@erclx/aitk 0.103.0 → 0.104.1

package/src/sandbox/expect.ts

@@ -209,23 +209,35 @@ export function countMechanicalAssertions(expectation: Expectation): number {
   )
 }
 
+/**
+ * An entry carrying `*` is matched as a glob, so an arm can assert a file whose
+ * name a run derives. Reports the matched path rather than the pattern, since a
+ * pass on `lessons/0001-*.html` says nothing until the name it found is named.
+ */
 function checkPaths(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
-  return expectation.paths.map((path) =>
-    existsSync(join(sandboxDir, path))
-      ? { ok: true, message: `exists: ${path}` }
-      : { ok: false, message: `missing: ${path}` },
-  )
+  return expectation.paths.map((path) => {
+    const written = writtenUnder(path, sandboxDir)
+
+    return written
+      ? { ok: true, message: `exists: ${written}` }
+      : { ok: false, message: `missing: ${path}` }
+  })
 }
 
 /**
- * An entry carrying `*` is matched as a glob, which is what lets an arm forbid
- * a file whose name a run derives rather than fixes. Pinning one spelling of a
- * derived name passes vacuously against every other spelling, which reads as
- * coverage the arm does not have. Returns the offending path so a failure names
- * the file the run wrote rather than the pattern that caught it.
+ * The first file an entry matches, or undefined when it matches none. An entry
+ * carrying `*` is matched as a glob, which is what lets an arm name a file whose
+ * name a run derives rather than fixes. Pinning one spelling of a derived name
+ * passes vacuously against every other spelling, which reads as coverage the arm
+ * does not have.
+ *
+ * Returning the match rather than a boolean is what lets a result name the file
+ * the run wrote instead of the pattern that found it. A glob matching several
+ * files answers with one of them in no fixed order, so an arm asserting content
+ * through a glob seeds a folder holding one.
  */
 function writtenUnder(pattern: string, sandboxDir: string): string | undefined {
   if (!pattern.includes('*')) {
@@ -260,14 +272,18 @@ function checkAbsent(
  * throwing, since an arm may assert content without also listing the path. A
  * pattern that does not compile is a defect in the declaration, so it fails the
  * assertion it belongs to rather than aborting the whole verdict.
+ *
+ * A path carrying `*` resolves to the file it matched, and falls back to itself
+ * when it matched none so the miss is reported against the entry as written.
  */
 function checkContent(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
   return expectation.content.map(({ path, pattern }) => {
-    const full = join(sandboxDir, path)
-    const label = `${path} =~ ${pattern}`
+    const matched = writtenUnder(path, sandboxDir) ?? path
+    const full = join(sandboxDir, matched)
+    const label = `${matched} =~ ${pattern}`
 
     let matcher: RegExp
     try {
@@ -279,6 +295,7 @@ function checkContent(
     if (!existsSync(full) || !statSync(full).isFile()) {
       return { ok: false, message: `no file to match: ${path}` }
     }
+
     if (matcher.test(readFileSync(full, 'utf8'))) {
       return { ok: true, message: `matches: ${label}` }
     }

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),