From afa6e7b169abf9f840a8e5cf7b6bd8af07bbbf6a Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:12:45 +0100 Subject: [PATCH 1/2] docs: bring post-cut docs and flag help current for v0.13.3 The v0.13.3 cut's docs review deferred five findings. launch.md and the --allow-dirty flag help now name the findings gate's refusal of an uncommitted issue record under open/ (and the help names the cut's uncommitted-records refusal), neither of which the flag waives. prepare-this-repo sets a local core.hooksPath only when the clone reads unarmed and leaves a foreign hooks path alone, and names .abcd/record-lint.json in full. The implement step --discard help now gives the order the code runs: worktree and branch first, then the pull request. The CLI reference is regenerated. Refs: iss-2610081312364884 Assisted-by: Claude:claude-opus-5-5 --- ...-currency-for-v0-13-3-launch-md-and-the.md | 15 +++++++++++ commands/launch.md | 18 ++++++++++--- commands/prepare-this-repo.md | 27 ++++++++++++++----- docs/reference/cli/commands.md | 4 +-- internal/surface/cli/build.go | 2 +- internal/surface/cli/ship.go | 3 ++- 6 files changed, 55 insertions(+), 14 deletions(-) create mode 100644 .abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md diff --git a/.abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md b/.abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md new file mode 100644 index 000000000..222152940 --- /dev/null +++ b/.abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md @@ -0,0 +1,15 @@ +--- +schema_version: 1 +id: "iss-2610081312364884" +slug: "post-cut-docs-currency-for-v0-13-3-launch-md-and-the" +severity: "minor" +category: "documentation" +source: "review-followup" +found_during: "manual-capture" +origin: researcher-authored +production_mode: hand-written +found_at: "commands/launch.md" +remedy: "Document the open-records refusal in launch.md and the --allow-dirty help, condition the hooksPath step on unarmed, correct the record-lint path and the --discard help order" +--- + +Post-cut docs currency for v0.13.3: launch.md and the --allow-dirty help omit the open-records refusal, prepare-this-repo shadows a foreign hooks path and names a bare record-lint.json, and implement step --discard help misorders its steps diff --git a/commands/launch.md b/commands/launch.md index 903298d94..edbf0b737 100644 --- a/commands/launch.md +++ b/commands/launch.md @@ -431,9 +431,9 @@ Exit codes gate the flow: Every refusal names the specific record, version, or surface that blocks it — a release in flight, a record move left uncommitted (`uncommitted-records`), a merged feature whose intent still sits in `planned/`, a missing surface - baseline, a surface break with no `breaking` record, or a - consequential finding this cycle captured and never answered (see *The - findings gate* below). A refusal is a result to relay, not a crash, and not + baseline, a surface break with no `breaking` record, a + consequential finding this cycle captured and never answered, or an open + issue record left uncommitted (see *The findings gate* below). A refusal is a result to relay, not a crash, and not something to work around. - **2** — a structural fault (the repository could not be read). Relay it and stop. @@ -479,6 +479,14 @@ to read. Every other route leaves a trace the next reader can follow; this one leaves nothing to audit, which is why it is named separately: the record has to come back before it can be resolved, wontfixed or deferred. +**An uncommitted open record refuses too**, under `unfixed-finding`. The gate +reads the ledger at HEAD, so it cannot judge a finding captured, regraded, +deferred or removed in the working tree: whenever any issue record under +`.abcd/work/issues/open/` differs from HEAD — added, edited, deleted or only +staged, at any severity — the cut refuses and the `reason` names every path. +`--allow-dirty` never waives it, because the gate would still read HEAD. Commit +the records (or discard the change) and run again. + The anchor is what bounds it. Records that already existed at the last tag are the standing backlog and are never this cut's to answer; only what this cycle itself captured is in scope. "It was already there when I started" is therefore @@ -655,7 +663,9 @@ ship is passed `--allow-dirty`, which carries them into the cut and records the override, with every path it carried, in the report (`allowed_dirty` in `--json`). The flag waives the dirty-tree gate and nothing else: never lockstep, never the archive pin's refusal of an uncommitted payload file, and never the -cut's own `uncommitted-records` refusal (step 1). On a ship +cut's own `uncommitted-records` refusal (step 1), and never the findings +gate's refusal of an uncommitted record under `.abcd/work/issues/open/` +(`unfixed-finding`; see *The findings gate*). On a ship that renders nothing it is an operand error, because there is no gate to waive. Relay the refusal and let the user decide; do not add `--allow-dirty` on their behalf. The ship's report, its `--json` (`parity`, `deep_smoke`) and its diff --git a/commands/prepare-this-repo.md b/commands/prepare-this-repo.md index e86bd3faa..740301383 100644 --- a/commands/prepare-this-repo.md +++ b/commands/prepare-this-repo.md @@ -55,7 +55,7 @@ Read from `$ABCD`, delegating heavy reading to subagents where available: `planned/` → `shipped/` → `superseded/`). - `docs/README.md` — strict Diátaxis, four directories, present tense only, user-facing only. -- `.abcd/docs-lint.json` and `record-lint.json` — study as patterns +- `.abcd/docs-lint.json` and `.abcd/record-lint.json` — study as patterns (banned-token rules with severity, fix message, `allow_context` escapes). - `.abcd/.work.local/private-names.txt` — **if present**: the banlist for the Phase 2 privacy audit. Its contents are read-only context; never reproduce @@ -191,15 +191,30 @@ target's `.abcd/.work.local/scratch/` (create the directory via ```bash "${CLAUDE_PLUGIN_ROOT}/abcd" ahoy install - git config core.hooksPath .githooks ``` That writes the committed private name guard (`.githooks/pre-commit` and its `pre-merge-commit` half), the gitignored local banlist stub, and the - `.gitattributes` line pinning the hooks to LF. The second command is once per - clone: a committed hook is not a running hook until git is pointed at it. - Report the hooks as scaffolded but unarmed if the user declines that config - change — never silently. + `.gitattributes` line pinning the hooks to LF. A committed hook is not a + running hook until git is pointed at it, so read which hooks directory git + runs in this clone from the detection pass + (`"${CLAUDE_PLUGIN_ROOT}/abcd" ahoy --json`, `banlist.hooks_path`) and act + on it: + + - `unarmed` — point git at the committed hooks, once per clone: + + ```bash + git config core.hooksPath .githooks + ``` + + Report the hooks as scaffolded but unarmed if the user declines that + config change — never silently. + - `foreign` — a hooks path set outside the clone (a global or system hooks + dispatcher) is in force. Leave it alone: never set a local + `core.hooksPath` over it, which would shadow the dispatcher in this clone. + Tell the user the dispatcher has to call the hook in `.githooks/` for the + guard to run, as `/abcd:ahoy` says. + - `armed` — nothing to do. 6. **Attribution (opt-in only).** If the user says this repo requires AI disclosure, scaffold the prompt hook from the binary and add the attribution section to `AGENTS.md`: diff --git a/docs/reference/cli/commands.md b/docs/reference/cli/commands.md index 99254103a..c227b06ea 100644 --- a/docs/reference/cli/commands.md +++ b/docs/reference/cli/commands.md @@ -2083,7 +2083,7 @@ refusal, exit 3 on a pause or a locked run state. **Flags:** ``` - --discard string discard a held lane (lane-): close its pull request, remove its worktree and branch + --discard string discard a held lane (lane-): remove its worktree and branch, then close its pull request --release string land a held lane as it is (lane-), once no lane has work left --run string the run to step (run-<16 digits>); the one run in progress when omitted ``` @@ -2672,7 +2672,7 @@ Cut a release, deriving its version and records from what shipped: Writes the CH **Flags:** ``` - --allow-dirty cut from a working tree with uncommitted changes; the pre-flight report records the override and every path it carried (waives the dirty-tree gate only — never lockstep, and never the archive pin's clean-payload refusal) + --allow-dirty cut from a working tree with uncommitted changes; the pre-flight report records the override and every path it carried (waives the dirty-tree gate only — never lockstep, the archive pin's clean-payload refusal, the cut's uncommitted-records refusal, or the findings gate's refusal of an uncommitted open/ issue record) --changelog-json string path to the host-composed changelog JSON (or - for stdin); absent runs the deterministic emit step --fetch-baseline read the parity baseline from the anchor tag's published plugin archive, verified against the release's checksums.txt (a network fetch; default: a fresh render at the tag) --payload-dir string stage the versioned release payload in this directory (must be empty and outside the repository) diff --git a/internal/surface/cli/build.go b/internal/surface/cli/build.go index 57d313c99..02726fac8 100644 --- a/internal/surface/cli/build.go +++ b/internal/surface/cli/build.go @@ -706,7 +706,7 @@ func newImplementStepCommand(asJSON *bool) *cobra.Command { } cmd.Flags().StringVar(&runID, "run", "", "the run to step (run-<16 digits>); the one run in progress when omitted") cmd.Flags().StringVar(&release, "release", "", "land a held lane as it is (lane-), once no lane has work left") - cmd.Flags().StringVar(&discard, "discard", "", "discard a held lane (lane-): close its pull request, remove its worktree and branch") + cmd.Flags().StringVar(&discard, "discard", "", "discard a held lane (lane-): remove its worktree and branch, then close its pull request") return cmd } diff --git a/internal/surface/cli/ship.go b/internal/surface/cli/ship.go index bfbcb4a0c..90407eea7 100644 --- a/internal/surface/cli/ship.go +++ b/internal/surface/cli/ship.go @@ -456,7 +456,8 @@ func newLaunchShipCommand(asJSON *bool) *cobra.Command { "stage the versioned release payload in this directory (must be empty and outside the repository)") cmd.Flags().BoolVar(&allowDirty, "allow-dirty", false, "cut from a working tree with uncommitted changes; the pre-flight report records the override and every path it carried "+ - "(waives the dirty-tree gate only — never lockstep, and never the archive pin's clean-payload refusal)") + "(waives the dirty-tree gate only — never lockstep, the archive pin's clean-payload refusal, the cut's uncommitted-records "+ + "refusal, or the findings gate's refusal of an uncommitted open/ issue record)") cmd.Flags().BoolVar(&fetchBaseline, "fetch-baseline", false, "read the parity baseline from the anchor tag's published plugin archive, verified against the release's checksums.txt "+ "(a network fetch; default: a fresh render at the tag)") From 2d0efb0e07685bcfac18ca520dc34cf429ed7943 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:13:01 +0100 Subject: [PATCH 2/2] docs: resolve the v0.13.3 post-cut docs currency issue Moves the issue to resolved/, pointing at the commit that brought launch.md, prepare-this-repo.md and the --allow-dirty and --discard flag help current with the code. Resolves: iss-2610081312364884 Assisted-by: Claude:claude-opus-5-5 --- ...ost-cut-docs-currency-for-v0-13-3-launch-md-and-the.md | 8 ++++++++ 1 file changed, 8 insertions(+) rename .abcd/work/issues/{open => resolved}/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md (57%) diff --git a/.abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md b/.abcd/work/issues/resolved/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md similarity index 57% rename from .abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md rename to .abcd/work/issues/resolved/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md index 222152940..de22e9c25 100644 --- a/.abcd/work/issues/open/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md +++ b/.abcd/work/issues/resolved/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md @@ -10,6 +10,14 @@ origin: researcher-authored production_mode: hand-written found_at: "commands/launch.md" remedy: "Document the open-records refusal in launch.md and the --allow-dirty help, condition the hooksPath step on unarmed, correct the record-lint path and the --discard help order" +resolution: "launch.md and the --allow-dirty help name the findings gate's open/ records refusal (and the help the cut's uncommitted-records refusal); prepare-this-repo conditions the hooksPath step on unarmed and names .abcd/record-lint.json; the --discard help gives the code's order" +impact: fix +resolved_by: + commit: "afa6e7b169abf9f840a8e5cf7b6bd8af07bbbf6a" --- Post-cut docs currency for v0.13.3: launch.md and the --allow-dirty help omit the open-records refusal, prepare-this-repo shadows a foreign hooks path and names a bare record-lint.json, and implement step --discard help misorders its steps + +## Grounds + +- pursued: the five deferred v0.13.3 docs-currency findings now match the code; a docs review that still finds one of them stale would show this wrong