@erclx/aitk 3.34.1 → 3.35.1

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.1",
   "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/markdown-audit.md

@@ -61,7 +61,7 @@ Two ban shapes stay unmeasured and the report says so on every run. A multi-word
 
 ### Bullets, paragraphs, and depth
 
-Bullet weight and depth are the checks that moved off `aitk context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero and ending in a colon, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
+Bullet weight and depth are the checks that moved off `aitk context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
 
 Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan above: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
 
@@ -136,7 +136,7 @@ Measured at `4b7b13a2` across 444 files with the paragraph checkpoint at 600: 8
 
 The ban half reached zero, which was the precondition the gate waited on, and it was re-measured against the same corpus at the moment the gate landed. Three sweep slices then took the structural half, and the corpus reports 1 heavy bullet and 22 heavy paragraphs across 6 files on 2026-08-06, every one on a ground the triage record holds as exempt.
 
-Depth is the one measure no slice triaged, so its figure moved with the sweep rather than with the corpus. The break rule widened to bold section markers on 2026-08-28, which drops the count again with no edit to any file, so the 41 above reads against a rule the command no longer runs. Read all four structural counts from a run rather than from this paragraph.
+Depth is the one measure no slice triaged, so its figure moved with the sweep rather than with the corpus. The break rule widened to bold section markers on 2026-08-28 and again to the colon-less ones the same day, and each drop came with no edit to any file, so the 41 above reads against a rule the command no longer runs. Read all four structural counts from a run rather than from this paragraph.
 
 ### What a hit asks of an author
 

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.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/markdown.ts

@@ -520,7 +520,7 @@ function reportDepth(
     'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
   )
   logInfo(
-    'A heading breaks a run and so does a bold section marker at column zero ending in a colon, such as a line reading only Risks in bold. A colon-less or indented one stays prose.',
+    'A heading breaks a run and so does a bold section marker at column zero, such as a line reading only Risks in bold. A colon-less one breaks when it holds one whole code span, or when it runs to 20 characters or fewer, and an indented one stays prose.',
   )
 
   const over = reports

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/markdown/structure.ts

@@ -19,19 +19,51 @@ const HEADING = /^#{1,6}\s/
  * headings was the alternative and it clears no plan already written, leaving
  * each flagged until someone rewrites it.
  *
- * The marker starts at column zero and carries a colon, and the whole line is
- * the marker or none of it is. A bold phrase opening a sentence is emphasis
- * rather than a seam, and an indented one is a label inside a list item, so
- * both stay prose. This ships as package data every project reads, where a
- * missed break costs one unbroken run and a false one shortens every run around
- * it until the measure stops reporting, which is the dearer of the two.
- *
- * The colon is what a colon-less `**Testing**` is held out by, and that shape
- * is a real section marker in a review body rather than a hypothetical. Widening
- * to reach it moves the shipped pattern rather than the wording, so the rule
- * states the colon and the widening stays open for a decision of its own.
+ * The marker starts at column zero and the whole line is the marker or none of
+ * it is. A bold phrase opening a sentence is emphasis rather than a seam, and
+ * an indented one is a label inside a list item, so both stay prose. This ships
+ * as package data every project reads, where a missed break costs one unbroken
+ * run and a false one shortens every run around it until the measure stops
+ * reporting, which is the dearer of the two.
+ *
+ * A colon ends most markers and not all of them. `claude-pr-review` writes
+ * three colon-less ones into every body it posts and a bold path heading for
+ * each file it reviews, so requiring the colon held a real seam out. Two
+ * signals stand in where the colon is absent, because the shape a marker has to
+ * be told from is a sentence set in bold and no one test separates both kinds
+ * of marker from it.
+ *
+ * A label that is one whole code span breaks at any width. A path runs long and
+ * a sentence set in bold is never a single span, so shape settles this half
+ * where width cannot. Across 81 colon-less markers in the review bodies posted
+ * on this repository, the 30 path headings run from 20 to 70 characters, and no
+ * colon-less line in the records tree is a whole span at all, so the rule adds
+ * reach without adding a false break.
+ *
+ * `MARKER_WIDTH` covers the rest and is read off the corpus rather than picked.
+ * Of the remaining 51 markers in those review bodies, 50 sit at or under 20
+ * visible characters, and so do 48 of the 94 colon-less lines in the records
+ * tree at `9960a4d7`, every one of them a label. The 21 to 30 band above it
+ * holds 8 lines nobody can classify on sight, where `One change across four
+ * files.` reads as a sentence and `Rule plus a mechanical half` reads as a
+ * seam, so the ceiling sits under that band rather than over it. That is where
+ * the asymmetry above points, a false break being the dearer error. Terminal
+ * punctuation separates nothing, since 45 of the 48 shortest colon-less lines
+ * end in one.
+ *
+ * Both signals govern the colon-less shape alone. A colon is its own evidence
+ * of a label, and capping the colon form as well takes the break back from four
+ * markers between 31 and 50 characters that already have it, every one of them
+ * a genuine section marker.
+ *
+ * One marker in that review corpus is reached by neither signal, a 48-character
+ * heading a session wrote by hand rather than from the template. Widening to
+ * catch it means raising the ceiling back through the band, so it is left as
+ * the cheap error the asymmetry above already names.
  */
-const SECTION_MARKER = /^\*\*[^*]+:\*\*\s*$/
+const BOLD_LINE = /^\*\*([^*]+)\*\*\s*$/
+const SPAN_LABEL = /^`[^`]+`$/
+const MARKER_WIDTH = 20
 
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 const TABLE_ROW = /^\s*\|/
@@ -272,11 +304,33 @@ function isTableRun(run: readonly BodyLine[]): boolean {
   return separators > 0
 }
 
+/**
+ * Reports whether a line is a section marker rather than emphasis.
+ *
+ * `BOLD_LINE` fixes the shape, and a colon-less label then answers to
+ * `SPAN_LABEL` or to `MARKER_WIDTH`, per the record above. Both read visible
+ * text, which reduces a link to its anchor text and leaves a backticked path
+ * counted whole, the same reading `isScannablePeerList` takes. The reduction is
+ * what lets a linked path reach the span test at all, since the markup around
+ * it would fail the pattern the destination is still attached.
+ */
+function isSectionMarker(text: string): boolean {
+  const marker = text.match(BOLD_LINE)
+  if (!marker) return false
+
+  const label = marker[1]
+  if (label.endsWith(':')) return true
+
+  const visible = visibleText(label)
+
+  return SPAN_LABEL.test(visible) || visible.length <= MARKER_WIDTH
+}
+
 /**
  * Measures the longest run of lines no signpost breaks, in rendered lines.
  *
  * A heading breaks a run and so does a section marker, which is the same
- * signpost written the way a template asked for it. `SECTION_MARKER` above
+ * signpost written the way a template asked for it. `isSectionMarker` above
  * fixes which lines qualify.
  *
  * Fenced lines are skipped rather than treated as breaks, per the standard:
@@ -325,7 +379,7 @@ export function longestRun(
   for (const line of lines) {
     if (line.fenced) continue
 
-    if (HEADING.test(line.text) || SECTION_MARKER.test(line.text)) {
+    if (HEADING.test(line.text) || isSectionMarker(line.text)) {
       close()
       continue
     }

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

package/standards/markdown.md

@@ -37,7 +37,8 @@ Does not govern:
 - Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.
 - Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there.
 - Break a run on a bold section marker holding its line alone, the way a heading breaks one. A document whose template separates sections with `**Risks:**` rather than `## Risks` has written the seam a reader lands on, and reading only the heading reported every such file at its full length whatever it carried.
-- Require the marker to start at column zero and to end in a colon inside the bold, and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item. A colon-less `**Testing**` does not break either, which holds a real section marker out and is the cost of keeping the pattern narrow on data every project is measured against.
+- Require the marker to start at column zero and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item.
+- Break a colon-less marker on either of two signals, since no one test separates every marker from a sentence set in bold. A label that is one whole code span breaks at any width, which is how a bold line holding only a backticked path reads as the file heading it is. Anything else breaks at 20 characters or fewer, which reaches `**Testing**` and leaves a bold sentence as prose.
 
 ## Paragraphs and lists