@erclx/aitk 3.2.0 → 3.4.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.2.0",
+  "version": "3.4.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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/governance/rules/claude/592-claude-md.md

@@ -0,0 +1,19 @@
+---
+description: Enforce the CLAUDE.md edit protocol and the test routing a fact into it rather than a rule
+paths:
+  - 'CLAUDE.md'
+---
+
+# CLAUDE.md standards
+
+## Editing
+
+- Show the proposed change as a fenced `diff` block in chat first, then wait for approval before calling the file-editing tool.
+
+## Routing
+
+- Keep a rule here when it applies every session regardless of what is being edited.
+- Move a rule into `.claude/rules/` when it fires only on a specific path being edited and violating it ships silently.
+- Route a rule failing either half to a context entry or a skill body rather than here.
+- Name a rule's tier rather than a rule file. A path-scoped rule reaches the session on its own glob and needs no pointer from here.
+- Point at a skill by name where one applies. A skill loads only when invoked, so an unreferenced skill is one no session finds.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.2.0",
+  "version": "3.4.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/architecture.md

@@ -43,6 +43,16 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 - Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
 - Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
 
+## Length
+
+Every session pays for this file before any work starts, so it carries a budget. The budget counts decisions rather than lines, because a bare line total is satisfied by merging paragraph pairs and the merged paragraphs then fail the weight checkpoint in `markdown.md`. A file over budget is carrying too many decisions, not decisions written too long.
+
+- Budget six lines per decision entry, being the H3, two paragraphs, and the blank lines separating them.
+- Budget the frame outside `## Key technical decisions` separately, covering the H1, the overview, and the risks. State the number the project takes where it records the budget, since a frame carries no fixed structure to derive one from.
+- Read the ceiling as the frame plus six lines against the decision count, rather than as the total the two multiply out to.
+- Bring an over-budget file back by merging two decisions or retiring one, never by compressing a decision's prose.
+- Yield the budget to the paragraph weight checkpoint when the two disagree. A paragraph past the checkpoint is a defect no budget licenses.
+
 ## Template
 
 The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none.

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.

package/tooling/claude/seeds/CLAUDE.md

@@ -22,6 +22,7 @@
 - Do not add features the user did not ask for
 - When rewriting a section, preserve existing code blocks, tables, and grouped examples unless the user asked to remove them
 - When planning an edit to `CLAUDE.md`, show the proposed change as a fenced `diff` block in chat first, then wait for approval before calling `Edit`
+- Keep a rule in `CLAUDE.md` when it applies every session regardless of what is being edited. Move one that fires only on a specific path being edited and ships silently when violated into `.claude/rules/`.
 - Edit an existing file with the file-editing tool, never a shell stream editor. An unescaped `&` in a `sed` replacement expands to the whole match, and `sed -i` exits zero when its pattern matches nothing, so both fail silently while reporting success. This governs edits you make, not stream editors written into a project's own scripts.
 
 ## Indexes