@erclx/canon 4.59.0 → 4.60.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.59.0",
+  "version": "4.60.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -22,6 +22,7 @@ A track that closes with several separable findings writes only one task, and th
 - Carry a lean and the finding that would overturn it on every open question, or admit that a measurement is missing
 - Confine writes to the track folder, with the close-time task file, the experiment fixture, and the intake routing below as the only exceptions
 - Route a closing-track finding the required task does not cover through `claude-intake`, rather than leaving it to be asked about. The route runs in the same session, so it is a write outside the folder rather than a handoff to a later one.
+- Place the closing task's row through `claude-tasks` Step 4 rather than writing `priority.md` or `backlog.md` directly
 - Link every claim about a source outside the project, and list an unread source as a lead rather than citing it
 - Put a fixture a headless run is pointed at outside the repository
 - Write the next-session file self-contained, since the folder is unbacked and dies with the machine

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

@@ -92,7 +92,7 @@ The standard sets the open question format and requires it inside a topic file a
 1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped.
 2. Write `07-next-session.md` self-contained, so it survives a compaction that loses the conversation.
 3. Update the file map in `README.md`.
-4. Write one task file in `.canon/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter. Aside from an experiment fixture, this and the routing in Step 5 are the only ways close mode reaches outside the folder.
+4. Write one task file in `.canon/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter. Place the row through `claude-tasks` Step 4, which checks the roster for a live orchestrator before writing `priority.md` or `backlog.md` directly. Aside from an experiment fixture, this and the routing in Step 5 are the only ways close mode reaches outside the folder.
 5. When the task written in Step 4 does not cover every finding the track surfaced, route what it leaves out through `claude-intake`. Skip this step when it does.
 6. Report uncited external claims. Closing already reads every file in the folder, so list any statement about a source outside the project that carries neither a link nor a lead entry. Report and do not block, because judging whether a sentence makes an external claim is the call a checker gets wrong.
 

package/claude/skills/claude-memory-review/SKILL.md

@@ -65,7 +65,7 @@ For each in-scope entry (see Scope), pick one action:
 - **Promote to `CLAUDE.md`**: the rule is cross-domain behavior or a design principle applied across the whole project.
 - **Promote to a skill body**: the rule fires only when editing a specific path-scoped domain. Name the target skill.
 - **Promote to a standards file**: the rule is an authoring reference that belongs in the project's own standards folder as `<domain>.md`.
-- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `.claude/context/index.md`. Append it to `.canon/tmp/memory-routing/<slug>.md` in the format `claude-memory-capture` writes, and tell the user to run `/claude-docs` from a branch. Do not edit the context entry here.
+- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `.claude/context/index.md`. Append it to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root, in the format `claude-memory-capture` writes, and tell the user to run `/claude-docs` from a branch. Do not edit the context entry here.
 - **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. Never edit the synced `.claude/rules/` copies of toolkit rules, because `canon gov sync` overwrites them. Stop at handoff.
   - In the toolkit repo, point the user at `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, which own the source-of-truth rules under `governance/rules/`.
   - In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`.
@@ -150,7 +150,7 @@ Free-form text after the verb is a reason. Capture it in the receipt but do not
 Action by action type:
 
 - **Promote**: use `Edit` to insert the rewritten rule into the target surface, then archive the memory file.
-- **Promote to a context entry**: append the fact to `.canon/tmp/memory-routing/<slug>.md`, then archive the memory file. `claude-docs` folds it in on its next run from a branch, which is what keeps one skill writing context entries.
+- **Promote to a context entry**: append the fact to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root, then archive the memory file. `claude-docs` folds it in on its next run from a branch, which is what keeps one skill writing context entries.
 - **Hand off**: do not edit governance. Archive the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
 - **Retire**: archive the memory file.
 

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

@@ -11,12 +11,15 @@ Without this skill, a task file gets a filename and frontmatter invented on the
 
 Archiving fails in two ways that both lose work. Moving the file, editing the ordering file, and regenerating the index as three separate acts drifts from the one command the merge hook calls, so the attended and unattended paths stop agreeing. And an all-`[x]` task gets archived while its pull request is still open, because marking outcomes happens on the branch as the first step of shipping. The board is gitignored, so nothing restores a task archived early.
 
+Placing a row without checking for another writer collides the same way. Two sessions filing work at once can claim one phase label twice or land two rows beside each other unread, since neither reads the board before writing it.
+
 ## Must
 
 - Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
 - Read the tasks standard before writing, rather than working the filename and frontmatter from memory
 - Require an origin at creation, because that is the only moment the invariant is enforceable
 - Propose the phase label from what is already on the board and pad it to two digits
+- Check the roster for a live orchestrator before writing a row, and hand off rather than write when one is found
 - Confirm the work reached the default branch before archiving
 - Run the archive command and route on the reason it refuses, since each reason has one resolution
 - Report an origin that carries no task, as a list rather than a prompt
@@ -28,6 +31,7 @@ Archiving fails in two ways that both lose work. Moving the file, editing the or
 - Write a pull request line at creation, when any number is a guess at someone else's work
 - Archive around a refusal
 - Split the legacy single-file archive into per-task files nobody wrote
+- Fall through to a direct write when no orchestrator is found and this session's own name starts with `worker-` or `planner-`, since those role bodies ban the write with no exception
 
 ## Guards
 

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

@@ -47,9 +47,15 @@ Write it immediately. Claude Code's tool permission dialog is the confirmation g
 
 A task file with no row is a dropped task, so name the surface it lands on in the same pass that creates it. A task that would plausibly be planned within the next few waves takes a row under `## Needs a plan` in `.canon/tasks/priority.md`, positioned by where it sits against the rows already there, with the reason for that position in its `Waiting on` cell. Anything else takes a line in `.canon/tasks/backlog.md`, which is unordered and where in the file it goes means nothing.
 
-The test and both file shapes are in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. From a linked worktree the file-editing tools refuse the main root, so a row lands through the same `Bash` route the file itself took.
+The test and both file shapes are in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`.
 
-Say which surface it went to and why in the report. The call is a judgment restated on every sweep rather than a property of the task, and a placement with no stated reason is one the next sweep re-derives from nothing.
+Check the roster for a live orchestrator before writing either file. Read `canon sessions list --self --json` for this session's own `sessionId` and `name`, then read `canon sessions list --json` and match a row whose `repository` matches this session's own, whose `sessionId` differs from it, and whose `name` starts with `orchestrator-`. That is the convention every hand-launched controller on this machine currently uses, and it excludes every `worker-` and `planner-` session cleanly. Treat a refusal from either call the same as a roster read that failed.
+
+- **Found.** Do not write `priority.md` or `backlog.md`. Report the surface the row would take and the reason worked out above, then hand off by messaging that session with the same information so it places the row itself rather than two sessions writing the board at once.
+- **Not found, and this session's own name (already read above) starts with `worker-` or `planner-`.** Do not write either file. Those two role bodies ban a board write with no exception, and an orchestrator absent from the roster is not consent to break it. Report the row and the surface it would take, so the operator or a later orchestrator places it.
+- **Not found otherwise, or the roster read fails.** Write the row directly, as today. A failed read is indistinguishable from a solo project holding no orchestrator, and stopping would strand the row on the one path this section otherwise keeps unconditional. From a linked worktree the file-editing tools refuse the main root, so the row lands through the same `Bash` route the file itself took.
+
+Say which branch fired and why in the report. The call is a judgment restated on every sweep rather than a property of the task, and a placement with no stated reason is one the next sweep re-derives from nothing.
 
 ### Step 5: report unlinked origins
 

package/docs/agents/tasks.md

@@ -214,7 +214,7 @@ Seven checks run. Plan and Collisions reach one half each of the `## Run now` te
 | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
 | Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
 | Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line        |
-| Mapping    | A row or backlog line naming no task file, and a task file neither surface names                                        |
+| Mapping    | A row or backlog line naming no task file                                                                               |
 | Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
 | Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
 | Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
@@ -224,9 +224,9 @@ Shape runs before any other check reads a row, since a row failing it carries no
 
 The Plan check reads the row and the task file both, because the two are written by different hands and only the task's own `Plan:` line reaches the archive. A row carrying a plan whose task states none is `plan-uncited`, and a pair naming two different plans is `plan-mismatched`. Both sides resolve against the board and against the project root before they compare, so a row writing `../plans/x.md` and a task writing `.canon/plans/x.md` name one file rather than two.
 
-Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A task file either surface names is accounted for, a file neither names is `row-missing`, and a file both name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. One check across both is what lets a task move between them without the move reading as a dropped file.
+Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A row or a backlog line naming no task file is `task-unresolved`, and a file both surfaces name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. A task file neither surface names is `unplaced` rather than a finding, since that is the normal state between a session filing it and a live orchestrator placing it on the board. One check across both is what lets a task move between them without the move reading as a dropped file.
 
-A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name is still reported as reaching neither surface. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.
+A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name still lands in the `unplaced` array below rather than the findings. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.
 
 Ordering reads a `## Needs a plan` row's `Waiting on` cell for the position it claims, and reports two failures off one walk. A row stating an ordinal is checked against where it actually sits, which is `row-misordered`. A row claiming no position in either form it may take is `row-unranked`, since its cell argues the task matters and ranks it against nothing, which leaves the order recording when each row was filed.
 
@@ -282,6 +282,21 @@ That claim collides with every row a later session writes under the folder, and
 
 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.
 
+A task file neither surface names lands in a fourth array, on the same reasoning:
+
+```json
+{
+  "unplaced": [
+    {
+      "subject": "v50.6-a-standard-no-skill-reads", // canon-allow-reference: shows the subject field's real vXX.Y-slug shape, not a citation of a real task
+      "message": "is a task file with no row on the board and no line on the backlog."
+    }
+  ]
+}
+```
+
+Under the roster-checked hand-off `claude-tasks` and `claude-groundwork` state, filing a task and placing its row are two acts a different session each may take, so a task caught between the two is ordinary rather than a finding and this array moves no exit code. It still reports, since it is the only local detector for a row a hand-edit dropped, a handoff message that never arrived, or an orchestrator that ended before placing it.
+
 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/canon",
   "type": "module",
-  "version": "4.59.0",
+  "version": "4.60.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/labels.ts

@@ -155,9 +155,9 @@ export function register(program: Command): void {
         "It also grades the title alone against standards/pr.md's ## Title",
         'section: the `<type>(<scope>): <subject>` structure, lowercase casing',
         'for the type, the scope, and the first subject word, and a 72-',
-        'character length cap. A review carries no title of its own, so this',
-        'check is skipped there rather than graded against the forced empty',
-        'string.',
+        'character length cap. A scan given no title, whether from a review',
+        'or from a bare --body or --body-file invocation, skips this check',
+        'rather than grading an empty string.',
         '',
         'Exit codes:',
         '  0  none of the five found',
@@ -287,12 +287,10 @@ async function runScan(opts: ScanOptions): Promise<number> {
 
   const result = scanPhaseLabels(resolved)
   const spelling = await scanTitleSpelling(resolved.title, process.cwd())
-  // A review carries no title of its own, so `resolved.title` is forced
-  // empty and grading it would fail as `structure` for the wrong reason.
+  // A scan given no title, whatever produced that absence, has nothing to
+  // grade and would otherwise fail as `structure` for the wrong reason.
   const titleFormat =
-    resolved.source === 'pull-request'
-      ? checkTitleFormat(resolved.title)
-      : undefined
+    resolved.title !== '' ? checkTitleFormat(resolved.title) : undefined
 
   logStep(resolved.source === 'review' ? 'Review comment' : 'Pull request')
   logInfo(
@@ -373,7 +371,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
         : 'Title format issue found',
   )
   if (titleFormat === undefined) {
-    logInfo('a review comment carries no title, so there is no format to grade')
+    logInfo('the scan carries no title, so there is no format to grade')
   } else if (titleFormat.conforms) {
     logInfo(
       'the title matches <type>(<scope>): <subject> and its casing and length rules',

package/src/commands/tasks.ts

@@ -22,6 +22,7 @@ import {
 import {
   type Finding,
   type FolderClaim,
+  type Unplaced,
   type Untested,
   type ValidateOutcome,
   validateBoard,
@@ -887,6 +888,17 @@ function reportValidation(
     } else {
       for (const claim of outcome.claims) logWarn(describeClaim(claim))
     }
+
+    // Unplaced is the normal state between a session filing a task and an
+    // orchestrator placing its row, so it moves no exit code. It still reports,
+    // since it is the only local detector for a row a hand-edit dropped or a
+    // handoff that never arrived.
+    logStep('Unplaced')
+    if (outcome.unplaced.length === 0) {
+      logInfo('every task file sits on the board or the backlog')
+    } else {
+      for (const task of outcome.unplaced) logWarn(describeUnplaced(task))
+    }
     outro()
   }
 
@@ -901,6 +913,7 @@ function reportValidation(
         findings: outcome.findings,
         untested: outcome.untested,
         claims: outcome.claims,
+        unplaced: outcome.unplaced,
       })}\n`,
     )
   }
@@ -921,6 +934,10 @@ function describeClaim(claim: FolderClaim): string {
   return `${claim.group}: ${claim.subject} ${claim.message}`
 }
 
+function describeUnplaced(task: Unplaced): string {
+  return `${task.subject} ${task.message}`
+}
+
 async function runArchive(
   task: string | undefined,
   opts: ArchiveCommandOptions,

package/src/tasks/validate.ts

@@ -38,7 +38,6 @@ export const FINDING_KINDS = [
   'plan-uncited',
   'plan-mismatched',
   'task-unresolved',
-  'row-missing',
   'row-duplicated',
   'row-misshapen',
   'row-untabled',
@@ -83,6 +82,18 @@ export interface FolderClaim {
   readonly message: string
 }
 
+/**
+ * A task file neither surface names. That is the normal state between a
+ * session filing it and a live orchestrator placing it, so it reports beside
+ * the findings and moves no exit code. It is still the only local detector for
+ * a row lost to a hand-edit, a handoff message that never arrived, or an
+ * orchestrator that ended before placing it.
+ */
+export interface Unplaced {
+  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
@@ -116,6 +127,7 @@ export interface ValidateReport {
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
   readonly claims: readonly FolderClaim[]
+  readonly unplaced: readonly Unplaced[]
 }
 
 export interface ValidateRefused {
@@ -556,15 +568,15 @@ function resolves(target: string, dir: string, root: string): boolean {
 }
 
 /**
- * Accounts every task file against both surfaces the board spans. A task sits
- * on `priority.md` when it would plausibly be planned soon and on `backlog.md`
- * otherwise, so a file reached by neither is the dropped one this reports and a
- * file reached by both claims two contradictory things about itself.
+ * Reports a task cited from two places on the board, which claims two
+ * contradictory things about itself: a task belongs to exactly one group,
+ * board or backlog. A task file neither surface names is no longer reported
+ * here, since that is the normal state between a session filing it and a live
+ * orchestrator placing it.
  */
 function checkMapping(
   rows: readonly BoardRow[],
   backlog: readonly BacklogRow[],
-  stems: readonly string[],
   dir: string,
 ): Finding[] {
   const findings: Finding[] = []
@@ -638,18 +650,6 @@ function checkMapping(
     }
   }
 
-  for (const stem of stems) {
-    if (!seen.has(stem) && !listed.has(stem)) {
-      findings.push({
-        kind: 'row-missing',
-        group: undefined,
-        subject: stem,
-        message:
-          'is a task file with no row on the board and no line on the backlog.',
-      })
-    }
-  }
-
   return findings
 }
 
@@ -878,6 +878,32 @@ function checkFolderClaims(
   return claims
 }
 
+/**
+ * Reports a task file neither the board nor the backlog names. Under the
+ * roster-checked hand-off, filing a task and placing its row are two acts a
+ * different session each may perform, so this state is ordinary rather than
+ * an error, and it moves no exit code. It still surfaces here rather than
+ * nowhere, since it is the only local detector for a row a hand-edit dropped,
+ * a handoff message that never arrived, or an orchestrator that ended before
+ * placing it.
+ */
+function checkUnplaced(
+  rows: readonly BoardRow[],
+  backlog: readonly BacklogRow[],
+  stems: readonly string[],
+): Unplaced[] {
+  const seen = new Set(rows.flatMap((row) => (row.stem ? [row.stem] : [])))
+  const listed = new Set(backlog.flatMap((row) => (row.stem ? [row.stem] : [])))
+
+  return stems
+    .filter((stem) => !seen.has(stem) && !listed.has(stem))
+    .map((stem) => ({
+      subject: stem,
+      message:
+        'is a task file with no row on the board and no line on the backlog.',
+    }))
+}
+
 /**
  * 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
@@ -1136,7 +1162,7 @@ export async function validateBoard(
 
   const findings = [
     ...shapeFindings,
-    ...checkMapping(rows, backlog, stems, dir),
+    ...checkMapping(rows, backlog, dir),
     ...checkPlans(rows, dir, root),
     ...(await checkPlanAgreement(rows, dir, root)),
     ...checkCollisions(rows),
@@ -1152,5 +1178,6 @@ export async function validateBoard(
     findings,
     untested: parked.untested,
     claims: checkFolderClaims(rows, root),
+    unplaced: checkUnplaced(rows, backlog, stems),
   }
 }

package/tooling/nextjs/manifest.toml

@@ -17,3 +17,6 @@ packages = [
 [scripts.override]
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && next dev --port $((3000 + WORKTREE_PORT_OFFSET))"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+
+[gitignore]
+"# Next" = [".next/"]

package/tooling/nextjs/reference.md

@@ -33,6 +33,12 @@ Next has no config-file port hook, unlike `astro.config.mjs`'s `server.port` or
 
 `create-next-app`'s own default `tsconfig.json` needs no changes beyond project-specific path aliases, so a golden copy here would ship nothing the scaffold does not already write.
 
+## Gitignore (extend)
+
+`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+
+- `"# Next" = [".next/"]`
+
 ## Development docs (extend)
 
 Append to the `## Scripts` table: