docs: bring post-cut docs and flag help current for v0.13.3

.abcd/work/issues/resolved/iss-2610081312364884-post-cut-docs-currency-for-v0-13-3-launch-md-and-the.md

@@ -0,0 +1,23 @@
+---
+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"
+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

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

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`:

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-<n>): close its pull request, remove its worktree and branch
+      --discard string   discard a held lane (lane-<n>): remove its worktree and branch, then close its pull request
       --release string   land a held lane as it is (lane-<n>), 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)

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-<n>), once no lane has work left")
-	cmd.Flags().StringVar(&discard, "discard", "", "discard a held lane (lane-<n>): close its pull request, remove its worktree and branch")
+	cmd.Flags().StringVar(&discard, "discard", "", "discard a held lane (lane-<n>): remove its worktree and branch, then close its pull request")
 	return cmd
 }
 

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)")