v0.12.0 integration 24b3: the build loop lands and records, drain lanes, gitleaks opt-in, terminal check, record-lint edge and ADR-id rules, follow-ups

.abcd/config/reading-presets.json

@@ -60,10 +60,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1460000,
-        "measured_tokens_est": 1441769,
-        "measured_bytes": 5550812,
-        "measured_at": "a586d62ff35df482f45a93989466d3a4d1b230e4"
+        "tokens_est": 1480000,
+        "measured_tokens_est": 1463871,
+        "measured_bytes": 5635907,
+        "measured_at": "cb46dbea2c0eb37f4aa976f59046f785a32a86eb"
       }
     },
     "entailment": {
@@ -132,10 +132,10 @@
         "intent-projection"
       ],
       "window": {
-        "tokens_est": 420000,
-        "measured_tokens_est": 411876,
-        "measured_bytes": 1585724,
-        "measured_at": "a586d62ff35df482f45a93989466d3a4d1b230e4"
+        "tokens_est": 430000,
+        "measured_tokens_est": 418715,
+        "measured_bytes": 1612056,
+        "measured_at": "cb46dbea2c0eb37f4aa976f59046f785a32a86eb"
       }
     },
     "comparative": {
@@ -216,10 +216,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1470000,
-        "measured_tokens_est": 1450805,
-        "measured_bytes": 5585600,
-        "measured_at": "a586d62ff35df482f45a93989466d3a4d1b230e4"
+        "tokens_est": 1490000,
+        "measured_tokens_est": 1472907,
+        "measured_bytes": 5670695,
+        "measured_at": "cb46dbea2c0eb37f4aa976f59046f785a32a86eb"
       }
     }
   }

.abcd/development/brief/02-constraints/02-dependencies.md

@@ -42,6 +42,30 @@ they run behind the same seam and harden the scan; when absent, the native
 default still runs and still gates. Scanning never depends on a tool being
 installed.
 
+gitleaks is the one adapter wired. The scanner declares the seam it plugs into,
+`scanner.Augmenter` (`Available() error` and `Scan(text, file) []Finding`),
+and never imports gitleaks; the composition root (`cmd/abcd`) registers the
+gitleaks augmenter, and every scanner the core builds picks it up for the
+repository it scans. The opt-in is that repository's own
+`.abcd/config/gitleaks.json`: absent or `enabled: false`, nothing is looked up
+and nothing runs. Armed, gitleaks runs over every text the scanner reads —
+the launch payload, transcripts, issue captures, memory pages, the privacy
+lint's tracked files, a lifeboat's planned bytes — and its findings are appended
+to the native ones, deduplicated on file, line and span. Its output is untrusted
+input: a report is bounded in size and count, a finding is kept only when its
+bytes sit at the line and column it names, and the scanner rebuilds every other
+field itself, so a report or record carries the rule's kind and a masked
+fingerprint, never the value in clear. The binary runs in the isolated child
+environment every abcd subprocess gets, its own output discarded.
+
+Armed with no gitleaks binary installed is one state with one consequence per
+consumer. A release (`launch`) and a lifeboat (`disembark pack`) refuse on it,
+the privacy lint reports it as an error, and the write paths — transcript
+capture, issue capture, memory ingest — write with the native scanner and name
+the gap in their receipt. A gitleaks run that fails, a report the scanner cannot
+place, or a configured path the adapter refuses degrades the scanner instead:
+every consumer treats that as it treats a broken `pii.json`.
+
 ## Plugin interop
 
 abcd interoperates with peer tools — notably the companion harness

.abcd/development/brief/04-surfaces/01-ahoy.md

@@ -682,12 +682,16 @@ and notes the orphaned-predecessor possibility in the summary.
 
 **Bare `abcd ahoy`** prints the status board: the folder kind, plugin-root
 status, root SHA, install mode where one resolves, vintage and staleness, the
-citation baseline's coverage and age on a repo that has armed the citation gate,
-the gap count, and — on a repo — guard health and the banlist block with its
-reach, closing on a next-step line for the unmanaged kinds. In JSON form the
-same pass renders the detection envelope plus vintage and staleness, and the
-plugin command reads those two from exactly this render, so they are a contract
-with the plugin surface rather than a convenience.
+superseded-root note when the answering binary sits in a plugin root other than
+the one this session resolves, the citation baseline's coverage and age on a
+repo that has armed the citation gate, the gap count, and — on a repo — guard
+health and the banlist block with its reach, closing on a next-step line for the
+unmanaged kinds. In JSON form the same pass renders the detection envelope plus
+vintage and staleness, and `superseded_root` when the note applies; the plugin
+command reads those from exactly this render, so they are a contract with the
+plugin surface rather than a convenience. The note is the one the version flag
+carries, under the same conditions
+([`12-version.md`](12-version.md#a-superseded-plugin-root-names-itself)).
 
 **The dry run** renders the detection envelope as JSON and nothing else, so the
 plugin command can summarise state off the folder kind and the gaps and name

.abcd/development/brief/04-surfaces/02-disembark.md

@@ -91,6 +91,7 @@ DESTINATION SAFETY GATE
                            ▼
 SECRET SCAN (before any write)
   scan the planned bytes; a hard-fail secret refuses the whole pack — never redact
+  (an armed gitleaks scans them too; armed and not installed, it refuses the pack)
                            │
                            ▼
 WRITE

.abcd/development/brief/04-surfaces/04-launch.md

@@ -44,7 +44,10 @@ that bind a run to a plugin follow the kind. For a kind other than `plugin` the
 preview scans the tree the release tag would archive (`git archive`'s view of
 `HEAD`, `export-ignore` honoured, links excluded) minus the record namespace,
 denied by the same rule a plugin payload is held to, unless it declares an
-include set; the report names which tree it scanned. Its lockstep check reads
+include set; the report names which tree it scanned. In a repository that armed
+gitleaks, its findings join the scan's, and an armed gitleaks with no binary
+installed is an unscanned entry and a hard fail, so the preview and the cut
+refuse on it ([dependencies](../02-constraints/02-dependencies.md)). Its lockstep check reads
 the primary and every declared file, reads no plugin manifest, and refuses a
 declared file it cannot read. The rows that judge a plugin payload — the
 installability smoke and its deep tier, hook compliance, the parity diff — report

.abcd/development/brief/04-surfaces/05-intent.md

@@ -485,14 +485,15 @@ Both the press-release intent and the frozen PRD are immutable input artefacts p
 
 ## 6. Acceptance gates and bidirectional link verification
 
-`internal/core/lint` (cross-cutting; its shipped wiring is the docs currency lint and the `cmd/record-lint` gate) is the record-lint over the committed intent tree — it does not run inside planning; the acceptance-criteria refusal at plan time is the intent package's own `hasAcceptanceCriteria` check (`internal/core/intent`). The armed record-lint rules that bear on the intent tree are `intent_lifecycle` (the directory/kind/`spec_id` invariants and the `status:`-key ban below), `intent_impact_valid` (the `impact:` field's legal value set), `intent_sota` (a `planned/` intent carries a non-empty `## SOTA` declaration, armed at warn), `persona_registry` (press-release quote attributions resolve to the persona roster), `record_schema` (the `itd` store's filename↔id agreement, and `superseded_by` handle validity with two-way agreement across stores), `record_provenance` (the `origin`/`production_mode` disclosure pair and the `related_issues` back-edge), `spec_lifecycle` and `spec_id_unique` (the itd↔spc bidirectional agreement below, and the buckets' agreement: a planned intent has an open spec, and a shipped intent has none left open), and `delivery_state` (no CHANGELOG delivery entry, under `Added` or `Changed`, cites an intent still sitting in `drafts/`). The `IL0xx` codes per [`05-internals/06-lint.md`](../05-internals/06-lint.md) are plan-time design, a later phase.
+`internal/core/lint` (cross-cutting; its shipped wiring is the docs currency lint and the `cmd/record-lint` gate) is the record-lint over the committed intent tree — it does not run inside planning; the acceptance-criteria refusal at plan time is the intent package's own `hasAcceptanceCriteria` check (`internal/core/intent`). The armed record-lint rules that bear on the intent tree are `intent_lifecycle` (the directory/kind/`spec_id` invariants and the `status:`-key ban below), `intent_impact_valid` (the `impact:` field's legal value set), `intent_sota` (a `planned/` intent carries a non-empty `## SOTA` declaration, armed at warn), `persona_registry` (press-release quote attributions resolve to the persona roster), `record_schema` (the `itd` store's filename↔id agreement, and `superseded_by` handle validity with two-way agreement across stores), `record_provenance` (the `origin`/`production_mode` disclosure pair and the `related_issues` back-edge), `spec_lifecycle` and `spec_id_unique` (the itd↔spc bidirectional agreement below, and the buckets' agreement: a planned intent has an open spec, and a shipped intent has none left open), `delivery_state` (no CHANGELOG delivery entry, under `Added` or `Changed`, cites an intent still sitting in `drafts/`), and `stale_edge` and `edge_cycle` (the dependency edges below, armed at warn). The `IL0xx` codes per [`05-internals/06-lint.md`](../05-internals/06-lint.md) are plan-time design, a later phase.
 
 The invariants below are the contract the tree is held to, and each names what holds it. A bullet marked **(convention)** is practice the corpus follows by hand, with no shipped check behind it:
 
 - **Acceptance criteria present and well-formed** (per the itd-1 discipline): an intent cannot be planned without a `## Acceptance Criteria` section carrying at least one Given-When-Then bullet. The block is at plan time, not in the record-lint: the refusal is the intent package's own `hasAcceptanceCriteria` check on a draft, plus the `acceptance_criteria` row of the readiness gate. Everything in `planned/` and `shipped/` has therefore passed it. The two buckets the plan step never crosses are held by hand and are **(convention)**: a draft still on the bench may carry none, and so may a discipline, whose route into `disciplines/` does not run through planning at all. Both are true of this corpus today — four bench drafts and seven of the fourteen disciplines carry no section. No record-lint rule reads it, so a committed intent that lost one still passes the gate.
 - **A planned intent declares the state of the art** (per [sota-per-intent](../../principles/sota-per-intent.md)): a `## SOTA` section naming the existing alternatives, each one's rough maturity, and the path taken. `intent_sota` flags a `planned/` intent with no such section, or with a heading and nothing under it, at warn severity — the warn-first rung of a ratchet whose next rung is blocker once the planned bucket is back-filled. It judges presence, not the path's spelling, and reads neither `drafts/` (not yet shaped) nor `shipped/` (history, most of it older than the principle).
 - **`kind` is set on intents in `planned/`, `shipped/`, `disciplines/`, and `superseded/`.** Intents in `drafts/` may have `kind: null`. The shipped plan step neither infers a kind nor asks for one: it writes `standalone` wherever the draft left the field null, so `standalone` is what an unstated kind becomes. **A later phase** replaces that default with the proposal the user confirms or overrides (§ 1, "Later phase — plan grows a PRD-freeze front end and multi-kind dispatch"). What the record lint holds meanwhile is the value set per bucket: a draft's kind must be null, `standalone` or `bundle-member`, and a planned or shipped record's must be one of the latter two, non-null (`intent_lifecycle`).
 - **`kind: bundle-member` requires a `bundle:` field** pointing to a bundle ID; *all* members of a bundle reference the same bundle ID, and bundles are bidirectional in their members' frontmatter. `record_schema` refuses a bundle-member naming a bundle no other record names, unless its `reclassification_history` states the bundle now has one member (the survivor a supersession leaves); a bundle-member carrying no `bundle:` at all is **(convention)**, since both writers stamp the name and the shipped records without one are settled. **Exception for superseded bundle-members:** intents in `superseded/` with `kind_at_supersession: bundle-member` carry `bundle: null` AND `bundle_at_supersession: <bundle-id>` (preserves the bundle the intent was part of when retired, while signalling the bundle is no longer active); the reclassify verb writes both, and no lint reads `bundle_at_supersession`.
+- **A dependency edge names a live record, and the edges form no cycle.** `stale_edge` flags a `planned/` or `drafts/` intent whose `builds_on` or `blocked_by` names an intent in `superseded/`, one finding per edge, naming the record the superseded intent's chain ends at: the same walk along `superseded_by` the build's blocked check follows (`intent.SupersessionChainOf`), or why the chain cannot be finished. `edge_cycle` flags a cycle through `builds_on` and `blocked_by` together, across every intent not superseded, in one finding naming every record on it. Both are armed at warn, because this tree carries five findings that each wait on a decision rather than a repair: the drafts itd-22 (`blocked_by`) and itd-33 (`builds_on`) name itd-2, whose successor does not carry the in-session dispatch contract they depended on; itd-2609201916056194 and itd-2609201916151817 build on each other (iss-2609300848016421); and itd-14 and itd-15, and itd-2609081951381895 and itd-2609170822093401, build on each other (iss-2609300903551032). Both rules become blockers once those are decided.
 - **Bundle invariant: no member is blocked by another.** Planning several intents as a bundle refuses a member naming another member in `blocked_by`, naming the edge, before anything moves. See § 1 "Bundle invariant" for the canonical statement.
 - **`surface_history` entries are well-formed.** Every entry must include `date` (ISO YYYY-MM-DD), `from` (free-form surface descriptor), `to`, and `reason` (non-empty). Lint code `IL012` (severity: warn — it's an audit trail, not a gate). See itd-27's `surface_history` (skill → sub-verb on 2026-05-07) for a worked example.
 - **`kind: discipline` lives only in `disciplines/` or `superseded/`.** A discipline-kind record in `drafts/` is an error, caught by the record lint over the committed tree rather than at plan time: the `intent_lifecycle` drafts rule admits only a null, `standalone` or `bundle-member` kind, and the disciplines rule demands `discipline`. The gate is the commit, not the promotion.

.abcd/development/brief/04-surfaces/07-memory.md

@@ -100,7 +100,12 @@ stored text (`MR001`). `MR001` is the read side of the write-time redactor, run
 over every page, the source registry and each stored original, and over every
 page name, which it judges as the write side judges a filename: split into its
 parts and held to the hard-fail bar alone. It names the kind and the line, never
-the span, and the lint never rewrites the store.
+the span, and the lint never rewrites the store. The write-time redactor carries
+a repository's armed gitleaks (`.abcd/config/gitleaks.json`): its findings are
+masked with the native ones, a gitleaks run that fails refuses the ingest, and
+armed with no binary installed the ingest writes on the native scanner and its
+`scan_gap` names what is missing
+([dependencies](../02-constraints/02-dependencies.md)).
 
 Four of the seven can stop the run. `MR001` is the sharpest: residue in the
 store is a fault, never advice. `ML001` and `MS002` join it, because a source

.abcd/development/brief/04-surfaces/11-history.md

@@ -5,7 +5,10 @@ Every transcript that reaches the store has been redacted on write, so what
 accrues is a durable, searchable account of how a repo was built that is safe
 to keep, safe to read back, and safe to feed a later distiller. Capture is
 automatic: the session's end stages the transcript, the next session's start
-files it away.
+files it away. A repository that armed gitleaks (`.abcd/config/gitleaks.json`)
+has gitleaks' findings masked too; armed with no binary installed, the
+transcript is stored on the native scanner and the capture's `scan_gap` names
+what is missing ([dependencies](../02-constraints/02-dependencies.md)).
 
 The store is **user-level** and lives outside every repo at
 `~/.abcd/transcripts/<root-sha>/records/`, keyed on the repo's root-commit SHA.

.abcd/development/brief/04-surfaces/12-version.md

@@ -38,7 +38,10 @@ The version flag prints a short block: the version line, then `install:`
 read-only render of the binary's own state, not a board for the repository, and
 it answers alone: a record id beside the flag is refused rather than silently
 dropped. The JSON form emits the same facts as `name`, `version`, `vintage` and
-`staleness`, with `install_mode` present only when it resolves. The update
+`staleness`, with `install_mode` present only when it resolves, and
+`superseded_root` present only when the answering binary sits in a plugin root
+other than the one this session resolves (see *A superseded plugin root names
+itself* below); the plain render prints that note on a `note:` line. The update
 verb's check prints the same report with a `check` object added.
 
 When the online check finds an update, the answer carries the command that takes it,
@@ -83,6 +86,49 @@ renders stands in. When neither says anything, the framework's line stands
 byte-for-byte. The exit code, the stream and the JSON envelope are the
 framework's own.
 
+## A superseded plugin root names itself
+
+The two shapes above are loud: the binary is asked for something it does not
+have, so there is an error to hang a line on. A third shape has none. A plugin
+root is named for the commit it was installed from, so every update mints a new
+root and nothing prunes the old ones; a command page interpolates an absolute,
+hash-pinned binary path into its own prose, and that path is designed to
+expire. Between an update and the reload that re-interpolates it, following the
+page runs a superseded binary that is still on disk, answers normally — exit 0,
+no diagnostic — and reports a version that is true of that root and false of
+this machine (iss-2609020113012227, refining iss-2608230943088357).
+
+What the disk proves, with no network and no heuristic, is the divergence: the
+plugin root this session resolves — through the same ladder every other surface
+uses, which prefers the environment's own plugin-root variable over the
+executable's ancestors — against the plugin root the running binary sits in,
+found by that ladder's own executable-ancestor walk and layout check. When those
+are two different roots, the version flag's report (and the update verb's check,
+which extends it) and bare `ahoy` add a `superseded_root` note naming both roots
+by the commit each was installed from, in the plain render as well as in the
+JSON form. It is a note beside the answer: the reported version, vintage and
+staleness are unchanged, and nothing refuses.
+
+The two names are directory names read off the disk, so each passes through the
+terminal sanitiser before it is printed: a control or bidirectional character in
+one is replaced, never rendered. The command pages tell the agent to relay the
+note as abcd printed it and never to rebuild the names from a path, which would
+undo that.
+
+The note is silent in three cases. A binary inside no plugin root at all — a
+PATH copy, a `go run` build — has no superseded root to name, and the vintage
+comparison already covers it. A binary in the root this session resolves has
+nothing to disclose. And a binary served from a source checkout of abcd says
+nothing: a checkout is a valid plugin root (`hooks/` sits at its top), so a
+developer running the `make build` artefact while a harness session resolves its
+own cache root satisfies the divergence test, but a checkout is not named for a
+commit it was installed from, and the note's remedy would point at the
+plugin-root binary the dogfooding rule calls the stale one. That case is the
+vintage comparison's, and the stale-binary line above keys its rebuild remedy on
+the same source-checkout test. The guard is keyed on the root that served the
+answer: a provisioned root answering into a session whose own root is a source
+checkout still names itself.
+
 ## Where the version comes from
 
 The version is **derived, never hand-authored**: it is read from the shipped