@erclx/canon 4.23.0 → 4.24.0

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

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

package/claude/skills/claude-orchestrate/REQUIREMENT.md

@@ -94,6 +94,7 @@ The session also records nothing of what it learns. Both other callers of memory
 - Merge. Recommend merge or changes and leave the gate to the human.
 - Spawn a worker with the Agent tool, since an in-process subagent shares this session's context and cannot be steered or reached independently. A dispatched `claude --bg` process is not this: it is a separate session with its own worktree and its own PR, gated by the collision check and the file-set disjointness test.
 - Hand a worker anything but a plan, because scope lives there
+- Name a count of the defect's extent or the mechanism behind it while filing a row, since this seat measures a defect from where it stands and the planner is the reader who commits to that scope. A blocker re-test, a collision check, and a file set decide whether a row can start rather than how big it is, and they stay.
 - Run a second orchestrator against the same board
 - Promote a task to fill the queue when nothing qualifies. A thin queue is a real answer.
 - Promote a parked row on how long it has waited, since age is not a measurement of the blocker

package/claude/skills/claude-orchestrate/SKILL.md

@@ -149,6 +149,14 @@ The tracked-file boundary collides with `CLAUDE.md`, which says to handle a smal
 
 Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when no such task exists or is expected. Run `claude-review` when the boundary is crossed anyway, since a branch-diff pass is not independent and is the only check a self-authored change can get.
 
+Filing a row states the defect and the surface it was seen on, and stops there. The extent and the cause belong to whoever plans it, so a row names neither a count of how far the defect reaches nor the mechanism behind it. Say in a plain sentence in the task file that the count was not taken, where the row's shape invites one, rather than in a marker of any prescribed form. The board's own cell has no room for it, since `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` caps a `Waiting on` cell at two clauses.
+
+A finding placed into another task's `## Findings` is filing under a second name and takes the same rule. An unverified cause costs more than an unverified count, since a count fails loudly at the first re-measurement while a mechanism nobody opened the module to check sends real work in the wrong direction.
+
+What the measurement decides is the test, rather than whether one was taken. A measurement that decides whether a row can start stays in this seat, which covers the blocker re-test in `${CLAUDE_SKILL_DIR}/references/orchestrator-parked.md`, the collision check before a dispatch, and the file set refill step 6 lists against every track in flight. One that decides how big the row is goes to the planner.
+
+Both kinds read the same tree, and only a sizing count commits a plan to a scope this seat cannot see the whole of. A row filed under `## Needs a plan` carries no `Touches` column either, so filing it unmeasured owes no file set and the disjointness machinery is untouched. A position claim in that group's cell is in scope as well: name the row it outranks or the class it belongs to, each a judgment about order, and never reach for a count of the defect's extent to justify the rank, which is the untested number this boundary keeps off the row wearing a ranking argument.
+
 ## Refilling the ready queue
 
 Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge, whenever the ready list thins, and whenever a wave is in flight with fewer unclaimed plans than there are workers building. `${CLAUDE_SKILL_DIR}/references/orchestrator-sweep.md` wraps this procedure for a batch of merges and adds the plan re-verification that a merge invalidates.

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

@@ -29,6 +29,8 @@ The blocker cell states what the row waits on, and each kind is tested different
 - 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.
 
+Every measurement this pass takes is a blocker re-test on a row already filed, and it decides whether that row can start rather than how big it is. Sizing a row is the filing boundary `claude-orchestrate` states under `## Boundaries`, which leaves the extent and the cause to whoever plans the row.
+
 Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` with the date it was taken. `### Writing the board` in `claude-orchestrate` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report.
 
 ## Two ways a re-test goes wrong

package/docs/agents/commands.md

@@ -56,7 +56,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
 | `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |
 | `canon claude skills audit`   | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                        |
-| `canon standards audit`       | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                 |
+| `canon standards audit`       | Report the corpus against the success-criterion gate `standards/standard.md` states, failing only on a standard new to the branch (`--json`, `--arrivals-only`)       |
 | `canon claude skills drift`   | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                             |
 | `canon claude skills reach`   | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                            |
 | `canon claude skills rank`    | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                       |

package/docs/workflow/operating-model.md

@@ -65,6 +65,14 @@ goes to the task that owns the surface, or folds into the next task touching it,
 because a session that writes a change cannot review it independently afterwards
 and no later session recovers that vantage.
 
+Filing that row stops at the defect and the surface it was seen on. How far the
+defect reaches and what causes it belong to whoever plans the row, so it arrives
+carrying neither a count nor an asserted mechanism, and the seat that found it
+says as much in a plain sentence rather than supplying either. What separates the
+two is what a measurement decides: the blocker re-test, the collision check, and
+the file set compared against every track in flight all decide whether a row can
+start, and only a count of the defect's extent decides how big it is.
+
 ## The loop
 
 One feature travels this path end to end.

package/package.json

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

package/src/commands/standards.ts

@@ -62,7 +62,7 @@ export function register(program: Command): void {
   standards
     .command('audit')
     .description(
-      'Report the corpus against the `## Success criterion` gate in standards/standard.md',
+      'Report the corpus against the success-criterion gate standards/standard.md states',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -78,7 +78,7 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the audit completed with every arriving standard carrying the section',
         '  1  refused, with the reason on stderr',
-        '  2  a standard new to this branch carries no ## Success criterion section',
+        '  2  a standard new to this branch carries no success-criterion section',
         '',
         'A standard already in the corpus without the section is a known gap',
         'standards/standard.md names, not a violation, so only an arrival fails.',
@@ -204,8 +204,8 @@ function reportArrivalGate(
   intro('canon standards audit')
   logError(
     missing.length === 1
-      ? '1 standard new to this branch carries no ## Success criterion section'
-      : `${missing.length} standards new to this branch carry no ## Success criterion section`,
+      ? '1 standard new to this branch carries no success-criterion section'
+      : `${missing.length} standards new to this branch carry no success-criterion section`,
   )
   pipeOutput(missing.join('\n'))
   outro()
@@ -217,7 +217,7 @@ function reportCorpus(
   logStep('Corpus')
   logInfo(`${plural(audit.standards.length, 'standard')} at standards/`)
   logInfo(
-    `${plural(audit.withCriterion.length, 'standard')} carrying ## Success criterion`,
+    `${plural(audit.withCriterion.length, 'standard')} carrying a success criterion`,
   )
 
   logStep('Known gaps')
@@ -241,7 +241,7 @@ function reportCorpus(
   }
 
   logError(
-    `${plural(audit.arrivalsWithoutCriterion.length, 'standard')} arrived carrying no ## Success criterion section`,
+    `${plural(audit.arrivalsWithoutCriterion.length, 'standard')} arrived carrying no success-criterion section`,
   )
   pipeOutput(audit.arrivalsWithoutCriterion.join('\n'))
 }

package/src/gate/measures.ts

@@ -435,7 +435,7 @@ export const standardCriteria: Measure = async (ctx) => {
     emissions: [output(run.all)],
     failure:
       run.exitCode === 2
-        ? 'A standard new to this branch carries no ## Success criterion section. Run bun src/cli.ts standards audit.'
+        ? 'A standard new to this branch carries no success-criterion section. Run bun src/cli.ts standards audit.'
         : 'canon standards audit could not read which standards arrived on this branch. Run bun src/cli.ts standards audit --json to see why.',
   }
 }

package/src/git-base.ts

@@ -0,0 +1,19 @@
+/**
+ * Preferred first, matching `src/tasks/trunk.ts`. A local `main` trailing the
+ * remote pulls other people's merged commits into the range, so a check
+ * reading it decides against files the branch never touched.
+ */
+export const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * The refs to try, in order, for the far side of a branch range: a named ref
+ * alone, or the trunk list when none was named.
+ */
+export function baseCandidates(ref: string | undefined): readonly string[] {
+  return ref !== undefined ? [ref] : TRUNK_REFS
+}
+
+/** Whether a `merge-base` result names a commit rather than an empty read. */
+export function isMergeBase(value: string | undefined): value is string {
+  return value !== undefined && value !== ''
+}

package/src/git-files.ts

@@ -1,13 +1,7 @@
 import { $ } from 'bun'
+import { baseCandidates, isMergeBase } from '@/git-base'
 import { gitEnv } from '@/git-env'
 
-/**
- * Preferred first, matching `src/gov/test-order.ts` and `src/tasks/trunk.ts`. A
- * local `main` trailing the remote pulls other people's merged commits into the
- * range, so a check reading it decides against files the branch never touched.
- */
-const TRUNK_REFS = ['origin/main', 'main'] as const
-
 /** Runs git under `root` with the resolution variables a hook exports stripped. */
 async function git(
   root: string,
@@ -37,14 +31,9 @@ export async function resolveBaseRef(
   root: string,
   ref?: string,
 ): Promise<string | undefined> {
-  if (ref !== undefined) {
-    const merged = await git(root, ['merge-base', 'HEAD', ref])
-    return merged === undefined || merged === '' ? undefined : merged
-  }
-
-  for (const trunk of TRUNK_REFS) {
-    const merged = await git(root, ['merge-base', 'HEAD', trunk])
-    if (merged !== undefined && merged !== '') return merged
+  for (const candidate of baseCandidates(ref)) {
+    const merged = await git(root, ['merge-base', 'HEAD', candidate])
+    if (isMergeBase(merged)) return merged
   }
 
   return undefined

package/src/gov/test-order.ts

@@ -1,13 +1,7 @@
 import { execaSync } from 'execa'
+import { baseCandidates, isMergeBase } from '@/git-base'
 import { gitEnv } from '@/git-env'
 
-/**
- * Preferred first, matching `src/tasks/trunk.ts`. A clone with no remote still
- * answers off its local trunk, and a local `main` trailing the remote widens
- * the range rather than narrowing it, which over-reports instead of hiding.
- */
-const TRUNK_REFS = ['origin/main', 'main'] as const
-
 /**
  * The extensions this check can pair. A test sits beside its subject under one
  * name throughout this corpus, so the weakest assumption available is also the
@@ -349,22 +343,17 @@ function resolveBase(
   ref: string | undefined,
   head: string,
 ): string | { kind: 'unreadable'; reason: TestOrderRefusal; message: string } {
-  if (ref !== undefined) {
-    const merged = git(root, ['merge-base', head, ref])
-    if (merged === undefined || merged === '') {
-      return {
-        kind: 'unreadable',
-        reason: 'bad-base',
-        message: `Ref ${ref} shares no history with HEAD in ${root}. Pass a ref this branch was taken from.`,
-      }
-    }
-    return merged
+  for (const candidate of baseCandidates(ref)) {
+    const merged = git(root, ['merge-base', head, candidate])
+    if (isMergeBase(merged)) return merged
   }
 
-  for (const trunk of TRUNK_REFS) {
-    if (revParse(root, trunk) === undefined) continue
-    const merged = git(root, ['merge-base', head, trunk])
-    if (merged !== undefined && merged !== '') return merged
+  if (ref !== undefined) {
+    return {
+      kind: 'unreadable',
+      reason: 'bad-base',
+      message: `Ref ${ref} shares no history with HEAD in ${root}. Pass a ref this branch was taken from.`,
+    }
   }
 
   const rootCommits = git(root, ['rev-list', '--max-parents=0', head])