@erclx/aitk 0.104.0 → 0.104.1

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.0",
+  "version": "0.104.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -227,6 +227,10 @@ A board carrying one task written `../plans/x.md` and another written `.claude/p
 
 Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
 
+`aitk tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `aitk` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.claude/plans-archive/`.
+
+Nothing in the exit code reports that. Branch on the record's `ok` and `reason` fields and never on the exit, which is the rule every task verb already carries: an operator's shell profile may wrap `aitk` in a function that runs the binary and then another command, taking its status from the second, and one measured here masks every non-zero exit rather than only an absent verb. The binary itself exits 1 for an unknown subcommand and 1 for an ordinary refusal alike. Switching this body to the verb needs a release that carries it and a read of the record rather than the exit, which together retire the duplication.
+
 A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.claude/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
 
 - Target resolves inside `.claude/plans/`, the file exists, and no other task file cites it: create `.claude/plans-archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.

package/docs/agents/tasks.md

@@ -24,6 +24,8 @@ aitk tasks archive --pull-request 673 --json
 
 Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `plan-unswept`, or `bad-input`.
 
+`plan-unswept` fires on the last task pointing at a live plan, never on every task pointing at one. The gate counts the other live tasks whose `Plan:` line resolves onto the same file, so a plan several tasks share archives its tasks freely and only the final one is held until `claude-docs` sweeps the plan. Reading the folder alone refused all of them, which deadlocked the board against a sweep correctly declining to move a plan another live task cites.
+
 `bad-input` covers a malformed command line, which all three task verbs answer the same way. It is separate from `ambiguous` and `no-match` because those describe the board, and a caller that passed two selectors would otherwise be sent to repair a task citation that is fine.
 
 The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
@@ -34,6 +36,27 @@ Skills branch on the reason rather than on the exit code:
 aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
 ```
 
+## Plan citations
+
+`aitk tasks plan-citations <stem>` answers where a task's plan sits and which other live tasks hold it. It reports and never writes.
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `location`, one of `unstated`, `live`, `archived`, or `outside`, and `citedBy`, the other live tasks whose `Plan:` line lands on the same file. Exit codes: `0` read, `1` refused with `no-board` or `no-match`.
+
+`aitk tasks archive` gates on this same answer, so a caller wanting the count reads it here rather than scanning the board. The `claude-docs` plans sweep is the exception and still states the rule in its own body, because a plugin skill reaches a target on merge while the CLI reaches one on release, so a sweep calling a verb the installed `aitk` predates gets no record back and archives nothing.
+
+Branch on `reason` rather than on the exit code, which is the rule the archive section above already states and which this verb needs for a second reason. An operator's shell profile may wrap `aitk` in a function that runs the binary and then another command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
+
+A `live` location with an empty `citedBy` is the sweep to run. One whose `citedBy` names a sibling is a plan several tasks share, which the sweep leaves alone and the archive gate lets through.
+
+```bash
+aitk tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
+```
+
 ## Pull request
 
 `aitk tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.
@@ -106,7 +129,11 @@ A backlog line is a bullet carrying a link to a sibling task, since the backlog
 
 The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
 
-The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or closing every outcome, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+
+A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
+
+The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate runs several times a sweep and a fetch per run is a cost this command does not carry, so a clone behind its remote under-reports rather than claiming work landed.
 
 Both halves gate on a citation inside the `Waiting on` cell, never on the columns beside it. The board format gives a collision cell the file held by the running task, so a row whose cell names no file was parked by something else, and testing its Touches column instead reports a cleared collision on a row no collision ever parked while counting that row as re-tested. A cited task is a bare sibling link, the way the Task column spells one, so a pointer into another folder names a plan rather than a task and settles nothing. A cited task carrying no outcome box settles nothing either, since a file the check could not parse is not evidence of a finished one.
 

package/docs/ai-workflow.md

@@ -105,11 +105,11 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `.claude/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
-`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task has closed and one whose cited file nothing running still holds. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, which is where the three kinds resting on a person's judgment land. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
+`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
 `aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
-Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
+Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
 

package/package.json

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

package/src/commands/tasks.ts

@@ -1,6 +1,12 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
-import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  type ArchiveOutcome,
+  archiveTask,
+  type CitationOutcome,
+  type PlanCitations,
+  planCitations,
+} from '@/tasks/archive'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -42,6 +48,11 @@ interface ValidateCommandOptions {
   readonly root?: string
 }
 
+interface CitationsCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -126,6 +137,41 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(opts)
     })
 
+  tasks
+    .command('plan-citations')
+    .description('Report where a task plan sits and which live tasks hold it')
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Locations:',
+        '  unstated  the task carries no Plan: line',
+        '  live      the target resolves inside .claude/plans/',
+        '  archived  the target resolves inside .claude/plans-archive/',
+        '  outside   the target resolves somewhere else',
+        '',
+        'Exit codes:',
+        '  0  the citations were read',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It reports and never writes. A live plan whose citedBy list is empty',
+        'is the sweep to run, and one a sibling still holds is left alone.',
+        'The archive gate reads the same answer, so neither can drift.',
+        '',
+        'Examples:',
+        '  aitk tasks plan-citations v28.1-trigger-escalation',
+        '  aitk tasks plan-citations v28.1-trigger-escalation --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: CitationsCommandOptions) => {
+      process.exitCode = await runCitations(task, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -426,6 +472,67 @@ async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   return reportValidation(outcome, opts.json ?? false, root)
 }
 
+async function runCitations(
+  task: string,
+  opts: CitationsCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await planCitations(root, task)
+
+  return reportCitations(outcome, opts.json ?? false, root)
+}
+
+function reportCitations(
+  outcome: CitationOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk tasks plan-citations')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('aitk tasks plan-citations')
+  logStep(outcome.stem)
+  logInfo(describeCitations(outcome))
+  outro()
+
+  return 0
+}
+
+function describeCitations(outcome: PlanCitations): string {
+  if (outcome.location === 'unstated') return 'carries no Plan: line.'
+
+  if (outcome.location === 'archived') {
+    return `points at ${outcome.target}, which an earlier sweep already archived.`
+  }
+
+  if (outcome.location === 'outside') {
+    return `points at ${outcome.target}, which resolves outside both plans folders.`
+  }
+
+  if (outcome.citedBy.length === 0) {
+    return `is the last live task citing ${outcome.target}, so the sweep may archive it.`
+  }
+
+  return `shares ${outcome.target} with ${outcome.citedBy.join(', ')}, so the sweep leaves it.`
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,

package/src/tasks/archive.ts

@@ -6,6 +6,7 @@ import { regenOne } from '@/indexes/regen'
 const TASKS_DIR = join('.claude', 'tasks')
 const ARCHIVE_DIR = join('.claude', 'task-archive')
 const PLANS_DIR = join('.claude', 'plans')
+const PLANS_ARCHIVE_DIR = join('.claude', 'plans-archive')
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -192,13 +193,152 @@ function isUnder(path: string, dir: string): boolean {
  * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
  * and `.claude/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
+ *
+ * The resolved path is returned rather than a boolean, because the citation
+ * count below compares two tasks by where their targets land and not by the
+ * strings they wrote. A target outside the live plans folder yields nothing,
+ * which is an archived plan or a pointer into somewhere else entirely.
  */
-function isLivePlan(target: string, dir: string, root: string): boolean {
+export function resolveLivePlan(
+  target: string,
+  dir: string,
+  root: string,
+): string | undefined {
   const plans = join(root, PLANS_DIR)
+  const fromBoard = resolve(dir, target)
+  const fromRoot = resolve(root, target)
+
+  if (isUnder(fromBoard, plans)) return fromBoard
+  if (isUnder(fromRoot, plans)) return fromRoot
+  return undefined
+}
+
+/**
+ * Names the other live tasks whose `Plan:` line lands on the same file. This is
+ * the rule `claude-docs` applies before it archives a plan, held here so one
+ * question has one implementation: a plan another live task still cites is a
+ * plan the sweep is correct to leave, and a guard that read the folder instead
+ * refused every task sharing one plan and deadlocked the board against the
+ * sweep that was behaving correctly.
+ *
+ * The closing task is excluded by name. It cites the plan itself, so counting
+ * it would never reach zero and the count would answer nothing.
+ */
+export async function otherTasksCitingPlan(
+  dir: string,
+  root: string,
+  plan: string,
+  closing: string,
+): Promise<string[]> {
+  const stems = (await listTaskStems(dir)).filter((stem) => stem !== closing)
+
+  const read = await Promise.all(
+    stems.map(async (stem) => {
+      const target = readPlanTarget(
+        await readFile(join(dir, `${stem}.md`), 'utf8'),
+      )
+      const resolved = target && resolveLivePlan(target, dir, root)
+      return resolved === plan ? stem : undefined
+    }),
+  )
+
+  return read.filter((stem): stem is string => stem !== undefined)
+}
+
+/**
+ * Where a task's `Plan:` target resolves, which is what decides whether the
+ * plan is the sweep's to move. `unstated` is a task carrying no line at all,
+ * and it is distinct from a line resolving somewhere unexpected.
+ */
+export const CITATION_LOCATIONS = [
+  'unstated',
+  'live',
+  'archived',
+  'outside',
+] as const
+
+export type CitationLocation = (typeof CITATION_LOCATIONS)[number]
+
+export interface PlanCitations {
+  readonly ok: true
+  readonly stem: string
+  readonly target: string | undefined
+  readonly location: CitationLocation
+  /** Other live tasks landing on the same file. Empty unless `location` is `live`. */
+  readonly citedBy: readonly string[]
+}
+
+export type CitationOutcome = PlanCitations | ArchiveRefused
+
+/**
+ * Answers where one task's plan sits and who else holds it, which is the whole
+ * of the last-live-citation rule. `claude-docs` reads this rather than scanning
+ * the board itself, so the sweep that moves a plan and the gate that refuses a
+ * task archive cannot drift into disagreeing about which plan is free.
+ *
+ * It reports and never writes. The move, the retarget, and the ordering the two
+ * happen in belong to the caller, and a verb that performed them would be
+ * deciding a question the sweep is there to decide.
+ */
+export async function planCitations(
+  root: string,
+  stem: string,
+): Promise<CitationOutcome> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const stems = await listTaskStems(dir)
+  if (!stems.includes(stem)) {
+    return refuse('no-match', `No task named ${stem} on the board.`, stems)
+  }
+
+  const target = readPlanTarget(await readFile(join(dir, `${stem}.md`), 'utf8'))
+  if (!target) {
+    return {
+      ok: true,
+      stem,
+      target: undefined,
+      location: 'unstated',
+      citedBy: [],
+    }
+  }
+
+  const live = resolveLivePlan(target, dir, root)
+  if (!live) {
+    const location = resolvesUnder(target, dir, root, PLANS_ARCHIVE_DIR)
+      ? 'archived'
+      : 'outside'
+    return { ok: true, stem, target, location, citedBy: [] }
+  }
+
+  return {
+    ok: true,
+    stem,
+    target,
+    location: 'live',
+    citedBy: await otherTasksCitingPlan(dir, root, live, stem),
+  }
+}
+
+/**
+ * Runs the two-spelling resolution `resolveLivePlan` applies against a folder
+ * other than the live one, so an archived plan is read as archived whichever
+ * root the task wrote its path against.
+ */
+function resolvesUnder(
+  target: string,
+  dir: string,
+  root: string,
+  folder: string,
+): boolean {
+  const resolved = join(root, folder)
 
   return (
-    isUnder(resolve(dir, target), plans) ||
-    isUnder(resolve(root, target), plans)
+    isUnder(resolve(dir, target), resolved) ||
+    isUnder(resolve(root, target), resolved)
   )
 }
 
@@ -310,12 +450,21 @@ export async function archiveTask(
   }
 
   const planTarget = readPlanTarget(text)
-  if (planTarget && isLivePlan(planTarget, dir, root)) {
-    return refuse(
-      'plan-unswept',
-      `${stem} still points at a live plan. Run /claude-docs to sweep it first, then archive.`,
-      [planTarget],
-    )
+  const livePlan = planTarget && resolveLivePlan(planTarget, dir, root)
+
+  // A live plan is unswept only when nothing else on the board holds it. A plan
+  // several tasks share stays live by design, so refusing on the folder alone
+  // parked every one of those tasks behind a sweep that was right to decline.
+  if (livePlan) {
+    const shared = await otherTasksCitingPlan(dir, root, livePlan, stem)
+
+    if (shared.length === 0) {
+      return refuse(
+        'plan-unswept',
+        `${stem} is the last task pointing at a live plan. Run /claude-docs to sweep it first, then archive.`,
+        [planTarget],
+      )
+    }
   }
 
   const destination = archiveDir(root)

package/src/tasks/trunk.ts

@@ -0,0 +1,89 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+const GIT_TIMEOUT_MS = 10_000
+
+/** Preferred first. A clone with no remote still answers off its local trunk. */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * Reports whether a pull request's work reached the trunk. `undefined` means
+ * the trunk could not be read, which is a different answer from `false` and has
+ * to stay one: a check that degraded to "not landed" on an unreachable trunk
+ * would report a board silently rather than say what it failed to test.
+ */
+export type TrunkReader = (pullRequest: number) => Promise<boolean | undefined>
+
+/**
+ * Matches the two subjects a landed pull request leaves on the trunk: the
+ * `(#NNN)` suffix a squash merge writes, and the subject GitHub writes for a
+ * merge commit. Both carry the number in a form no other commit spells, so a
+ * pull request numbered 12 cannot match one numbered 123.
+ */
+function grepArgs(pullRequest: number): string[] {
+  return [
+    '--extended-regexp',
+    '--grep',
+    `\\(#${pullRequest}\\)`,
+    '--grep',
+    `Merge pull request #${pullRequest} from`,
+  ]
+}
+
+/**
+ * Reads the trunk as this clone already holds it and never fetches. A validate
+ * run happens several times a sweep and a fetch per run is a cost the check
+ * does not carry today, so a clone behind the remote reports the row untested
+ * or leaves it parked rather than claiming work landed.
+ */
+export function gitTrunkReader(root: string): TrunkReader {
+  const answered = new Map<number, boolean | undefined>()
+
+  return async (pullRequest) => {
+    if (answered.has(pullRequest)) return answered.get(pullRequest)
+
+    const landed = await readTrunk(root, pullRequest)
+    answered.set(pullRequest, landed)
+    return landed
+  }
+}
+
+async function readTrunk(
+  root: string,
+  pullRequest: number,
+): Promise<boolean | undefined> {
+  for (const ref of TRUNK_REFS) {
+    const result = await execa(
+      'git',
+      [
+        '-C',
+        root,
+        'log',
+        ref,
+        '-n',
+        '1',
+        '--format=%H',
+        ...grepArgs(pullRequest),
+        // The ref is a revision, and a repository tracking a path under the
+        // same name would otherwise fail the whole read as ambiguous.
+        '--',
+      ],
+      // `post-merge` drives the task verbs, and a hook exports the repository
+      // variables git reads ahead of `-C`, so the ambient environment would
+      // answer for whatever repository fired the hook.
+      {
+        reject: false,
+        timeout: GIT_TIMEOUT_MS,
+        env: gitEnv(),
+        extendEnv: false,
+      },
+    )
+
+    // A missing ref exits non-zero, which is the next ref's turn rather than an
+    // answer. An exit of zero with no commit is the ref saying the work is not
+    // on it, which is an answer and stops the walk.
+    if (result.exitCode === 0) return result.stdout.trim().length > 0
+  }
+
+  return undefined
+}

package/src/tasks/validate.ts

@@ -5,8 +5,10 @@ import {
   archiveDir,
   isReservedStem,
   readOutcomes,
+  readPullRequest,
   tasksDir,
 } from '@/tasks/archive'
+import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
 
 const ORDERING_FILE = 'priority.md'
 const BACKLOG_FILE = 'backlog.md'
@@ -486,17 +488,34 @@ function citedStem(cell: string): string | undefined {
   return stemOf(target)
 }
 
+/** What one blocker citation produced, since a row can be neither settled nor open. */
+interface CitedResult {
+  readonly findings: readonly Finding[]
+  readonly untested: readonly Untested[]
+}
+
+function nothing(): CitedResult {
+  return { findings: [], untested: [] }
+}
+
 /**
- * Reports what a cited task does to the row waiting on it. A live file whose
- * outcomes are all closed settles the row, and so does one sitting in the
- * archive. A file carrying no outcome box settles nothing, since a file the
- * check could not parse is not evidence of a finished one.
+ * Reports what a cited task does to the row waiting on it. A file sitting in
+ * the archive settles the row, and a live file settles it only once the work it
+ * carries is on the trunk. A file carrying no outcome box settles nothing,
+ * since a file the check could not parse is not evidence of a finished one.
  *
  * A citation resolving in neither folder is a broken pointer rather than a
  * closed task, and the two take different findings. Reading an absent file as
  * archived states a specific fact about a file nobody ever wrote, which is what
  * a renamed task or a typo produces.
  *
+ * A closed outcome is not the same fact as landed work. The ship chain marks
+ * outcomes as its first step and opens the pull request several steps later, so
+ * a check reading the checkbox reports the row settled while the branch is
+ * still in review. The pull request the task names is what the trunk is asked
+ * about, and a task naming none leaves the row untested rather than settled,
+ * because the only local signal left is the checkbox that produced the defect.
+ *
  * The outcome list comes off `readOutcomes` rather than a pattern of its own,
  * so this check cannot disagree with the archive and outcome verbs about which
  * checkboxes are outcomes and which sit inside a block a task displays.
@@ -506,42 +525,76 @@ async function checkCitedTask(
   subject: string,
   cited: string,
   root: string,
-): Promise<Finding[]> {
+  trunk: TrunkReader,
+): Promise<CitedResult> {
   const live = join(tasksDir(root), `${cited}.md`)
 
   if (!existsSync(live)) {
     if (existsSync(join(archiveDir(root), `${cited}.md`))) {
-      return [
+      return settled(group, subject, `waits on ${cited}, which is archived.`)
+    }
+
+    return {
+      findings: [
         {
-          kind: 'blocker-settled',
+          kind: 'blocker-unresolved',
           group,
           subject,
-          message: `waits on ${cited}, which is archived.`,
+          message: `waits on ${cited}, which is neither on the board nor archived.`,
         },
-      ]
+      ],
+      untested: [],
     }
-
-    return [
-      {
-        kind: 'blocker-unresolved',
-        group,
-        subject,
-        message: `waits on ${cited}, which is neither on the board nor archived.`,
-      },
-    ]
   }
 
-  const { open, closed } = readOutcomes(await readFile(live, 'utf8'))
-  if (open.length > 0 || closed.length === 0) return []
+  const text = await readFile(live, 'utf8')
+  const { open, closed } = readOutcomes(text)
+  if (open.length > 0 || closed.length === 0) return nothing()
 
-  return [
-    {
-      kind: 'blocker-settled',
+  const pullRequest = readPullRequest(text)
+  if (pullRequest === undefined) {
+    return untestedRow(
       group,
       subject,
-      message: `waits on ${cited}, which carries no open outcome.`,
-    },
-  ]
+      `waits on ${cited}, which closed every outcome but names no pull request, so nothing tests whether the work reached the trunk.`,
+    )
+  }
+
+  const landed = await trunk(pullRequest)
+  if (landed === undefined) {
+    return untestedRow(
+      group,
+      subject,
+      `waits on ${cited}, whose pull request #${pullRequest} could not be read against the trunk.`,
+    )
+  }
+
+  if (!landed) return nothing()
+
+  return settled(
+    group,
+    subject,
+    `waits on ${cited}, whose pull request #${pullRequest} reached the trunk.`,
+  )
+}
+
+function settled(
+  group: BoardGroup,
+  subject: string,
+  message: string,
+): CitedResult {
+  return {
+    findings: [{ kind: 'blocker-settled', group, subject, message }],
+    untested: [],
+  }
+}
+
+function untestedRow(
+  group: BoardGroup,
+  subject: string,
+  message: string,
+): CitedResult {
+  return { findings: [], untested: [{ group, subject, message }] }
 }
 
 /**
@@ -564,6 +617,7 @@ async function checkCitedTask(
 async function checkParked(
   rows: readonly BoardRow[],
   root: string,
+  trunk: TrunkReader,
 ): Promise<{ findings: Finding[]; untested: Untested[] }> {
   const findings: Finding[] = []
   const untested: Untested[] = []
@@ -578,7 +632,15 @@ async function checkParked(
     const contested = readPaths(cell)
 
     if (cited) {
-      findings.push(...(await checkCitedTask(row.group, subject, cited, root)))
+      const result = await checkCitedTask(
+        row.group,
+        subject,
+        cited,
+        root,
+        trunk,
+      )
+      findings.push(...result.findings)
+      untested.push(...result.untested)
     }
 
     const held = contested.filter((path) =>
@@ -613,12 +675,21 @@ function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
 
+export interface ValidateOptions {
+  /** Overridden by tests, which supply the trunk rather than reaching for git. */
+  readonly trunk?: TrunkReader
+}
+
 /**
  * Reports what every board row claims against what the tree holds. It writes
  * nothing: a row is a session's claim about readiness, and a validator that
  * repaired one would be asserting the claim it exists to test.
  */
-export async function validateBoard(root: string): Promise<ValidateOutcome> {
+export async function validateBoard(
+  root: string,
+  options: ValidateOptions = {},
+): Promise<ValidateOutcome> {
+  const trunk = options.trunk ?? gitTrunkReader(root)
   const dir = tasksDir(root)
   if (!existsSync(dir)) {
     return refuse('no-board', `No task board at ${dir}.`)
@@ -647,7 +718,7 @@ export async function validateBoard(root: string): Promise<ValidateOutcome> {
     : []
 
   const stems = await listTaskStems(dir)
-  const parked = await checkParked(rows, root)
+  const parked = await checkParked(rows, root, trunk)
 
   const findings = [
     ...checkMapping(rows, backlog, stems, dir),

package/standards/tasks.md

@@ -132,7 +132,11 @@ Add no fourth readiness group in place of this file. The three group names are t
 
 ## Validation
 
-`aitk tasks validate` reads the columns above and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a task file reached by neither surface, a task on both surfaces or in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task is archived or has closed every outcome and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+`aitk tasks validate` reads the columns above and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a task file reached by neither surface, a task on both surfaces or in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task reached the trunk and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+
+A cited task is settled by being archived, or by closing every outcome and carrying a `Pull request:` line the trunk holds. The closed checkbox alone settles nothing, because the ship chain marks outcomes as its first step and opens the pull request several steps later, so a row read off the checkbox reports settled while the branch is still in review. A task that closed every outcome and names no pull request, and one whose pull request the run could not read against the trunk, are both reported as untested. Degrading either back to the checkbox would reproduce the defect under a name claiming it was fixed.
+
+The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate happens several times a sweep and a fetch per run is a cost this check does not carry, so a clone behind the remote under-reports rather than claiming work landed.
 
 A task file is accounted for when a row on `priority.md` or a line on `backlog.md` names it, and reported when neither does. One check across both surfaces is what lets a task move between them without the move looking like a dropped file, and a task named by both is reported for the same reason a task in two groups is: it claims two things about itself and only one of them can hold. A project carrying no `backlog.md` is read as an empty backlog rather than refused, which leaves the one-to-one mapping this check ran before the second surface existed.
 
@@ -252,8 +256,16 @@ Archiving a task does not archive its plan. `claude-docs` owns the plans sweep a
 
 The row is matched by the link in its first cell rather than by a pattern against the whole line. A row names the task it is about in the first cell, so a link anywhere after that is a reference, such as a blocker pointing at what it waits on. Matching the line would delete the referring task's row too, on a board that is gitignored and has nothing to recover it from.
 
-Sweep the plan before archiving the task. The sweep finds its work by scanning the live folder, so a task archived first is beyond its reach for good, and the plan is left with no live task citing it and an archived task pointing at a path nothing will retarget. The archive refuses a task whose `Plan:` line still resolves inside `.claude/plans/` for that reason, which puts the ordering under a gate rather than under a convention the unattended caller cannot follow.
+Sweep the plan before archiving the task. The sweep finds its work by scanning the live folder, so a task archived first is beyond its reach for good, and the plan is left with no live task citing it and an archived task pointing at a path nothing will retarget. The archive refuses the last task pointing at a live plan for that reason, which puts the ordering under a gate rather than under a convention the unattended caller cannot follow.
+
+The gate counts the other live tasks citing the same plan rather than reading which folder the plan sits in. A plan several tasks share stays in the live folder by design, because the sweep is correct to leave a plan another live task still cites, so a gate reading the folder alone refuses every one of those tasks and the board and the sweep block each other with neither in the wrong. Counting the citations asks the question the gate means: a plan nothing else holds is one the sweep has yet to reach, and a plan a sibling still holds is one the sweep already decided about.
+
+The count resolves the target against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file and one plan two tasks spelled differently counts once. `aitk tasks plan-citations` exposes that count for a caller that wants it, and the gate reads it.
+
+The `claude-docs` sweep states the rule rather than calling that verb, which is a duplication accepted with a reason rather than an oversight. A skill reaches a target the moment it merges and the CLI reaches one only when a release publishes, so a body calling a verb the installed `aitk` predates gets no record back and sweeps nothing. The two spellings therefore have to agree by hand until a release carries the verb, and the failure they guard against is a plan stranded by the form its citation was written in.
+
+A caller reads the outcome off the record's `reason` field and never off the exit code. An operator's shell profile may wrap `aitk` in a function that runs the binary and then another command, taking its status from the second, which masks an ordinary refusal exactly as it masks an absent verb.
 
-That gate resolves the target against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file. `claude-docs` reads the line the same way, and two halves of one ordering that parsed it differently would leave a plan stranded by the form it was written in.
+Surviving a shared plan is not the same as sanctioning one. `standards/plan.md` puts one concern in one plan file, so a plan serving several tasks is a shape to correct rather than to build on, and the gate only stops it from deadlocking the board.
 
 A task with an open outcome stays on the board. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. The sweep is gated on the same condition, so archiving around an open outcome also leaves the plan behind.