@erclx/aitk 3.34.1 → 3.35.0

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

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

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

@@ -37,7 +37,9 @@ No count binds this. List the files the candidate's plan touches, from its `**Fi
 
 The board is not the whole set. A track a person launched by hand carries no row, so that column cannot see it, which is the ordinary shape whenever the operator is launching rather than dispatching. Read `aitk sessions list --json` for the branches in flight, and take the file set of any branch no row names from the plan that branch is building. A candidate cleared against the board alone is cleared against a partial reading.
 
-Take the comparison at the file path rather than at a folder above it. `aitk tasks validate` compares path segments, and on 2026-08-28 it reported two rows as colliding on `src` where one writes `src/github.ts` and the other `src/markdown/structure.ts`. Most of the CLI sits under `src/`, so a folder-level reading fires on nearly every parallel pair and buries the one real collision that same run caught, `.claude/ARCHITECTURE.md` held by two rows. Read that verb's output as a candidate list and settle each pair by file.
+Take the comparison at the file path rather than at a folder above it. `aitk tasks validate` compares the paths each row wrote, so a collision it reports on a folder means a row's Touches cell claimed that folder rather than the verb widening anything. On 2026-08-28 it called two rows colliding on `src` because one cell named the bare folder while the other wrote `src/markdown/structure.ts`, which this paragraph once misread as the verb comparing path segments too coarsely.
+
+The finding names which row contributed the containing path, and a bare-folder cell reports as a claim of its own beside the findings. Read that output as a candidate list, settle each pair by file, and narrow the cell that over-claimed rather than discounting the collision it caused.
 
 Disjointness is necessary and not sufficient, so hold a candidate whose sets do not touch when a stated reason serializes it, and write the reason on the hold. One row creating a skill and another auditing that catalog and counting it write nothing in common, measured 2026-08-27, and dispatching both still leaves the audit counting a denominator that moves underneath it. Nothing verifies that a reason was written, so the rule holds only while the dispatcher applies it.
 

package/docs/agents/tasks.md

@@ -129,6 +129,8 @@ 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.
 
+Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical, which is how a correct report was once read as the verb comparing folders rather than files.
+
 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.
@@ -155,6 +157,24 @@ The other three kinds rest on a person's judgment, so a row neither half reached
 
 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.
 
+A `## Run now` row whose Touches column names a bare folder lands in a third array on the same reasoning:
+
+```json
+{
+  "claims": [
+    {
+      "group": "Run now",
+      "subject": "v1.0-first",
+      "message": "claims the whole src/tasks folder, so it collides with every row written under it."
+    }
+  ]
+}
+```
+
+That claim collides with every row a later session writes under the folder, and it is legitimate whenever the row does rewrite the directory, so the array states the reach and moves no exit code. A measure failing on a cell that is right teaches a reader to skip it. Folder against file is decided by asking the tree for a path that resolves, and by the extension only for a path the row has yet to create, since the name alone reads a file carrying no extension as a folder.
+
+The scan reaches `## Run now` and stops, where the collision check stops. A cell in another group describes work nobody has planned, written as a sentence and rewritten once a plan exists, so a claim read off one reports on prose rather than on a file set. A parked folder claim surfaces when its row is promoted, which is when the cell becomes something a dispatcher can act on.
+
 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`, `priority`, and `backlog` 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/package.json

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

package/src/commands/tasks.ts

@@ -17,6 +17,7 @@ import {
 } from '@/tasks/record'
 import {
   type Finding,
+  type FolderClaim,
   type Untested,
   type ValidateOutcome,
   validateBoard,
@@ -581,6 +582,16 @@ function reportValidation(
       )
       for (const row of outcome.untested) logWarn(describeUntested(row))
     }
+
+    // A folder claim is often the correct way to say a row rewrites a whole
+    // directory, so it reports beside the findings and moves no exit code. A
+    // measure that fails on a legitimate cell trains a reader to skip it.
+    logStep('Folder claims')
+    if (outcome.claims.length === 0) {
+      logInfo('every run now row names files rather than folders')
+    } else {
+      for (const claim of outcome.claims) logWarn(describeClaim(claim))
+    }
     outro()
   }
 
@@ -594,6 +605,7 @@ function reportValidation(
         tasks: outcome.tasks,
         findings: outcome.findings,
         untested: outcome.untested,
+        claims: outcome.claims,
       })}\n`,
     )
   }
@@ -610,6 +622,10 @@ function describeUntested(row: Untested): string {
   return `${row.group}: ${row.subject} ${row.message}`
 }
 
+function describeClaim(claim: FolderClaim): string {
+  return `${claim.group}: ${claim.subject} ${claim.message}`
+}
+
 async function runArchive(
   task: string | undefined,
   opts: ArchiveCommandOptions,

package/src/tasks/validate.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import {
@@ -63,6 +63,19 @@ export interface Untested {
   readonly message: string
 }
 
+/**
+ * A `Touches` cell naming a bare folder, which claims every file under it and
+ * so collides with every row a later session writes there. The claim is often
+ * correct, since a row rewriting a whole directory has no other way to say so,
+ * which is why it reports beside the findings rather than inside them and moves
+ * no exit code.
+ */
+export interface FolderClaim {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
 /**
  * A backlog line, which carries a pointer and nothing else. The backlog is
  * explicitly unordered, so a line has no position to read and no columns to
@@ -91,6 +104,7 @@ export interface ValidateReport {
   readonly tasks: number
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
+  readonly claims: readonly FolderClaim[]
 }
 
 export interface ValidateRefused {
@@ -164,6 +178,23 @@ function sharesPath(left: string, right: string): boolean {
   )
 }
 
+/**
+ * Whether a `Touches` path names a directory. The tree answers for a path that
+ * resolves, which is the only reading that separates a folder from a file
+ * carrying no extension, such as a hook script.
+ *
+ * A path the row has yet to create resolves to nothing, so the name decides
+ * there. `readPaths` admits a span for one of two reasons, a slash or an
+ * extension, so a span surviving without an extension is one a slash let
+ * through and reads as a folder.
+ */
+function isFolder(path: string, root: string): boolean {
+  const target = resolve(root, path)
+  if (existsSync(target)) return statSync(target).isDirectory()
+
+  return !/\.[A-Za-z][A-Za-z0-9]*$/.test(path)
+}
+
 function splitCells(line: string): string[] {
   return line
     .trim()
@@ -457,17 +488,22 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
     for (let j = i + 1; j < ready.length; j += 1) {
       const left = ready[i]
       const right = ready[j]
-      const shared = (left.touches ?? []).filter((path) =>
-        (right.touches ?? []).some((other) => sharesPath(path, other)),
-      )
+      const shared = (left.touches ?? []).flatMap((path) => {
+        const other = (right.touches ?? []).find((candidate) =>
+          sharesPath(path, candidate),
+        )
+        return other === undefined
+          ? []
+          : [describeShared(path, other, left, right)]
+      })
 
       if (shared.length === 0) continue
 
       findings.push({
         kind: 'touches-collided',
         group: 'Run now',
-        subject: `${left.stem ?? left.label} and ${right.stem ?? right.label}`,
-        message: `both touch ${shared.join(', ')}.`,
+        subject: `${subjectOf(left)} and ${subjectOf(right)}`,
+        message: `both touch ${joinShared(shared)}.`,
       })
     }
   }
@@ -475,6 +511,75 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
   return findings
 }
 
+function subjectOf(row: BoardRow): string {
+  return row.stem ?? row.label
+}
+
+/**
+ * Names one path two rows share, and the row that claimed it as a folder when
+ * one side named a directory holding the other's file. Which side contributed
+ * the containing path is the fact a reader acts on, and printing the shared
+ * strings alone leaves an over-broad cell and a genuine overlap identical.
+ *
+ * The shorter path is the container, because `sharesPath` holds for an unequal
+ * pair only when one is a prefix of the other up to a separator.
+ */
+function describeShared(
+  path: string,
+  other: string,
+  left: BoardRow,
+  right: BoardRow,
+): string {
+  if (path === other) return path
+
+  const container = path.length < other.length ? path : other
+  const owner = container === path ? left : right
+  return `${container}, which ${subjectOf(owner)} claims as a folder`
+}
+
+/**
+ * A folder clause carries a comma of its own, so a comma between clauses would
+ * read as another path. The plain list keeps the comma it has always had.
+ */
+function joinShared(clauses: readonly string[]): string {
+  const separator = clauses.some((clause) => clause.includes(',')) ? '; ' : ', '
+  return clauses.join(separator)
+}
+
+/**
+ * Reports a `Touches` cell naming a bare folder. The claim collides with every
+ * row a later session writes under that folder, and it is legitimate whenever
+ * the row does rewrite the directory, so this states the reach rather than
+ * calling it a defect.
+ *
+ * The scan takes `## Run now` alone, where `checkCollisions` takes it. A cell in
+ * another group describes work nobody has planned, so it is written as a
+ * sentence and rewritten at planning time, and a claim read off one reports on
+ * prose rather than on a file set. That is the shape that teaches a reader to
+ * skip the report. A parked folder claim surfaces when the row is promoted,
+ * which is also when its cell becomes a set anything can act on.
+ */
+function checkFolderClaims(
+  rows: readonly BoardRow[],
+  root: string,
+): FolderClaim[] {
+  const claims: FolderClaim[] = []
+
+  for (const row of rows.filter((candidate) => candidate.group === 'Run now')) {
+    for (const path of row.touches ?? []) {
+      if (!isFolder(path, root)) continue
+
+      claims.push({
+        group: row.group,
+        subject: subjectOf(row),
+        message: `claims the whole ${path} folder, so it collides with every row written under it.`,
+      })
+    }
+  }
+
+  return claims
+}
+
 /**
  * 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
@@ -734,5 +839,6 @@ export async function validateBoard(
     tasks: stems.length,
     findings,
     untested: parked.untested,
+    claims: checkFolderClaims(rows, root),
   }
 }