openRepoTools becomes the openrepotools package: pipx installs the wheel with the whole payload, --install leaves pipx's link to pipx, --version names the release, and every count line says where the other commands come from (#228, PR 1 of 4)

openspec/changes/release-tags-pypi/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-17

openspec/changes/release-tags-pypi/clarifications.md

@@ -0,0 +1,147 @@
+# Clarifications
+
+_Captured during proposal council review. These constrain the design._
+_Generated by /opsx:propose council on 2026-10-17_
+
+The council reviewed `proposal.md` at `698cf30`. It had three read-only
+reviewers: the product advocate (PA), the systems architect (SA) and the
+adversary engineer (ADV). Lane openRepoTools-3, the lead, assigned the
+verdicts on 2026-10-17 at about 22:4xZ. Its nine VALID verdicts are applied
+to `proposal.md`, and its correction to the release owner's `LICENSE` check
+followed lane openRepoTools-1's D3 and D4 (#186 comment 6242560541). The
+five NOTED verdicts are below, and the three DISMISSED ones are at the end.
+
+## Council-Identified Constraints
+
+### N1: how the pipx link is detected
+
+**Raised by:** systems-architect (SA1) and adversary-engineer (ADV3)
+
+**Concern:** `plan_install_targets` runs first (`openRepoTools:1853`), and
+the `jq` check comes only later, in `plan_hook_merge` (`openRepoTools:1863`,
+its refusal at `:2500`). `unplaceable_kind` refuses every link, and the
+generic refusal prints `rm -f -- "<dir>/openRepoTools"` (`openRepoTools:2466`).
+On a machine with no `jq`, or under a future pipx metadata format, a
+detection that read `pipx_metadata.json` would fail. The person would then
+follow the printed `rm`, and nothing on `PATH` could run `--install` again.
+Reading that file in bash without `jq` would also mean writing a JSON
+parser: pipx writes it with sorted keys, so `injected_packages` comes before
+`main_package`, and `"package"` keys appear more than once.
+
+**Design impact:**
+- The detection is the proposal's path rule ("The pipx link is skipped"). It
+  derives everything from the resolved link and asks only whether files and
+  directories exist. It parses no JSON, needs no `jq`, and takes nothing
+  from the environment or from the entry module.
+- Moving the `jq` check ahead of `plan_install_targets` is the design's
+  call. If it moves, a missing `jq` refuses before any link advice is
+  printed.
+- The fixtures mirror the venv layouts of pipx 1.11.1, 1.17.8 and 1.18.3,
+  under each of the three pipx homes the proposal names.
+
+### N2: the grammar bash reads the stamp with
+
+**Raised by:** systems-architect (SA2) and adversary-engineer (ADV4)
+
+**Concern:** bash reads `_release.py` itself and trusts no environment
+variable for the stamp. So the file needs a reader that cannot be talked
+into a half-stamp, and that runs under the oldest bash the payload supports.
+
+**Design impact:**
+- The reader is a fixed grammar modelled on `pin_parse`
+  (`openRepoTools:458`). It reads lines, takes only the five names, and
+  never sources, imports or runs the file.
+- It refuses, each with its own reason:
+  - an unreadable file;
+  - a partial stamp, meaning one that breaks the proposal's all-or-nothing
+    rule;
+  - a malformed field.
+- It holds to bash 3.2: no `${x,,}`, `mapfile`, `declare -A` or `local -n`,
+  and an `awk -v` value carries one line only (AGENTS.md).
+- The release build's stamp writer and this reader must agree. A test passes
+  the writer's output through the reader.
+
+### N3: where the release notes live after the cutover
+
+**Raised by:** systems-architect (SA3)
+
+**Concern:** `docs/` goes to the spec leg
+(`openspec/changes/migrate-to-triad/adoption-plan.yaml:183-184`). A release
+step in the code leg that read `docs/release-notes/`, or a code-leg test of
+the notes, would read across legs, like the follow-ups the plan already lists
+(`adoption-plan.yaml:393-401`).
+
+**Design impact:**
+- There are two ways to meet the proposal's cutover invariant that no release
+  step reads across legs:
+  - the notes stay in `docs/release-notes/`, in the spec leg with `docs/`,
+    and `release.yml` reads none of them;
+  - or they move into the code leg, and the adoption plan carries an
+    exception.
+- The design chooses. **The default** is that no release step reads them,
+  and the GitHub Release links to them.
+- Lane openRepoTools-1's reading of the plan at openRepoShape v1.1.0 already
+  puts `docs/release-notes/` in spec (#186 comment 6242560541).
+
+### N4: the file modes in hatchling's wheel
+
+**Raised by:** systems-architect (SA4). The reviewer gave this point from
+memory and marked it unverified.
+
+**Concern:** the proposal's mode check (each packaged file's mode in the
+wheel equals the commit's `100755` or `100644`) assumes that hatchling
+1.27.0's reproducible wheel keeps 0644 and 0755.
+
+**Design impact:**
+- Check whether hatchling 1.27.0's reproducible wheel keeps 0644/0755. If it
+  does not, the installer must set each placed file's mode itself.
+- Either way, the design relies on the installer for modes, never on the
+  wheel. `--install` already sets 755 on each command it places, and 644 or
+  600 on the rest.
+- **Checked while writing this file.** In hatchling 1.27.0's published wheel
+  (sha256
+  `d3a2f3567c4f926ea39849cdf924c7e99e6686c9c8e288ae1037c8fa2a5d937b`),
+  `normalize_file_permissions`
+  (`hatchling/builders/utils.py:96-110`) maps any mode to 0644, or to 0755
+  when the owner's execute bit is set. The wheel builder applies it whenever
+  the target is reproducible (`hatchling/builders/wheel.py:97-101` and
+  `:140`), and `reproducible` defaults to true
+  (`hatchling/builders/config.py:377-383`). So the mode check can hold as
+  written. The design still relies on the installer.
+
+### N5: the wording of VALID 9's refusal and report, and how pip's script is recognised
+
+**Raised by:** adversary-engineer (ADV2)
+
+**Concern:** the proposal makes `--install` refuse to replace pip's console
+script for openrepotools, and makes a package-mode `--install` report when
+the first `openRepoTools` on `PATH` is not the package's console script.
+Neither line's text is fixed yet, and neither is the test that tells pip's
+script from any other regular file.
+
+**Design impact:**
+- The design fixes the exact text of the refusal and of the shadow report.
+  - The refusal names the file and says it is pip's console script for
+    openrepotools. It says nothing was installed, and names the way out.
+  - The report names the `openRepoTools` that `PATH` finds first, and the
+    console script it expected.
+- A console script is recognised by its shebang, a `#!` line naming a
+  Python, together with the import of the `openrepotools` entry point that
+  pip's console-script template writes.
+
+## Considered and dismissed
+
+These were raised and ruled out. The design does not reopen them.
+
+- **D1: a sixth `--version` line read from the receipt** (PA3's first
+  option). This would be a new capability, out of scope for v1.1.0. The
+  proposal's non-goal "`--version` names the command's release, not the
+  placed files'" covers it.
+- **D2: binding the stamp's environment variables to the payload
+  directory** (SA2's variant: pass the payload directory, compare it with
+  `pwd -P`, then unset the variables). Bash reading `_release.py` beside its
+  own payload replaces it, and leaves no environment surface at all.
+- **D3: having the entry module pass its venv to bash** (ADV3's
+  suggestion). It only works when the package itself runs. A checkout's or
+  the one-line install's `--install` must recognise pipx's link too, and the
+  proposal's path rule covers every mode.