@erclx/aitk 3.34.0 → 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.0",
+  "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/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`, unchanged in what they measure. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run of lines no heading breaks reports past roughly 40 rendered lines, measured at 80 columns, 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 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.
 
 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. 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, 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.
 
 ### 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.0",
+  "version": "3.35.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/markdown.ts

@@ -519,6 +519,9 @@ function reportDepth(
   logInfo(
     '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.',
+  )
 
   const over = reports
     .filter((report) => report.structure.longestRun > checkpoints.run)

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

@@ -1,6 +1,38 @@
 import { type BodyLine, visibleText } from '@/markdown/scan'
 
 const HEADING = /^#{1,6}\s/
+
+/**
+ * A section marker holding its line alone, which is the signpost a document
+ * uses where its own template asks for bold rather than a heading.
+ *
+ * `standards/plan.md` gives `## Summary` a heading and marks the four sections
+ * below it this way, so a conforming plan read as one run from its first line
+ * to its last and all seven live plans reported past the depth checkpoint, at
+ * 106 to 166 rendered lines. A measure firing on a whole corpus says nothing
+ * about it, and it costs more than silence, since a reader who learns to skip
+ * the depth section skips it on the file where a deep run genuinely sits.
+ *
+ * Breaking on the marker clears two of those seven and moves the other five
+ * onto the seams inside them, at 42 to 77 lines, which is the measure telling
+ * a long section from a long file for the first time. Moving the template to
+ * 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.
+ */
+const SECTION_MARKER = /^\*\*[^*]+:\*\*\s*$/
+
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
@@ -241,7 +273,11 @@ function isTableRun(run: readonly BodyLine[]): boolean {
 }
 
 /**
- * Measures the longest run of lines no heading breaks, in rendered lines.
+ * 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
+ * fixes which lines qualify.
  *
  * Fenced lines are skipped rather than treated as breaks, per the standard:
  * they leave the count without ending the run, so prose either side of an
@@ -289,7 +325,7 @@ export function longestRun(
   for (const line of lines) {
     if (line.fenced) continue
 
-    if (HEADING.test(line.text)) {
+    if (HEADING.test(line.text) || SECTION_MARKER.test(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

@@ -36,6 +36,8 @@ Does not govern:
 - Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
 - 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.
 
 ## Paragraphs and lists
 

package/standards/plan.md

@@ -57,6 +57,7 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 
 - Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the four that follow are labels over lists rather than sections of prose.
 - A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
+- Both spellings break a depth run, so `aitk markdown audit` reads either as the seam it is and reports a plan for a section that genuinely runs long rather than for its whole body. The markdown standard states the rule.
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
 - Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
 - Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.