@erclx/aitk 0.97.1 → 0.98.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.97.1",
+  "version": "0.98.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -1,17 +1,17 @@
 ---
 title: Orchestrator parked row runbook
-description: Re-testing every parked blocker against the current tree, the trigger that separates this pass from the merge sweep, and the two ways a re-test goes wrong
+description: Re-testing every parked blocker against the current tree, the two triggers that start the pass, and the two ways a re-test goes wrong
 ---
 
 Re-test every parked row as orchestrator. A blocker cell is a measurement taken the day the row was parked and nothing re-takes it, so a row can wait on a condition that stopped holding weeks earlier with no surface reporting the gap.
 
-Run this when nothing merged and the board is not moving. Workers are building, no pull request is waiting on a first pass, and the session is otherwise idle.
+Two triggers start this pass. `orchestrator-sweep.md` ends by sending the rows `aitk tasks validate` listed as untested here, because a merge changes the tree under every parked row at once rather than under the rows naming it. The other is an idle session: nothing merged, workers are building, no pull request is waiting on a first pass, and the board is not moving.
 
-That trigger is the inverse of the sweep's. `orchestrator-sweep.md` runs after a batch of merges and asks which parked row to promote next, taking the blocker cell as read. This pass asks whether that cell is still true. Both walk the same rows and both can end in a promotion, so a session reading them as one pass runs whichever it remembers and re-tests nothing.
+The two differ in scope rather than in procedure. A merge sends the untested rows, since the validator already re-took the two kinds it can settle. An idle session walks every parked row, because no event narrowed which of them to look at.
 
-A merge is still worth following with this pass even though the sweep already ran. A merge changes the tree under every parked row at once rather than under the rows naming it, and the sweep re-reads none of them.
+Neither trigger is a scheduler. `orchestrator-poll.md` owns the one recurring trigger this skill has, and a second loop firing into a static board is the always-on failure that file already warns about.
 
-Nothing starts this pass, and it takes no scheduler of its own. `orchestrator-poll.md` owns the one recurring trigger this skill has, and a second loop firing into a static board is the always-on failure that file already warns about.
+The sweep's own question stays distinct from this one. It asks which parked row to promote next, taking the blocker cell as read, and this pass asks whether that cell is still true. A session collapsing them runs whichever it remembers and re-tests nothing.
 
 ## Scope
 
@@ -21,10 +21,10 @@ Take the rows in board order and finish one before opening the next. Clearing a
 
 ## Re-testing a row
 
-The blocker cell states what the row waits on, and each kind is tested differently.
+The blocker cell states what the row waits on, and each kind is tested differently. `aitk tasks validate` already re-takes the first two and reports the rest as untested, so run it first and re-take by hand only what it names.
 
-- Collision with a track in flight: intersect the row's Touches column with that of every `## Run now` row. A track that merged since the row was parked is no longer in flight, whatever the sets still share. A `## Needs a plan` row carries no Touches column, so read its file set off the task file before claiming a collision either way.
-- A dependency on another task: open that task. One whose outcomes are all `[x]`, or one already archived, holds nothing.
+- Collision with a track in flight: the validator tests the file the cell cites against the Touches column of every `## Run now` row. A track that merged since the row was parked is no longer in flight, whatever the sets still share. A cell naming the file in prose rather than in backticks cites nothing, so write the collision the way the board format spells it and the check picks the row up on the next run.
+- A dependency on another task: the validator opens the task a link in the cell names. One whose outcomes are all `[x]`, or one already archived, holds nothing. A cell naming the task in prose resolves to no file, so open it by hand and rewrite the cell as a link.
 - A condition about the tree, such as a count of some shape or the presence of a construct: measure it again, per Two ways a re-test goes wrong below.
 - Waiting on a plan: nothing external holds the row, so the pass writes the plan rather than testing anything. See The plan half below.
 - Waiting on an operator action, such as a run that happens from a shell: record it as untestable this pass and name what the operator has to do. A session cannot clear it, and re-measuring it every pass is waste.

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

@@ -10,7 +10,9 @@ Sweep the board as orchestrator after merging. Run this once per batch of merges
 3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
 4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
 
-Run `aitk tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, maps rows against task files both ways, and tests the `## Run now` file sets for overlap, which is the half of the readiness claim a reading of the board cannot check. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
+Run `aitk tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, maps rows against task files both ways, tests the `## Run now` file sets for overlap, and re-takes the two blocker kinds a command can settle. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
+
+Then run `orchestrator-parked.md` over the rows the validator listed as untested. Those carry the three blocker kinds no command settles, and the merge this sweep followed changed the tree under every one of them at once while the refill above re-read none. Take the untested rows alone rather than the whole board, since the validator already answered the rest.
 
 Place every finding the merged work produced before promoting anything. A finding that changes a rule goes to the standard or the rule that states it, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. A pull request body counts as nowhere, since the thread stops being read the moment it merges.
 

package/docs/agents/commands.md

@@ -29,7 +29,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                       |
 | `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                  |
 | `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                 |
-| `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)                                                      |
+| `aitk tasks validate`      | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`)                                             |
 | `aitk intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                     |
 | `aitk intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                            |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                              |

package/docs/agents/tasks.md

@@ -90,17 +90,40 @@ aitk tasks validate
 aitk tasks validate --json
 ```
 
-Four checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states, and the second reaches only the collision reason that half names, since the other blocker kinds put no fact on disk to check against. Mapping and Grouping test the folder contract and hold for every group:
+Five checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group. Blockers reaches the rows outside `## Run now`:
 
-| Check      | What it reports                                                                   |
-| ---------- | --------------------------------------------------------------------------------- |
-| Plan       | A `## Run now` row whose Plan column carries no link, or one resolving to no file |
-| Mapping    | A row naming no task file, and a task file no row names                           |
-| Grouping   | A task carrying a row in more than one readiness group                            |
-| Collisions | Two `## Run now` rows whose Touches columns name a path in common                 |
+| Check      | What it reports                                                                      |
+| ---------- | ------------------------------------------------------------------------------------ |
+| Plan       | A `## Run now` row whose Plan column carries no link, or one resolving to no file    |
+| Mapping    | A row naming no task file, and a task file no row names                              |
+| Grouping   | A task carrying a row in more than one readiness group                               |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                    |
+| Blockers   | A parked row whose blocker has stopped holding, or whose cited task resolves nowhere |
 
 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.
+
+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.
+
+A citation resolving in neither the board nor the archive is `blocker-unresolved` rather than a settled row. 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, and only a task that genuinely closed releases the row waiting on it.
+
+The other three kinds rest on a person's judgment, so a row neither half reached lands in a second array rather than in the findings:
+
+```json
+{
+  "untested": [
+    {
+      "group": "Needs a plan",
+      "subject": "v50.6-a-standard-no-skill-reads",
+      "message": "..."
+    }
+  ]
+}
+```
+
+An untested row is not a finding and moves no exit code. Reading a clean findings list as a clean board is the failure the array exists to prevent, and `orchestrator-parked.md` is the pass that takes those rows by hand.
+
 Exit codes: `0` every check passed, `1` refused, `2` at least one finding. The `reason` field carries which gate refused: `no-board`, `no-ordering`, or `no-groups`. A board grouping under headings of its own trips `no-groups` rather than being read against columns it never declared.
 
 Columns are read from each table's own header rather than by position, so a project whose board differs from this one is reported for what it lacks. The `index` and `priority` siblings are skipped, along with every pre-compaction handoff, which takes one file per session under a `session-` prefix. None of them is a task, and a handoff counted as one would be reported as a task carrying no row on every session that wrote one.

package/docs/ai-workflow.md

@@ -103,7 +103,7 @@ 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 last check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. 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.
+`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: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.
 

package/package.json

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

package/src/commands/tasks.ts

@@ -11,6 +11,7 @@ import {
 } from '@/tasks/record'
 import {
   type Finding,
+  type Untested,
   type ValidateOutcome,
   validateBoard,
 } from '@/tasks/validate'
@@ -458,6 +459,19 @@ function reportValidation(
     } else {
       for (const finding of outcome.findings) logWarn(describe(finding))
     }
+
+    // The untested rows carry the warn glyph rather than the pass glyph. They
+    // move no exit code, and a green tick on a row nothing re-took is the
+    // misread this section exists to prevent.
+    logStep('Parked rows')
+    if (outcome.untested.length === 0) {
+      logInfo('every parked row carried a citation or a file set to re-test')
+    } else {
+      logWarn(
+        `${outcome.untested.length} row(s) carry a blocker no check can settle`,
+      )
+      for (const row of outcome.untested) logWarn(describeUntested(row))
+    }
     outro()
   }
 
@@ -469,6 +483,7 @@ function reportValidation(
         rows: outcome.rows,
         tasks: outcome.tasks,
         findings: outcome.findings,
+        untested: outcome.untested,
       })}\n`,
     )
   }
@@ -481,6 +496,10 @@ function describe(finding: Finding): string {
   return `${scope}${finding.subject} ${finding.message}`
 }
 
+function describeUntested(row: Untested): string {
+  return `${row.group}: ${row.subject} ${row.message}`
+}
+
 async function runArchive(
   task: string | undefined,
   opts: ArchiveCommandOptions,

package/src/tasks/validate.ts

@@ -1,7 +1,12 @@
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { isReservedStem, tasksDir } from '@/tasks/archive'
+import {
+  archiveDir,
+  isReservedStem,
+  readOutcomes,
+  tasksDir,
+} from '@/tasks/archive'
 
 const ORDERING_FILE = 'priority.md'
 
@@ -31,6 +36,8 @@ export const FINDING_KINDS = [
   'row-duplicated',
   'touches-unstated',
   'touches-collided',
+  'blocker-settled',
+  'blocker-unresolved',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -42,6 +49,17 @@ export interface Finding {
   readonly message: string
 }
 
+/**
+ * A parked row neither half of the blocker check reached. Three of the five
+ * blocker kinds put no fact on disk, so a run reporting findings alone would
+ * read as a board with nothing stale on it.
+ */
+export interface Untested {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
 export interface BoardRow {
   readonly group: BoardGroup
   readonly label: string
@@ -49,6 +67,8 @@ export interface BoardRow {
   readonly plan: string | undefined
   /** Absent when the group fixes no `Touches` column, empty when it read none. */
   readonly touches: readonly string[] | undefined
+  /** Absent when the group fixes no `Waiting on` column, which is `## Run now`. */
+  readonly waiting: string | undefined
 }
 
 export interface ValidateReport {
@@ -56,6 +76,7 @@ export interface ValidateReport {
   readonly rows: number
   readonly tasks: number
   readonly findings: readonly Finding[]
+  readonly untested: readonly Untested[]
 }
 
 export interface ValidateRefused {
@@ -185,6 +206,7 @@ export function readBoard(text: string): {
     const taskAt = columnIndex(header, 'task')
     const planAt = columnIndex(header, 'plan')
     const touchesAt = columnIndex(header, 'touches')
+    const waitingAt = columnIndex(header, 'waiting on')
 
     const task = taskAt >= 0 ? (cells[taskAt] ?? '') : ''
     const target = linkTarget(task)
@@ -196,6 +218,7 @@ export function readBoard(text: string): {
       stem: target ? stemOf(target) : undefined,
       plan,
       touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
+      waiting: waitingAt >= 0 ? (cells[waitingAt] ?? '') : undefined,
     })
   }
 
@@ -359,6 +382,142 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
   return findings
 }
 
+/**
+ * Reads the task a blocker cell cites. A task pointer is a bare sibling
+ * filename, the way every `Task` column spells one, so a target carrying a
+ * directory names something else and yields nothing. A row waiting on a plan
+ * links that plan, and reading its stem as a task would report the row settled
+ * against a folder the plan does not sit in.
+ */
+function citedStem(cell: string): string | undefined {
+  const target = linkTarget(cell)?.split('#')[0]
+  if (!target || target.includes('/')) return undefined
+  return stemOf(target)
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+async function checkCitedTask(
+  group: BoardGroup,
+  subject: string,
+  cited: string,
+  root: string,
+): Promise<Finding[]> {
+  const live = join(tasksDir(root), `${cited}.md`)
+
+  if (!existsSync(live)) {
+    if (existsSync(join(archiveDir(root), `${cited}.md`))) {
+      return [
+        {
+          kind: 'blocker-settled',
+          group,
+          subject,
+          message: `waits on ${cited}, which is archived.`,
+        },
+      ]
+    }
+
+    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 []
+
+  return [
+    {
+      kind: 'blocker-settled',
+      group,
+      subject,
+      message: `waits on ${cited}, which carries no open outcome.`,
+    },
+  ]
+}
+
+/**
+ * Re-takes the two blocker kinds a command can settle, over every row outside
+ * `## Run now`. A cited task is settled by being archived or by closing every
+ * outcome, and a cited path is settled by no `## Run now` row still holding it.
+ *
+ * Both halves gate on a citation the cell carries, never on a column beside it.
+ * The board standard 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 its
+ * `Touches` column says nothing about what holds it. Reading that column
+ * instead reports a cleared collision on a row no collision ever parked, and
+ * counts the row as re-tested, which is the more expensive half of that error.
+ *
+ * The cell is read for citations rather than parsed into fields, since the
+ * standard fixes three forms for it and leaves it prose. A row neither half
+ * reached is returned as untested, because the other three kinds are a person's
+ * to judge and silence about them reads as a board with nothing stale on it.
+ */
+async function checkParked(
+  rows: readonly BoardRow[],
+  root: string,
+): Promise<{ findings: Finding[]; untested: Untested[] }> {
+  const findings: Finding[] = []
+  const untested: Untested[] = []
+  const running = rows.filter((row) => row.group === 'Run now')
+
+  for (const row of rows) {
+    if (row.group === 'Run now') continue
+
+    const subject = row.stem ?? row.label
+    const cell = row.waiting ?? ''
+    const cited = citedStem(cell)
+    const contested = readPaths(cell)
+
+    if (cited) {
+      findings.push(...(await checkCitedTask(row.group, subject, cited, root)))
+    }
+
+    const held = contested.filter((path) =>
+      running.some((run) =>
+        (run.touches ?? []).some((other) => sharesPath(path, other)),
+      ),
+    )
+
+    if (contested.length > 0 && held.length === 0) {
+      findings.push({
+        kind: 'blocker-settled',
+        group: row.group,
+        subject,
+        message: `waits on ${contested.join(', ')}, which nothing under Run now holds.`,
+      })
+    }
+
+    if (!cited && contested.length === 0) {
+      untested.push({
+        group: row.group,
+        subject,
+        message:
+          'cites no task and no file, so neither half of its blocker is mechanical.',
+      })
+    }
+  }
+
+  return { findings, untested }
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -389,12 +548,20 @@ export async function validateBoard(root: string): Promise<ValidateOutcome> {
   }
 
   const stems = await listTaskStems(dir)
+  const parked = await checkParked(rows, root)
 
   const findings = [
     ...checkMapping(rows, stems, dir),
     ...checkPlans(rows, dir, root),
     ...checkCollisions(rows),
+    ...parked.findings,
   ]
 
-  return { ok: true, rows: rows.length, tasks: stems.length, findings }
+  return {
+    ok: true,
+    rows: rows.length,
+    tasks: stems.length,
+    findings,
+    untested: parked.untested,
+  }
 }

package/standards/tasks.md

@@ -65,7 +65,7 @@ The `Waiting on` column under `## Up next` carries that reason in one of three f
 
 Under `## Up next` a collision names the file held by the task already running, a sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
 
-`aitk tasks validate` reads those columns and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a row and a task file that do not map one to one, a task in two groups, and two `## Run now` rows touching a path in common. It does not read the `Waiting on` cell, so that test holds on reading alone. 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 those columns and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a row and a task file that do not map one to one, a task 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.
 
 ```markdown
 ---