@erclx/aitk 0.104.0 → 0.105.0

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/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/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.

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.