@erclx/aitk 0.104.1 → 0.105.0

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

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

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

@@ -21,7 +21,8 @@ Read `.claude/standards/groundwork.md` from the project root before writing any
 
 - Write only inside `.claude/groundwork/<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
 - One exception, at close only: write one task file recording what the track concluded.
-- A second exception, for experiments: write a fixture a spike needs under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- A second exception, for what a spike reads: write an input under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.claude/groundwork/<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
 - Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
@@ -36,7 +37,7 @@ A track may run an experiment to settle an open question without stopping to ask
 
 A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.claude/.tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md`, `.claude/rules/`, and `.claude/standards/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
 
-Record method, result, measured cost, and caveats in `08-spikes.md`. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
 
 ## Step 1: detect the mode
 

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

@@ -113,9 +113,14 @@ The last line is what keeps the step honest on a stack this skill cannot read. E
 
 Then report the port this worktree derives, on a second line:
 
-- `scripts/worktree-port.sh` present: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- `scripts/worktree-port.sh` present and exiting zero: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- Present and exiting non-zero: emit `The port helper refuses this directory, so no server here has a port. <its stderr>`
 - Absent: `No port derivation installed, so every served port is the stack default.`
 
+Branch on the exit rather than on the output, since the helper prints nothing to stdout when it refuses and reading that as a number reports an offset of zero, which is the main checkout's.
+
+The helper refuses a folder left behind after its worktree was removed, which Step 4 cannot land on, since it registers whatever it creates. The branch is here so a refusal is never read back as an offset of zero, which is the main checkout's port and the collision the helper exists to prevent.
+
 The offset is what `claude-orchestrate` sends a reader here to read rather than assign, and what an operator overrides through `WORKTREE_PORT_OFFSET` when two worktrees derive the same value. Deriving it correctly and printing it nowhere leaves both instructions naming a number no surface emits.
 
 Do not invoke `ExitWorktree` from this skill. Exit is the user's call.

package/docs/agents/commands.md

@@ -45,6 +45,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                    |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                            |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD` (`--json`)                                                         |
+| `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                   |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
 
 ## Domain commands
@@ -56,7 +57,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`, `install`, `sync`, `<name>`                                                         |
-| `gov`       | `list`, `install`, `sync`, `build`                                                          |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`                                   |
 | `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `setup [dest]` |
 | `wiki`      | `init`                                                                                      |
 | `design`    | `render`                                                                                    |

package/docs/agents/index.md

@@ -27,3 +27,4 @@ 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
 - [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/test-order.md

@@ -0,0 +1,56 @@
+---
+title: Test order
+description: 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
+---
+
+# Test order
+
+`aitk gov test-order` reports where an implementation reached a commit ahead of the test covering the same behavior. It answers the rule in `.claude/rules/core/070-planning.md` that asks for the test first, which until this verb existed was prose loaded on a glob match with nothing measuring it.
+
+```bash
+aitk gov test-order
+aitk gov test-order --base origin/main --json
+aitk gov test-order --root ../my-app
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
+| `--root <path>` | Repository 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. A consumer reading stdout sees pure data, and an operator reading the terminal sees why a run refused rather than a command that appeared to do nothing.
+
+## The range it reads
+
+The default range is the branch against the trunk, resolved as the merge base against `origin/main` and then local `main`. A repository carrying neither falls back to the root commit, so a fresh checkout still answers rather than refusing.
+
+Reading all history on every run measures work nobody is reviewing and buries the finding that matters under the ones already merged. `--base` widens or narrows it when a reader wants a different window.
+
+Only history is read. A file sitting in the working tree and in no commit is invisible here, which is the point: the verification run sees a tree at one moment, and the ordering exists nowhere but history.
+
+## How a pair is decided
+
+A test is paired to an implementation by the module path with the test suffix removed, so `src/parser.test.ts` covers `src/parser.ts`. Every record is keyed on the implementation path, which is what a reader goes looking for.
+
+Pairing is the whole difficulty. A test and its implementation are related by behavior rather than by filename, so a behavior split across two modules pairs wrongly or not at all. That is what the unclassified verdict exists to catch rather than hide.
+
+## The three verdicts
+
+- **Satisfied.** The implementation was added in the range and its test reached history no later. A test that predates the range counts, and so does one commit carrying both sides, since the rule asks that the test not come after and a single commit is the shape a small change takes.
+- **Implementation-first.** The implementation was added in the range and its test was added in a later commit of the same range. This is the only verdict that moves the exit code.
+- **Unclassified.** Everything the pairing cannot read, each carrying its own reason. A module the range modified rather than added lands here, because a refactor and a new behavior cannot be told apart from history. So does an implementation no test names, and a test whose implementation the range never introduced.
+
+## What it reads past
+
+Only `.ts` and `.tsx` are paired, since a test sits beside its subject under one name across that corpus and a bash script has no such partner. Declaration files carry no behavior to test. Every other changed path is counted under `Read past` rather than dropped silently.
+
+Coverage is narrower than the rule the check answers to. The rule speaks to every behavior, and the verb speaks to the behaviors it can identify, so the report states its own scope on every run rather than implying it looked at everything.
+
+## Exit codes
+
+Exit codes are `0` when nothing reached history ahead of its test, `1` for a refusal, and `2` for at least one implementation-first finding. Unclassified rows move no exit code.
+
+Nothing wires this into `bun run check` or into a hook. The unclassified class is large and known, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `aitk tasks validate` is the precedent: it exits `2` on findings and is called where the claim is made rather than on every push.
+
+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

@@ -55,6 +55,8 @@ The routing test is whether the repository can answer an item today. A session g
 
 A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
+What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
+
 #### Session 2
 
 Start a fresh Claude Code session. The diff is sufficient context for both review and ship.

package/governance/rules/core/070-planning.md

@@ -13,4 +13,5 @@ description: Enforce planning standards before implementation
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
+- Run `aitk gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
 - Do not modify code without a confirmed plan.

package/package.json

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

package/src/commands/gov.ts

@@ -14,6 +14,11 @@ import {
   mergeExtraRules,
   resolveRules,
 } from '@/gov/stacks'
+import {
+  type PairRecord,
+  readTestOrder,
+  type TestOrderReport,
+} from '@/gov/test-order'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import {
@@ -48,6 +53,12 @@ interface ListOptions {
   readonly json?: boolean
 }
 
+interface TestOrderOptions {
+  readonly base?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -133,6 +144,130 @@ export function register(program: Command): void {
     .action((opts: ListOptions) => {
       process.exitCode = runList(opts)
     })
+
+  gov
+    .command('test-order')
+    .description(
+      'Report where an implementation reached history before its test',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Measures the rule in .claude/rules/core/070-planning.md that asks for',
+        'the test before the code. It reports and never gates, because pairing',
+        'a test to an implementation is a judgment.',
+        '',
+        'Coverage:',
+        '  a test sits beside its subject under the same name, minus .test',
+        '  only .ts and .tsx are paired, and every other path is named as read past',
+        '  a module the range modified rather than added is unclassified, since',
+        '  a refactor and a new behavior cannot be told apart from history',
+        '',
+        'Exit codes:',
+        '  0  no implementation reached history ahead of its test',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one implementation reached history ahead of its test',
+        '',
+        'Examples:',
+        '  aitk gov test-order',
+        '  aitk gov test-order --base origin/main --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: TestOrderOptions) => {
+      process.exitCode = runTestOrder(opts)
+    })
+}
+
+/**
+ * Reports and never gates, so the finding count moves the exit code without
+ * anything wiring it into a push. `aitk tasks validate` set that shape: a
+ * measure carrying a known false-positive class is what forces contributors to
+ * route around a stage, and the unclassified bucket here is that class.
+ */
+function runTestOrder(opts: TestOrderOptions): number {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = readTestOrder(root, { base: opts.base })
+  const emitJson = opts.json ?? false
+
+  // The frame renders on stderr in both modes and the record goes to stdout
+  // alone, which is the split `docs/agents/output-shape.md` fixes. A consumer
+  // reading stdout sees pure data either way, and an operator reading the
+  // terminal sees the refusal rather than a command that appeared to do nothing.
+  if (report.kind === 'unreadable') {
+    intro('aitk gov test-order')
+    logStep('Refused')
+    logError(report.reason)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportTestOrder(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ok: true, root, ...report })}\n`)
+  }
+
+  return report.findings.length > 0 ? 2 : 0
+}
+
+function describePair(record: PairRecord): string {
+  const test = record.test === null ? 'no test' : record.test
+  return `${record.subject} → ${test}: ${record.reason}`
+}
+
+function reportTestOrder(
+  report: Extract<TestOrderReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov test-order')
+
+  logStep('Range')
+  logInfo(`${report.base.slice(0, 8)}..${report.head.slice(0, 8)} in ${root}`)
+
+  logStep(report.findings.length === 0 ? 'Clean' : 'Findings')
+  if (report.findings.length === 0) {
+    logInfo('no implementation reached history ahead of the test covering it')
+  } else {
+    for (const finding of report.findings) logWarn(describePair(finding))
+  }
+
+  logStep('Satisfied')
+  logInfo(`${report.satisfied.length} pair(s) whose test came first`)
+
+  // The unclassified rows carry the warn glyph and move no exit code. A pass
+  // over a change the pairing could not read is the claim this check exists to
+  // avoid making, so the rows are named rather than counted into the clean line.
+  logStep('Unclassified')
+  if (report.unclassified.length === 0) {
+    logInfo('every changed module paired')
+  } else {
+    logWarn(
+      `${report.unclassified.length} change(s) the pairing could not read`,
+    )
+    for (const record of report.unclassified) logWarn(describePair(record))
+  }
+
+  // Coverage is narrower than the rule, and a report that did not say so would
+  // read as a verdict over every behavior in the range.
+  logStep('Read past')
+  logInfo(
+    `${report.ignored.length} path(s) outside ${report.scope.extensions.join(', ')}`,
+  )
+
+  outro()
 }
 
 /**

package/src/gov/test-order.ts

@@ -0,0 +1,383 @@
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Preferred first, matching `src/tasks/trunk.ts`. A clone with no remote still
+ * answers off its local trunk, and a local `main` trailing the remote widens
+ * the range rather than narrowing it, which over-reports instead of hiding.
+ */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * The extensions this check can pair. A test sits beside its subject under one
+ * name throughout this corpus, so the weakest assumption available is also the
+ * one the corpus already honors. Every other extension is read past and named,
+ * since a bash script and its test are related by nothing a filename carries.
+ */
+export const SOURCE_EXTENSIONS = ['.ts', '.tsx'] as const
+
+/** The suffix removed to derive the subject a test covers. */
+export const TEST_SUFFIXES = ['.test.ts', '.test.tsx'] as const
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/** A `--name-status` line: a status letter, a tab, then one path. */
+const NAME_STATUS = /^([A-Z])\d*\t(.+)$/
+
+export type Verdict = 'satisfied' | 'implementation-first' | 'unclassified'
+
+export interface PairRecord {
+  /** The implementation path, which is what a subject is named by. */
+  readonly subject: string
+  /** The test paired to it, or `null` when the pairing found no partner. */
+  readonly test: string | null
+  readonly verdict: Verdict
+  readonly implementationCommit: string | null
+  readonly testCommit: string | null
+  /** Why the verdict reads the way it does, in the report's own words. */
+  readonly reason: string
+}
+
+export interface Scope {
+  readonly extensions: readonly string[]
+  readonly testSuffixes: readonly string[]
+}
+
+export type TestOrderReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly scope: Scope
+      readonly satisfied: readonly PairRecord[]
+      readonly findings: readonly PairRecord[]
+      readonly unclassified: readonly PairRecord[]
+      /** Changed paths outside the pairing's reach, named rather than counted. */
+      readonly ignored: readonly string[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+export interface TestOrderOptions {
+  /** The far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+}
+
+/** One path as one commit in the range touched it. */
+interface Change {
+  readonly path: string
+  readonly status: string
+  readonly commit: string
+  /** Position in the range, oldest first, which is what orders a pair. */
+  readonly order: number
+}
+
+/**
+ * Reads `--name-status` log output, oldest commit first, into one entry per
+ * path per commit.
+ *
+ * The order field rather than the commit is what a comparison reads, since two
+ * commits carry no ordering a caller can derive from their hashes alone.
+ */
+function parseChanges(output: string): Change[] {
+  const changes: Change[] = []
+  let commit = ''
+  let order = -1
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trimEnd()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      order += 1
+      continue
+    }
+
+    const match = NAME_STATUS.exec(trimmed)
+    if (match === null || commit === '') continue
+
+    changes.push({ path: match[2], status: match[1], commit, order })
+  }
+
+  return changes
+}
+
+/** Whether a path is a test this check can derive a subject from. */
+function testSuffix(path: string): string | undefined {
+  return TEST_SUFFIXES.find((suffix) => path.endsWith(suffix))
+}
+
+/**
+ * The implementation a test covers, derived by removing the test suffix.
+ *
+ * A behavior split across two modules pairs wrongly or not at all under this,
+ * which is what the unclassified bucket exists to catch rather than hide.
+ */
+function subjectOf(path: string): string {
+  const suffix = testSuffix(path)
+  if (suffix === undefined) return path
+  return `${path.slice(0, -suffix.length)}${suffix.replace('.test', '')}`
+}
+
+/** The one test path that would cover `subject` under the beside convention. */
+function testPathFor(subject: string): string {
+  return subject.replace(/\.(tsx?)$/, '.test.$1')
+}
+
+/**
+ * Whether a path is an implementation this check can pair. A declaration file
+ * carries no behavior to test, so it is read past rather than reported as a
+ * module nothing covers.
+ */
+function isImplementation(path: string): boolean {
+  if (path.endsWith('.d.ts')) return false
+  if (testSuffix(path) !== undefined) return false
+  return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension))
+}
+
+/** The first commit in the range that added `path`, or `undefined`. */
+function introduction(
+  changes: readonly Change[],
+  path: string,
+): Change | undefined {
+  return changes.find((change) => change.path === path && change.status === 'A')
+}
+
+function classify(
+  changes: readonly Change[],
+  atBase: ReadonlySet<string>,
+): {
+  satisfied: PairRecord[]
+  findings: PairRecord[]
+  unclassified: PairRecord[]
+} {
+  const satisfied: PairRecord[] = []
+  const findings: PairRecord[] = []
+  const unclassified: PairRecord[] = []
+
+  // Keyed by subject so a module whose implementation and test both moved is
+  // one record rather than two, and so a test with no partner still reports
+  // under the implementation path a reader would go looking for.
+  const subjects = new Set<string>()
+  for (const change of changes) {
+    if (isImplementation(change.path)) subjects.add(change.path)
+    else if (testSuffix(change.path) !== undefined) {
+      subjects.add(subjectOf(change.path))
+    }
+  }
+
+  for (const subject of [...subjects].sort()) {
+    const candidate = testPathFor(subject)
+    const testChange = introduction(changes, candidate)
+    const testAtBase = atBase.has(candidate)
+    const test = testAtBase || testChange !== undefined ? candidate : undefined
+
+    const implementation = introduction(changes, subject)
+
+    if (implementation === undefined) {
+      unclassified.push({
+        subject,
+        test: test ?? null,
+        verdict: 'unclassified',
+        implementationCommit: null,
+        testCommit: null,
+        reason: atBase.has(subject)
+          ? 'the implementation predates the range, so a change to it cannot be separated from a refactor'
+          : 'no implementation reached the range beside this test',
+      })
+      continue
+    }
+
+    if (test === undefined) {
+      unclassified.push({
+        subject,
+        test: null,
+        verdict: 'unclassified',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'no test names this module, so the ordering has no second side',
+      })
+      continue
+    }
+
+    // A paired test the range never added is one that already sat at the base
+    // commit, since those are the only two ways `test` gets a value at all.
+    if (testChange === undefined) {
+      satisfied.push({
+        subject,
+        test,
+        verdict: 'satisfied',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'the test predates the range',
+      })
+      continue
+    }
+
+    // One commit carrying both sides counts as satisfied. The rule asks that
+    // the test not come after, and a single commit is the shape a small change
+    // takes here, so reporting it would flag most of the corpus.
+    const record: PairRecord = {
+      subject,
+      test,
+      verdict:
+        testChange.order <= implementation.order
+          ? 'satisfied'
+          : 'implementation-first',
+      implementationCommit: implementation.commit,
+      testCommit: testChange.commit,
+      reason:
+        testChange.order <= implementation.order
+          ? 'the test reached history no later than the implementation'
+          : 'the implementation reached history before the test covering it',
+    }
+
+    if (record.verdict === 'satisfied') satisfied.push(record)
+    else findings.push(record)
+  }
+
+  return { satisfied, findings, unclassified }
+}
+
+/**
+ * Where an implementation reached a commit ahead of the test covering it,
+ * between `base` and the current `HEAD` of the tree at `root`.
+ *
+ * This reports and never gates. Pairing a test to an implementation is a
+ * judgment, so a change the pairing cannot read lands in `unclassified` with
+ * its reason stated rather than being counted as a pass. Coverage is narrower
+ * than the rule the check answers to, and `scope` and `ignored` are what say so
+ * on every run.
+ */
+export function readTestOrder(
+  root: string,
+  options: TestOrderOptions = {},
+): TestOrderReport {
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
+    }
+  }
+
+  const base = resolveBase(root, options.base, head)
+  if (typeof base !== 'string') return base
+
+  const log = git(root, [
+    'log',
+    '--reverse',
+    '--name-status',
+    '--no-renames',
+    '--format=%H',
+    `${base}..${head}`,
+  ])
+
+  if (log === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${base} and HEAD failed under ${root}.`,
+    }
+  }
+
+  const tree = git(root, ['ls-tree', '-r', '--name-only', base])
+  if (tree === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
+    }
+  }
+
+  const changes = parseChanges(log)
+  const atBase = new Set(tree.split('\n').filter((line) => line !== ''))
+
+  const ignored = [
+    ...new Set(
+      changes
+        .map((change) => change.path)
+        .filter(
+          (path) => !isImplementation(path) && testSuffix(path) === undefined,
+        ),
+    ),
+  ].sort()
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    scope: { extensions: SOURCE_EXTENSIONS, testSuffixes: TEST_SUFFIXES },
+    ...classify(changes, atBase),
+    ignored,
+  }
+}
+
+/**
+ * The far side of the range. A ref the caller named has to resolve, since
+ * falling back to the trunk there would measure a range nobody asked for. With
+ * no ref named, the merge base against the trunk scopes the run to the branch,
+ * and a repository carrying no trunk falls back to the root commit rather than
+ * refusing.
+ */
+function resolveBase(
+  root: string,
+  ref: string | undefined,
+  head: string,
+): string | { kind: 'unreadable'; reason: string } {
+  if (ref !== undefined) {
+    const resolved = revParse(root, ref)
+    if (resolved === undefined) {
+      return {
+        kind: 'unreadable',
+        reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+      }
+    }
+    return resolved
+  }
+
+  for (const trunk of TRUNK_REFS) {
+    if (revParse(root, trunk) === undefined) continue
+    const merged = git(root, ['merge-base', head, trunk])
+    if (merged !== undefined && merged !== '') return merged
+  }
+
+  const rootCommits = git(root, ['rev-list', '--max-parents=0', head])
+  if (rootCommits === undefined || rootCommits === '') {
+    return {
+      kind: 'unreadable',
+      reason: `No base resolves against ${root}. Fetch origin or pass --base.`,
+    }
+  }
+
+  return rootCommits.split('\n')[0]
+}
+
+/**
+ * `execaSync` with git's repository-resolution variables stripped, so `-C`
+ * resolves against `root` and not against whatever repository a hook exported.
+ * `undefined` is the refusal, which every caller turns into its own reason.
+ */
+function git(root: string, args: readonly string[]): string | undefined {
+  const result = execaSync('git', ['-C', root, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  return result.exitCode === 0 ? result.stdout.trimEnd() : undefined
+}
+
+/**
+ * The commit a ref names. `^{commit}` is what turns a tag or a tree into the
+ * commit behind it, so a caller never compares a ref against another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const resolved = git(root, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${ref}^{commit}`,
+  ])
+
+  return resolved === undefined || resolved === '' ? undefined : resolved.trim()
+}

package/standards/groundwork.md

@@ -122,6 +122,10 @@ Each spike carries four things:
 
 Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
 
+A spike also leaves files behind, and they split on whether the track cites them rather than on whether they are markdown. An input the run reads, being a fixture page, an arm script, or a copied asset, is re-runnable and cited by nothing, so it stays outside the track wherever the surface driving the spike puts it. Evidence the record cites, being a recording, a render, or a frame pulled from one, is what a later reader opens to check a claim, so it lives in `evidence/` inside the track beside the file citing it. Name the split rather than the file types, which is what keeps this from going stale on the next kind of artifact a spike produces.
+
+`evidence/` takes no number, since numbering is the read order over the files a reader opens in sequence and an artifact is reached from the claim that cites it instead.
+
 Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
 
 One method error is worth naming, because it is made rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction naming a path puts that path in the transcript whether or not anything opened it. The check is the tool call.

package/tooling/astro/manifest.toml

@@ -15,17 +15,17 @@ packages = [
 ]
 
 [scripts]
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
 "build" = "astro check && astro build"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 "astro" = "astro"
 "typecheck" = "astro check"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
-"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) bash scripts/screenshot.sh"
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 
 [gitignore]
 "# Astro" = [".astro/"]

package/tooling/vite-react/manifest.toml

@@ -11,13 +11,13 @@ packages = [
 ]
 
 [scripts]
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite"
 "build" = "tsc --noEmit && vite build"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"
 "typecheck" = "tsc --noEmit"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
 "build" = "tsc --noEmit && vite build"
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"

package/tooling/web/configs/scripts/worktree-port.sh

@@ -3,10 +3,18 @@ set -euo pipefail
 
 # Prints a port for this working directory: the base itself in a normal
 # checkout, and the base plus a per-worktree offset in a linked git worktree,
-# so two worktrees of one repository never serve on one port.
+# so two worktrees of one repository never serve on one port. A folder left
+# behind after its worktree was removed is refused rather than served, since
+# every port it derives lands on the one the main checkout wanted.
 
 base="${1:-0}"
 band=50
+worktrees_dir=".claude/worktrees"
+
+refuse() {
+  echo "worktree-port: $1 is a leftover worktree folder, because $2." >&2
+  echo "worktree-port: a port derived here collides with the main checkout, so remove the folder, or set WORKTREE_PORT_OFFSET to serve from it anyway." >&2
+}
 
 offset() {
   if [[ -n "${WORKTREE_PORT_OFFSET:-}" ]]; then
@@ -14,23 +22,53 @@ offset() {
     return
   fi
 
-  local git_dir common_dir name
-  git_dir=$(git rev-parse --git-dir 2>/dev/null) || {
+  local here git_dir common_dir toplevel dir name
+  here=$(pwd -P)
+
+  if ! git_dir=$(git rev-parse --git-dir 2>/dev/null); then
+    # Git refuses outright when a `.git` file names an administrative directory
+    # that is gone, which is what removing a worktree by hand leaves behind.
+    # Outside a repository there is no pointer at all and the base is correct.
+    dir=$here
+    while [[ "$dir" != / ]]; do
+      if [[ -f "$dir/.git" ]]; then
+        refuse "$dir" "its .git file names an administrative directory that is gone"
+        return 1
+      fi
+      [[ -d "$dir/.git" ]] && break
+      dir=$(dirname "$dir")
+    done
     echo 0
     return
-  }
+  fi
+
   common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || {
     echo 0
     return
   }
+  toplevel=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo 0
+    return
+  }
+  toplevel=$(cd "$toplevel" && pwd -P)
 
   if [[ "$(cd "$git_dir" && pwd -P)" == "$(cd "$common_dir" && pwd -P)" ]]; then
+    # The main checkout answers here, and so does every directory under it,
+    # including a folder whose `.git` was deleted along with its worktree,
+    # since git then walks upward and reports the parent repository. Location
+    # is the only signal separating the two, so a directory sitting under the
+    # worktrees folder is refused rather than handed the base port.
+    if [[ "$here/" == "$toplevel/$worktrees_dir/"?* ]]; then
+      refuse "$here" "no worktree is registered for it"
+      return 1
+    fi
     echo 0
     return
   fi
 
-  name=$(basename "$(git rev-parse --show-toplevel)")
+  name=$(basename "$toplevel")
   echo $(($(printf '%s' "$name" | cksum | cut -d' ' -f1) % band + 1))
 }
 
-echo $((base + $(offset)))
+value=$(offset) || exit 1
+echo $((base + value))

package/tooling/web/manifest.toml

@@ -42,13 +42,13 @@ packages = [
 "test:run" = "vitest run --reporter=verbose"
 "test:ui" = "vitest --ui"
 "test:coverage" = "vitest run --coverage"
-"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test"
-"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test --ui"
+"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test"
+"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
 "test:e2e:report" = "playwright show-report"
 "check:full" = "./scripts/verify.sh && bun run test:e2e"
 
 [scripts.override]
-"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) bash scripts/screenshot.sh"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]

package/tooling/web/reference.md

@@ -16,7 +16,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
-- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone.
+- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
 
 ## What stays in per-stack adapters
 
@@ -40,6 +40,9 @@ Two worktrees of one repository run the same stack, so a fixed port makes the se
 - Derive every served port from `scripts/worktree-port.sh`. Never write a port literal into a script string.
 - Read `WORKTREE_PORT_OFFSET` in a config and add it to the stack's default port. Unset yields the default, so a plain clone keeps the port it has always served on.
 - Draw the offset from a band of 50, hashed from the worktree folder name. Two worktrees can hash to one offset, so set `WORKTREE_PORT_OFFSET` by hand to break a tie.
+- Expect a non-zero exit and no port from a folder left under `.claude/worktrees/` once its worktree is gone. Git reports the parent repository from inside one, so the helper cannot read it as a worktree and every base it serves would land on the main checkout's port. Both shapes refuse, and they reach differently. A folder whose own `.git` was deleted refuses only under that directory, since location is the only thing separating it from an ordinary subdirectory the base port is correct for. A folder whose `.git` names a pruned administrative directory refuses wherever it sits, because a pointer to nothing is broken regardless of where the folder is.
+- Call it as `VAR=$(bash scripts/worktree-port.sh) && export VAR && <server>`, never as the shorter `VAR=$(bash scripts/worktree-port.sh) <server>`. An assignment prefix discards the exit status of its own substitution, so the shorter form starts the server with `VAR` set to the empty string, every config reads that back as an offset of zero, and the refusal lands on the port it was raised to protect. The assignment alone carries the status, which is what the `&&` reads.
+- Set `WORKTREE_PORT_OFFSET` by hand to serve from such a folder anyway. That is the one override, and it is checked before any directory test.
 - Force-replace `dev` and `preview` through `[scripts.override]`. Both stacks' scaffolds define those keys, and a plain `[scripts]` entry never replaces a key the scaffold already wrote.
 - Set `strictPort` on every dev and preview server. A server that walks to the next free port serves where nothing is looking for it.
 - Set Playwright `reuseExistingServer: false`. Reuse attaches to whatever answers on the port, which reports a pass against another branch's code and prints nothing to say so.