@erclx/aitk 3.3.0 → 3.5.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/SKILL.md

@@ -40,7 +40,7 @@ No surface carries cross-version sequencing, so report none. A row's `Waiting on
 
 A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
 
-On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It captures what the session learned, then writes a session map per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, carrying the state of play, the mistakes worth not repeating, and the standing cautions, with the decisions taken under delegated authority added as this role's extension. That capture is the only one this session runs, since the refill sweep reports it as owed rather than paying it. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `aitk:session-map`, which captures what the session learned and writes a session map per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, then adds the decisions taken under delegated authority as this role's extension. That capture is the only one this session runs, since the refill sweep reports it as owed rather than paying it. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
 On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
 

package/claude/skills/claude-orchestrate/references/orchestrator-handoff.md

@@ -3,9 +3,11 @@ title: Orchestrator handoff runbook
 description: The two sections an orchestrating session adds over the shared session map, how capture runs from a session that never commits, and the resume invocation the file carries out
 ---
 
-Write the pre-compaction handoff as orchestrator. Follow `${CLAUDE_SKILL_DIR}/../../standards/session.md` for the filename, the three core sections, the write procedure, and the citation rule. Everything below is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
+Write the pre-compaction handoff as orchestrator. Invoke `aitk:session-map` for the generic half, which is the filename, the three core sections, the write procedure, the drift step and the ref it reads, and the citation rule. Everything below is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
 
-1. Run the capture step the core opens with, and tell `aitk:claude-memory-capture` that this session does not commit.
+Settle all three steps below before the door writes, so one write carries the core and the extension together. The door reports the map as written and knows nothing of this role, so its success line ends the generic half rather than this runbook, and a session that stops there ships a map missing both of the things this file exists to add.
+
+1. Tell the door this session does not commit, which is the caveat its capture step takes and passes to `aitk:claude-memory-capture`.
 2. Add `## Decisions taken under delegated authority` directly after `## State`, holding each decision and why it went that way, so nobody re-proposes it. It sits there rather than after the core because a decision is read against the state it was taken in.
 3. Close the file with the block below, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
 
@@ -25,6 +27,6 @@ The requirement is a resume request to the orchestrator skill with that skill lo
 
 Step 1 exists because both other callers of capture are ship-chain skills and this session never ships. Without a call here, the session that receives every operator correction is the one session that records none. A compaction arriving with no warning takes the capture with it, and firing it once per batch of merges leaves the same window open across a long planning stretch, since a sweep runs only on a merge. The refill sweep reports the debt between handoffs so the operator knows one is owed.
 
-Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work.
+Step 1 varies the door rather than replacing it, which is why the door is invoked first and this runbook states only what differs. The generic half moved out whole, the drift step and its ref recovery with it, so nothing here restates a step the door already carries and the two cannot disagree.
 
-The core's drift step answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.
+Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work.

package/claude/skills/session-map/REQUIREMENT.md

@@ -0,0 +1,57 @@
+---
+name: session-map
+description: Why the write procedure needs a route any session can take, why the door carries the drift step and its ref recovery, and why it states none of the shape the standard already fixes
+---
+
+# Session map requirement
+
+## Gap
+
+Without this skill, the standard governing the pre-compaction handoff carries a complete numbered write procedure and nothing routes a session to it. The reading half already works, since the resume path opens the newest map and leads its report with it, so a file nobody is routed to write is read by a surface built to find it.
+
+The only routed writer belongs to the orchestrator role. It disables model invocation, asserts that role on invocation, and adds a section for decisions taken under delegated authority, so a plain feature session that reaches it receives a section it cannot fill and a review poll it does not run.
+
+The nearest description by wording writes a different artifact. Capture routes facts to a context entry and writes memory files, and a request naming the session and the moment matches it, so the map goes unwritten while a session believes it has handed off.
+
+The drift step is the one most specific to session length and the easiest to skip. It reads the commit the session started from, nothing on the machine records that commit, and a route that names the step without naming how to recover the ref ships an instruction nobody can follow.
+
+A step that reads a surface a project may not carry gets skipped on the reasoning that it has nothing to act on. A cold session run against a project with no `.claude/` tree skipped both the capture and the drift step and wrote its own rationale into the map, so the step the route exists to carry did not run on the first test from outside. The skip is worst where it looks most defensible, and a session that takes it quietly leaves a map indistinguishable from a conforming one.
+
+A capture fired the same way for every caller breaks the one caller the split leaves. An orchestrating session may write no tracked file, so its capture has to skip routing, and a route offering no way to say so leaves that reader running capture twice or routing facts the role forbids it to fold.
+
+A body that restates the sections, the frontmatter, or the numbered steps becomes a second source that drifts from the standard, which is the failure the split between the role writer and the core was made to remove rather than move.
+
+## Must
+
+- Write from any session whatever role it holds, without asserting one
+- Cite the standard for the filename, the frontmatter, the sections, the numbered procedure, and the citation rule rather than restating any of them
+- Run the drift step and state how to recover the ref it reads from how long the session has run
+- Record what the drift verb names, and read a refusal as the boundary of what the verb can read
+- Resolve the folder at the main worktree root, and write the file whole from the shell where the editing tools refuse that root
+- Fall back to the branchless filename on an empty slug rather than stopping
+- Leave model invocation enabled, so a session that has dropped its routing still reaches this by description
+- Take a caller's statement that the session does not commit and pass it to capture, so no fact this route fires is routed into a tracked file
+- Report the map alone, plus the line capture returns when a fact routed, since a fold left unreported is a fold nobody runs
+
+## Must not
+
+- Restate the standard's sections, frontmatter, or numbered steps
+- Skip a step by predicting what its skill or verb would have answered, rather than running it and recording what came back
+- Assert a role, or add a role's section to a map written by a session holding no such role
+- Fold the capture step's output into this skill's report
+- Take the worktree-local copy the editing tools offer in place of the main-root path
+- Summarize the board, the task files, or the work that shipped, each of which is carried by an artifact a compaction leaves standing
+
+## Guards
+
+- Not a git repository: stop, since the filename comes from the branch
+- Empty slug: fall back rather than stop, since the reasoning is worth more than the name
+- The drift verb refusing: record the boundary under standing cautions and keep writing
+
+## Out of scope
+
+- Reading a handoff back at the start of the next session: `session-resume`
+- Routing a session fact to the context entry that owns it, and writing what no entry owns to the memory folder: `claude-memory-capture`
+- The sections a role adds over the core three, which belong to that role's own surface. `claude-orchestrate` owns the orchestrator's and cites this route for the generic half.
+- Validating a written map against the standard, which no record kind covers, so a conforming shape rests on the standard being followed
+- Firing the write without being asked, which is a question about what the harness supports and is measured on its own track

package/claude/skills/session-map/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: session-map
+description: Writes the session map, the pre-compaction handoff at `.claude/tasks/session-<slug>.md`, from any session whatever role it holds, running the skill-drift step the write procedure opens with. Use when asked to "write the handoff", "write the session map", "save the session before it compacts", "we are about to compact", "hand off to the next session", or "leave a note for whoever picks this up". Do NOT use to route session facts to a context entry or the memory folder, which is `claude-memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+---
+
+# Session map
+
+Write the pre-compaction handoff for the current session. `${CLAUDE_SKILL_DIR}/../../standards/session.md` fixes the filename, the frontmatter, the three core sections, the numbered write procedure, and the citation rule. Follow that document rather than this body, which states when the procedure runs and what it runs against and leaves the shape where it already lives.
+
+Any session writes one. Do not assert a role on invocation, and do not add a role's sections to a map written by a session holding no such role.
+
+Run every step rather than judging in advance that one has nothing to act on. The capture skill and the drift verb each answer for themselves, refusal included, and a refusal recorded is a result where a prediction of one is not. A project carrying none of the scaffolding either step reads is the case this fires on, and it is the case where skipping looks most defensible.
+
+## Guards
+
+- If `git rev-parse --git-dir` does not resolve, stop: `❌ Not a git repository. A session map takes its filename from the branch.`
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls back to `latest` rather than stopping, since a handoff is scratch and a stop loses the reasoning the file exists to save.
+- Resolve the containing folder at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The guard above already stopped where that read has no repository to answer from, so it takes no fallback.
+
+## Step 1: run the capture the procedure opens with
+
+Item 1 of `## Writing one` is a capture. Invoke `aitk:claude-memory-capture` and let it return before writing, so the map cites what was written instead of restating the same lesson in prose.
+
+Pass on the caveat a caller states about committing. A caller that does not commit says so, and capture then skips routing and writes memory files alone, since a routed fact lands in a context entry and that is a tracked file. A caller stating nothing leaves capture to decide for itself, which is the ordinary run.
+
+Carry through the line capture returns when a fact routed, so the session knows a fold is still owed. Report nothing else about what it wrote. The map is this skill's output.
+
+## Step 2: recover the commit the drift step reads
+
+Item 2 runs `aitk claude skills drift <ref>` against the commit this session started from, and nothing on the machine records that commit. Estimate how long the session has run, round the duration up, and read the ref item 3 recovers:
+
+```bash
+git log -1 --format=%H --before='<duration> ago'
+```
+
+Round up rather than down. A ref older than the oldest load over-reports, and confirming a name it raises costs one read of that body, so the generous end is the safe one.
+
+Record what the verb names under `## Standing cautions`. A refusal is the boundary of what the verb can read rather than a fault, since it answers where the working directory carries `claude/skills/` with history behind it and refuses in a project consuming the plugin from a cache. Record the boundary the verb reported and keep writing, rather than the one it looked likely to report.
+
+## Step 3: write the map
+
+Follow items 4 through 6. Write only what a compaction destroys and no other artifact already carries, and cite a commit, a task, or a file and line for every claim.
+
+The file sits at the main worktree root, which the file-editing tools refuse from inside a linked worktree while offering a copy under that worktree instead. Take neither the refusal nor the copy. The map is written whole every time, so send it out as one plain shell command carrying a heredoc.
+
+## Step 4: extend it only where a role is held
+
+`## Extending it` governs a section added over the core three. Add one only when this session holds the role and the surface owning that role states the section, since a section the writer cannot fill teaches its reader to skip the file. A session holding no role writes the core three and stops.
+
+## Output
+
+```plaintext
+✅ Session map written: .claude/tasks/session-<slug>.md
+<what the drift verb named, or the boundary it refused at>
+```
+
+Emit the path from the project root. The `## Output` section of the project's instruction file sets the form it takes.

package/docs/agents/commands.md

@@ -48,6 +48,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
 | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                    |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
+| `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
 | `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
 | `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                  |
@@ -65,7 +66,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                      |
 | `snippets`  | `list`, `install`, `sync`, `create`                                                                         |
 | `standards` | `list`, `<name>`                                                                                            |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`                                                   |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                     |
 | `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
 | `wiki`      | `init`                                                                                                      |
 | `design`    | `render`                                                                                                    |

package/docs/agents/index.md

@@ -29,6 +29,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
+- [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates

package/docs/agents/superseded.md

@@ -0,0 +1,57 @@
+---
+title: Superseded values
+description: Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates
+---
+
+# Superseded values
+
+`aitk gov superseded <superseded> <replacement>` reports where the tree still asserts a value the convention behind it no longer produces. It answers the case a diff cannot: a convention changes, and the declarations testing it keep asserting the old form with nothing pointing at them.
+
+```bash
+aitk gov superseded feature-feat- feature-
+aitk gov superseded feature-feat- feature- --json
+aitk gov superseded old-name new-name --root ../my-app
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | Tree to read, defaulting to the current directory          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## Why the value is the key
+
+A file-scoped map from the changed rule to what cites it reaches nothing here. A fixture asserting an old output names neither the rule nor the standard behind it, so the change that superseded the value touches no file the fixture can be found from. The value both sides carry is the only key there is.
+
+The slug transform is what proved it. Dropping the type segment left four fixtures and three scenario scripts asserting the type-carrying spelling. One surfaced as a red sandbox arm, which named a failing scenario rather than a stale declaration, and the other six were found by deriving from the rule rather than by anything reporting them.
+
+## What it reads
+
+The whole corpus git lists: tracked files plus untracked ones git does not ignore. The untracked half keeps a file added on this branch in scope rather than one push later.
+
+Matching is a literal substring, so a value carrying regular-expression characters means what it says. Every occurrence on a line reports under its own column, since a line carrying the value twice is two edits.
+
+Binary files are skipped on a NUL byte rather than on an extension list, and so is any listed path that will not open. Both are counted. A run states the files it opened against the files git listed, because a count of what passed reads as a verdict on the repository unless it also says how much it left out.
+
+Pass an empty replacement to retire a value outright, as in `aitk gov superseded feature-feat- ""`. Findings report the same way and none is annotated, since a line cannot carry a replacement that does not exist.
+
+## The exemption marker
+
+A declaration disagreeing with a convention for a stated reason carries `aitk-allow-superseded: <reason>` on its own line or the one directly above. The marker moves the line into the report's `Exempt` section, which is named rather than counted, so a reader weighing the report can reach the reason.
+
+Only a marker naming a reason counts. A bare token is a line that meant to say something and did not, and honoring it would let a typo mute a finding. This is the `aitk-allow-secret` shape, and both read the same placement rule through one helper.
+
+## The blind spot
+
+The sweep sees the value and nothing else. A prose reference that went stale without carrying it is invisible here, which is not hypothetical: alongside the mechanical instances, one declaration had gone stale by citing the wrong standard for the transform, and it matches no string this sweep could have been given.
+
+A value sweep closes most of this class and no part of that one. The help text and the frame say so on every run, so a clean report is not read as a clean tree.
+
+## Exit codes
+
+Exit codes are `0` when nothing asserts the superseded value, `1` for a refusal, and `2` for at least one finding. It refuses an empty superseded value, which would match every line rather than a convention, a superseded value equal to its replacement, which means no convention changed, and a tree git cannot list, since an empty list passes each of its zero files. An empty replacement is not among them, because retiring a value is an ordinary reason to run this.
+
+Nothing wires this into `bun run check` or into a hook. A value sweep over-reports by construction, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `aitk gov test-order` is the sibling precedent.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the JSON record's `findings` array rather than the exit when a skill consumes this.

package/docs/ai-workflow.md

@@ -250,6 +250,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | ------------------------- | ------------------------------------------------------------------------------ |
 | `aitk:claude-orchestrate` | To assert the control session that owns the queue and reviews each worker's PR |
 | `aitk:session-resume`     | At the start of a session, to pick up what a previous one left                 |
+| `aitk:session-map`        | At the close of a session, to write the handoff a compaction would destroy     |
 
 ### Keep the project current with the toolkit
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/binary.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether the bytes are something a line scanner should not read.
+ *
+ * A NUL byte rather than an extension list, since a shipped tree carries fonts
+ * and images under names no scanner has reason to enumerate, and a list would
+ * go stale the first time a format was added. Decoded text holds no NUL, so the
+ * test costs one scan and never rejects source.
+ *
+ * Neutral rather than owned by either sweep that calls it. The secret scan
+ * shaped it and the superseded-value sweep reads the same corpus, so leaving it
+ * in `src/secrets/` would put a `src/gov/` dependency on the secret scanner for
+ * a predicate about bytes.
+ */
+export function isBinary(text: string): boolean {
+  return text.includes('\0')
+}

package/src/commands/gov.ts

@@ -14,6 +14,12 @@ import {
   mergeExtraRules,
   resolveRules,
 } from '@/gov/stacks'
+import {
+  readSuperseded,
+  SUPERSEDED_MARKER,
+  type SupersededHit,
+  type SupersededReport,
+} from '@/gov/superseded'
 import {
   type PairRecord,
   readTestOrder,
@@ -57,6 +63,11 @@ interface TestOrderOptions {
   readonly json?: boolean
 }
 
+interface SupersededOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -180,6 +191,141 @@ export function register(program: Command): void {
     .action((opts: TestOrderOptions) => {
       process.exitCode = runTestOrder(opts)
     })
+
+  gov
+    .command('superseded')
+    .description(
+      'Report where the tree still asserts a value a changed convention no longer produces',
+    )
+    .argument('<superseded>', 'The value the convention used to produce')
+    .argument('<replacement>', 'What it produces now')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Keyed on the value rather than on the file stating the rule. A fixture',
+        'asserting an old output names neither the rule nor the standard behind',
+        'it, so a file-scoped map from the changed rule reaches none of them and',
+        'the value both sides carry is the only key there is.',
+        '',
+        'It reports and never gates. A string appears for reasons unrelated to',
+        'the convention, so the output is a reading rather than a verdict, and a',
+        'declaration disagreeing for a stated reason carries a',
+        `\`${SUPERSEDED_MARKER}: <reason>\` marker on its own line or the one above.`,
+        '',
+        'Pass an empty replacement to retire a value outright. Findings report',
+        'the same way and none is annotated, since a line cannot carry a',
+        'replacement that does not exist.',
+        '',
+        'Blind spot:',
+        '  a prose reference that went stale without carrying the value, such as',
+        '  a declaration citing the wrong standard for the transform, matches',
+        '  nothing here and is reached by reading rather than by this sweep',
+        '',
+        'Exit codes:',
+        '  0  nothing in the corpus asserts the superseded value',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one declaration still asserts it',
+        '',
+        'Examples:',
+        '  aitk gov superseded feature-feat- feature-',
+        '  aitk gov superseded feature-feat- feature- --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        superseded: string,
+        replacement: string,
+        opts: SupersededOptions,
+      ) => {
+        process.exitCode = await runSuperseded(superseded, replacement, opts)
+      },
+    )
+}
+
+/**
+ * Reports and never gates, matching `test-order` above. The finding count moves
+ * the exit code with nothing wiring it into a push, since a value sweep
+ * over-reports by construction and gating a measure carrying a known
+ * false-positive class is what teaches contributors to route around a stage.
+ */
+async function runSuperseded(
+  superseded: string,
+  replacement: string,
+  opts: SupersededOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = await readSuperseded(root, { superseded, replacement })
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('aitk gov superseded')
+    logStep('Refused')
+    logError(report.reason)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportSuperseded(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ok: true, root, ...report })}\n`)
+  }
+
+  return report.findings.length > 0 ? 2 : 0
+}
+
+function describeHit(hit: SupersededHit): string {
+  const note = hit.carriesReplacement
+    ? ' (the replacement is on this line)'
+    : ''
+  return `${hit.file}:${hit.line}:${hit.column}${note}: ${hit.preview}`
+}
+
+function reportSuperseded(
+  report: Extract<SupersededReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov superseded')
+
+  logStep('Sweep')
+  logInfo(`${report.superseded} → ${report.replacement} in ${root}`)
+
+  logStep(report.findings.length === 0 ? 'Clean' : 'Findings')
+  if (report.findings.length === 0) {
+    logInfo('nothing in the corpus asserts the superseded value')
+  } else {
+    for (const finding of report.findings) logWarn(describeHit(finding))
+  }
+
+  // Named rather than counted. A muted line is a judgment someone recorded,
+  // and a reader weighing this report has to be able to reach the reason.
+  logStep('Exempt')
+  if (report.exempt.length === 0) {
+    logInfo('no line carries a marker')
+  } else {
+    for (const hit of report.exempt) logInfo(describeHit(hit))
+  }
+
+  // A count of what passed reads as a verdict on the repository unless the run
+  // also says how much of it the corpus left out.
+  logStep('Corpus')
+  logInfo(
+    `${report.files} file(s) opened of ${report.listed} listed, ${report.skipped} skipped as binary or unreadable`,
+  )
+
+  outro()
 }
 
 /**

package/src/exempt-marker.ts

@@ -0,0 +1,43 @@
+/**
+ * Escapes every character a regular expression would read as syntax.
+ *
+ * The token became a parameter when this was extracted, and the two callers
+ * pass letters and hyphens alone. That is what makes escaping cheap here rather
+ * than a fix for a live defect: an unescaped token holding a dot matches the
+ * wrong lines and one holding a parenthesis throws, and neither failure is the
+ * caller's to anticipate.
+ */
+function escapeForPattern(token: string): string {
+  return token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Whether the line at `index` carries `token` with a reason after it, reading
+ * itself and the line above.
+ *
+ * Extracted from `src/secrets/marker.ts`, which shaped it, so the two sweeps
+ * that mute a line share one answer to where a marker may sit. Two lines rather
+ * than one, because a value is as often introduced by a preceding comment as
+ * annotated inline, and a format taking no trailing comment has nowhere else to
+ * put the marker. Nothing further up counts, so a marker cannot silence a block
+ * it does not sit on.
+ *
+ * Only a marker naming a reason counts. A bare token is read as a line that
+ * meant to say something and did not, and honoring it would let a typo mute a
+ * finding, where the reason is the whole value of an exemption a later reader
+ * has to weigh.
+ */
+export function isMarked(
+  lines: readonly string[],
+  index: number,
+  token: string,
+): boolean {
+  const pattern = new RegExp(`${escapeForPattern(token)}:[ \\t]*\\S`)
+  const own = lines[index]
+  const above = index > 0 ? lines[index - 1] : undefined
+
+  return (
+    (own !== undefined && pattern.test(own)) ||
+    (above !== undefined && pattern.test(above))
+  )
+}

package/src/gov/superseded.ts

@@ -0,0 +1,207 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { isBinary } from '@/binary'
+import { isMarked } from '@/exempt-marker'
+import { listRepositoryFiles } from '@/git-files'
+
+/**
+ * The inline token exempting one line from this sweep, shaped on the
+ * `aitk-allow-secret` precedent and read by the same two-line rule.
+ *
+ * A declaration disagreeing with a convention for a stated reason is the case
+ * question 3 of the plan settled against gating on, and the marker is where
+ * that reason goes. A bare token names nothing a later reader can weigh, so it
+ * mutes nothing.
+ */
+export const SUPERSEDED_MARKER = 'aitk-allow-superseded'
+
+export interface SupersededHit {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly column: number
+  /**
+   * Whether the replacement sits on the same line, outside the superseded
+   * occurrences themselves.
+   *
+   * Read outside them because the replacement is routinely a substring of the
+   * value it replaced, which is what a convention dropping a segment produces.
+   * A plain containment test answers true for every line under that shape and
+   * separates nothing.
+   *
+   * A reading aid rather than a filter. The line stating the change carries
+   * both values and so does a fixture halfway through a repair, and nothing
+   * here can tell those apart. Suppressing on it would hide the second case,
+   * which is the whole class this sweep exists to reach.
+   */
+  readonly carriesReplacement: boolean
+  readonly preview: string
+}
+
+export interface SupersededOptions {
+  /** The value the convention used to produce, matched as a literal substring. */
+  readonly superseded: string
+  /** What it produces now, reported so a finding names what to write instead. */
+  readonly replacement: string
+}
+
+export type SupersededReport =
+  | {
+      readonly kind: 'measured'
+      readonly superseded: string
+      readonly replacement: string
+      /** Everything git listed, so the report states its own bound. */
+      readonly listed: number
+      /** Files opened, which is what the verdict actually covers. */
+      readonly files: number
+      /** Binary or unreadable, counted so a pass is not claimed over them. */
+      readonly skipped: number
+      readonly findings: readonly SupersededHit[]
+      readonly exempt: readonly SupersededHit[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+/**
+ * The longest preview a hit carries. A generated or minified line is one line
+ * to git and a screen of noise to a reader, and the report prints one hit per
+ * line found.
+ */
+const PREVIEW_LIMIT = 200
+
+/**
+ * Whether `replacement` appears on the line somewhere other than inside the
+ * superseded occurrences, which is what makes the flag mean anything when one
+ * value contains the other.
+ *
+ * An empty replacement carries nothing, so it answers false rather than the
+ * true every line returns from a containment test against the empty string.
+ * Retiring a value outright is what passes one, and reporting every finding as
+ * carrying its replacement there says the opposite of what happened.
+ */
+function carriesReplacement(line: string, options: SupersededOptions): boolean {
+  if (options.replacement === '') return false
+  return line.split(options.superseded).join('').includes(options.replacement)
+}
+
+/** Every occurrence of `superseded` in one file's text, exemptions separated. */
+export function sweepText(
+  file: string,
+  text: string,
+  options: SupersededOptions,
+): { findings: SupersededHit[]; exempt: SupersededHit[] } {
+  const lines = text.split('\n')
+  const findings: SupersededHit[] = []
+  const exempt: SupersededHit[] = []
+
+  for (const [index, line] of lines.entries()) {
+    let column = line.indexOf(options.superseded)
+    if (column === -1) continue
+
+    const muted = isMarked(lines, index, SUPERSEDED_MARKER)
+    const bucket = muted ? exempt : findings
+    const trimmed = line.trim()
+    const preview =
+      trimmed.length > PREVIEW_LIMIT
+        ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
+        : trimmed
+    const alsoReplacement = carriesReplacement(line, options)
+
+    while (column !== -1) {
+      bucket.push({
+        file,
+        line: index + 1,
+        column: column + 1,
+        carriesReplacement: alsoReplacement,
+        preview,
+      })
+      column = line.indexOf(options.superseded, column + 1)
+    }
+  }
+
+  return { findings, exempt }
+}
+
+/**
+ * Where the tree still asserts a value the convention behind it no longer
+ * produces, keyed on the value rather than on the file stating the rule.
+ *
+ * The file-scoped map is what this exists against. A fixture asserting an old
+ * output names neither the rule nor the standard, so nothing reaches it from
+ * the change that superseded it, and the value it carries is the only key both
+ * sides share.
+ *
+ * This reports and never gates. A string appears for reasons unrelated to the
+ * convention, so the output is a reading a person settles, and the counts of
+ * what was listed, opened, and skipped are what keep it from reading as a
+ * verdict over the whole tree.
+ *
+ * What it cannot see is a prose reference that went stale without carrying the
+ * value, such as a declaration citing the wrong standard for the transform. A
+ * value sweep closes most of this class and no part of that one.
+ */
+export async function readSuperseded(
+  root: string,
+  options: SupersededOptions,
+): Promise<SupersededReport> {
+  if (options.superseded === '') {
+    return {
+      kind: 'unreadable',
+      reason:
+        'The superseded value is empty, which matches every line in the tree rather than a convention.',
+    }
+  }
+
+  if (options.superseded === options.replacement) {
+    return {
+      kind: 'unreadable',
+      reason: `The superseded value and its replacement are both ${options.superseded}, so no convention changed and there is nothing to sweep for.`,
+    }
+  }
+
+  const listed = await listRepositoryFiles(root)
+  if (listed === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Git listed no corpus under ${root}. An empty list passes each of its zero files, so a tree git cannot read refuses rather than reporting clean.`,
+    }
+  }
+
+  const findings: SupersededHit[] = []
+  const exempt: SupersededHit[] = []
+  let files = 0
+  let skipped = 0
+
+  for (const path of listed) {
+    let text: string
+    try {
+      text = await readFile(join(root, path), 'utf8')
+    } catch {
+      // A listed path that will not open is a symlink leaving the tree or a
+      // file removed since git answered. Counted rather than reported, so the
+      // run still states that it measured less than it listed.
+      skipped += 1
+      continue
+    }
+
+    if (isBinary(text)) {
+      skipped += 1
+      continue
+    }
+
+    files += 1
+    const swept = sweepText(path, text, options)
+    findings.push(...swept.findings)
+    exempt.push(...swept.exempt)
+  }
+
+  return {
+    kind: 'measured',
+    superseded: options.superseded,
+    replacement: options.replacement,
+    listed: listed.length,
+    files,
+    skipped,
+    findings,
+    exempt,
+  }
+}

package/src/secrets/marker.ts

@@ -1,3 +1,5 @@
+import { isMarked } from '@/exempt-marker'
+
 /**
  * The inline token exempting one line from the secret scan.
  *
@@ -15,30 +17,14 @@
  */
 export const SECRET_MARKER = 'aitk-allow-secret'
 
-/**
- * Only a marker naming a reason counts.
- *
- * A bare token is read as a line that meant to say something and did not,
- * which is the rule `isStubSeed` already applies to a field set to anything
- * but `true`. Honoring it would let a typo mute a finding, and the reason is
- * the whole value of an exemption a later reader has to weigh.
- */
-const MARKER_LINE = new RegExp(`${SECRET_MARKER}:[ \\t]*\\S`)
-
 /**
  * Whether the line at `index` is exempt, reading itself and the line above it.
  *
- * Two lines rather than one, because a credential-shaped literal is as often
- * introduced by a preceding comment as annotated inline, and a format that
- * takes no trailing comment at all has nowhere else to put the marker. Nothing
- * further up counts, so a marker cannot silence a block it does not sit on.
+ * Where a marker may sit and what makes one count are `isMarked`, which the
+ * superseded-value sweep reads through the same call. Only the token differs
+ * between the two, so the placement rule has one answer rather than two that
+ * can drift.
  */
 export function isExempt(lines: readonly string[], index: number): boolean {
-  const own = lines[index]
-  const above = index > 0 ? lines[index - 1] : undefined
-
-  return (
-    (own !== undefined && MARKER_LINE.test(own)) ||
-    (above !== undefined && MARKER_LINE.test(above))
-  )
+  return isMarked(lines, index, SECRET_MARKER)
 }

package/src/secrets/scan.ts

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { isBinary } from '@/binary'
 import { listRepositoryFiles } from '@/git-files'
 import { isExempt } from '@/secrets/marker'
 import { matchLine } from '@/secrets/patterns'
@@ -48,18 +49,6 @@ export type SecretScan =
     }
   | { readonly kind: 'refused'; readonly reason: ScanRefusal }
 
-/**
- * Whether the bytes are something a line scanner should not read.
- *
- * A NUL byte rather than an extension list, since the shipped tree carries
- * fonts and images under names this check has no reason to enumerate, and a
- * list would go stale the first time a format was added. Decoded text holds no
- * NUL, so the test costs one scan and never rejects source.
- */
-export function isBinary(text: string): boolean {
-  return text.includes('\0')
-}
-
 /** Every finding in one file's text, with the marker already applied. */
 export function scanText(file: string, text: string): SecretFinding[] {
   const lines = text.split('\n')

package/standards/session.md

@@ -56,9 +56,11 @@ Add a section only for content that fits none of the three and would otherwise b
 
 ## Writing one
 
+The `session-map` skill is the invocable route onto this procedure and holds no role, so a session reaching for a handoff without knowing this document exists still lands here. A session that arrives at this document directly follows the steps below unchanged.
+
 1. Capture what the session learned first, so the map cites what was written instead of restating the same lesson in prose.
 2. Run `aitk claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill does not re-read the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. Recording a name is not acting on it, and the verb misses a body this session edited and has not committed. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
-3. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making.
+3. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. An empty result means no commit predates the window, so take the oldest commit the history holds and say which of the two the ref came from.
 4. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a measurement folder holds its track.
 5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
 6. Fill a section from reasoning the session actually holds. A session with no cross-feature picture that fills `## State` from what is already in git has written a summary of the tree, which the reader can produce faster than they can read it.
@@ -76,6 +78,7 @@ Do not restate the board, and do not summarize the work that shipped, since vers
 - Carry every core section whatever else a role adds, and state in the surface that adds a section why the core cannot carry it
 - Let the adding surface fix where its own section sits, so a role can place one between core sections where that reads better. The core order holds among the core sections alone.
 - Keep a section out of the core when a session holding no such role would leave it unfilled. An unfilled section teaches a reader to skip the file.
+- Cite the route onto `## Writing one` rather than restating the procedure, so the extension is the only thing the adding surface carries and the two cannot fall out of step
 - Carry a resume instruction inside the map itself when the routing to that instruction is what a compaction takes. The map survives what the instruction was loaded from, so each reaches a reader the other cannot.
 
 ## Template

package/standards/slug.md

@@ -29,3 +29,11 @@ The empty result is a detached HEAD, and the surface picks one of three response
 - Fall back to `latest`, so a read-only pass still writes somewhere predictable
 - Stop, when the surface commits or opens a pull request. There is no branch to put the work on, so `latest` would bury the problem instead of reporting it. State the stop in the surface's guards.
 - Fall through to the next source, when the slug is one candidate among several rather than the name of an output file
+
+## Changing the transform
+
+A change here moves what the transform produces, and every declaration asserting the old output keeps asserting it. Nothing reports those, because a fixture carrying an old filename names neither this file nor the surface that reads it, so a diff over the change reaches none of them. Dropping the type segment is the change that proved it: four fixtures and three scenario scripts kept the type-carrying spelling, one surfaced as a red arm months later, and the other six were found by deriving from the rule.
+
+Run `aitk gov superseded <old> <new>` in the same change, with the old output and the new one as the two arguments. The value is the only key both sides carry, and the sweep reads the whole tracked tree rather than a path someone predicted. Its output is a reading rather than a verdict, since a string appears for reasons unrelated to any convention, and a declaration disagreeing on purpose carries an `aitk-allow-superseded: <reason>` marker on its own line or the one above.
+
+The sweep sees a value and nothing else. A prose reference that went stale without carrying it, such as a passage citing the wrong standard for the transform, is reached by reading rather than by any key.