@erclx/canon 5.40.0 → 5.41.0

package/claude/skills/role-worker/SKILL.md

@@ -61,6 +61,14 @@ Announce the pull request as the ship chain's pull request step returns, carryin
 - Say the reach was unread rather than clear when the installed binary carries no such subcommand, and leave the undeclared list to the pull request
 - Carry a row this build turned up with its title, origin, and surface. Send it alone only when the session ends before a pull request opens.
 
+### A fan-in member
+
+A member of a fan-in set opens no pull request, so its done message stands in for the announcement. `auto-ship` sends it after the push.
+
+- Carry the branch, the head commit, and the integrator the plan names in place of a pull request number
+- Carry no reach, since the integrator's announcement carries it once for the whole set
+- An integrator is an ordinary worker and owes the announcement above
+
 ### Re-review and blocks
 
 Ask for the re-review as `review-address` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and the message starts the re-review.
@@ -117,5 +125,6 @@ Never concede on the name alone or proceed as if the sets never collided. A work
 ## Lifetime
 
 - The role runs from the worktree entry to the merge of the branch it built, and nothing carries to a second row, which is a new build under a new plan
+- A fan-in member's role ends at its push, since the integrator merges the branch and fixes on its own branch whatever the merge surfaces
 - A talk session outlives the merge and ends when the operator says the conversation is over
 - Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache, so a session changing its own skills may hold the copy from before the last update.

package/claude/skills/teach-workspace/REQUIREMENT.md

@@ -62,4 +62,4 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - Creating a wiki folder a project never chose
 - What the verbs do internally, which is the CLI domain's own contract rather than this skill's, and the records backup that carries the folder off one disk
 - What a lesson renders as and how a quiz behaves once rendered, which the lesson-craft reference shapes and a rendering layer executes
-- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so opening a workspace is the learner's call rather than a description match.
+- Deciding when to fire. The description states `Do NOT auto-trigger`, so opening a workspace is the learner's call rather than a description match.

package/claude/skills/teach-workspace/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: teach-workspace
-description: Opens and runs a learning workspace on one subject, holding a mission, resources, numbered lessons, reference pages, a glossary, and learning records that survive across sessions, proposes where a durable page from one belongs once it outgrows the workspace, and lands the confirmed pages from a branch. Use when asked to "teach me X", "open a learning workspace", "I want to learn X", "quiz me on this", "continue the lesson", "resume my workspace on X", "promote this reference page", or "fold the promoted pages in". Do NOT use to write project documentation, which belongs to the surface owning that document, and do NOT use to answer one question, which is an ordinary reply.
-disable-model-invocation: true
+description: Opens and runs a learning workspace on one subject, holding a mission, resources, numbered lessons, reference pages, a glossary, and learning records that survive across sessions, proposes where a durable page from one belongs once it outgrows the workspace, and lands the confirmed pages from a branch. Use when asked to "teach me X", "open a learning workspace", "I want to learn X", "quiz me on this", "continue the lesson", "resume my workspace on X", "promote this reference page", or "fold the promoted pages in". Do NOT use to write project documentation, which belongs to the surface owning that document, and do NOT use to answer one question, which is an ordinary reply. Do NOT auto-trigger.
 argument-hint: <subject to learn, the topic of a workspace to resume or promote, or fold>
 metadata:
   family: answer

package/docs/workflow/parallel-features.md

@@ -41,6 +41,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 Merge order matters only when two branches touch the same file. Expect to rebase over `CLAUDE.md`, `tooling/**`, `canon/context/context-model.md`, `docs/agents/`, and any folder's `index.md`. Resolve an `index.md` conflict with `canon indexes regen` over the rebased tree.
 
+- **Fan-in.** Batches of one change sharing edge files ship as one pull request, opened by an integrator that merges each member branch. See `claude/skills/plan-feature/references/batches.md`.
 - **Merge order.** Merge the smallest hotspot footprint first, and a branch touching `CLAUDE.md` or a context entry last.
 - **Rebase.** The branch merging second runs `/review-address`, which trial-merges against `origin/main` and rebases. Push, then merge.
 - **Clean up.** Run `/git-worktree cleanup` to remove merged worktrees. To start fresh, `ExitWorktree(action: "keep")`, then `/session-worktree <new-name>`.

package/docs/workflow/skill-map.md

@@ -67,7 +67,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:docs-sync`     | A change left `README.md` or `docs/` stale    |
 | `canon:git-stage`     | Staged changes span several concerns          |
 | `canon:git-commit`    | Staged changes are one concern                |
-| `canon:git-branch`    | A branch name needs generating or renaming    |
+| `canon:git-branch`    | A branch needs creating, naming, or renaming  |
 | `canon:git-pr`        | A pull request needs a title and body         |
 
 ## After the pull request opens

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.40.0",
+  "version": "5.41.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/git.ts

@@ -6,6 +6,10 @@ export const GIT_CASES: readonly SkillCase[] = [
     prompt: 'Come up with a conventional name for this branch.',
     expect: 'git-branch',
   },
+  {
+    prompt: 'I am on main and about to start a feature, create its branch.',
+    expect: 'git-branch',
+  },
   {
     prompt: "Turn what's staged into one commit message.",
     expect: 'git-commit',

package/src/commands/pr.ts

@@ -57,6 +57,7 @@ import {
   pruneFramesWithLegacy,
   pushFrame,
   readFrame,
+  referenceSlug,
   type TreeEntry,
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -184,6 +185,7 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
 interface FramesOptions extends ReadOptions {
   readonly add?: string
   readonly box?: string
+  readonly reference?: string
   readonly head?: string
   readonly pass?: string
   readonly theme?: string
@@ -196,6 +198,7 @@ type FramesCommandRefusal =
   | 'bad-mode'
   | 'no-number'
   | 'bad-box'
+  | 'bad-reference'
   | 'bad-head'
   | 'bad-pass'
   | 'bad-theme'
@@ -212,13 +215,15 @@ const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
   'no-number':
     '--add and --drop write for one pull request, so name its number.',
   'bad-box':
-    '--add takes --box <n>, a positive whole number naming the checklist box.',
+    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference <page>/<frame>, never both.',
+  'bad-reference':
+    '--reference takes <page>/<frame>, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
   'bad-head':
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
     '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
   'bad-theme':
-    '--theme takes dark or light and goes with --add, so a second shot of one box never replaces the first.',
+    '--theme takes dark or light and goes with --add --box, so a second shot of one box never replaces the first.',
   'bad-days': '--prune takes a positive whole number of days.',
   'unreadable-frame':
     'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
@@ -1011,6 +1016,10 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--add <file>', 'Push this PNG as a frame')
     .option('--box <n>', 'The checklist box the frame shows, with --add')
+    .option(
+      '--reference <address>',
+      'The design reference the capture shows, as <page>/<frame>, with --add in place of --box',
+    )
     .option(
       '--head <sha>',
       "The head the frame was driven at, with --add, defaulting to the pull request's",
@@ -1035,7 +1044,8 @@ export function register(program: Command): void {
         `An add writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
-        'with --theme, and `link` names that',
+        'with --theme, or ref-<page>--<frame>.png for a design reference capture',
+        'passed as --reference <page>/<frame> in place of --box, and `link` names that',
         `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
         'requests and resolves until its own pull request is dropped. The pass',
         'segment keeps a second pass at one head and box from replacing an image',
@@ -1056,10 +1066,11 @@ export function register(program: Command): void {
         '  ok                an add pushed, or a drop or prune finished',
         '  bad-mode          not exactly one of --add, --drop, --prune',
         '  no-number         --add or --drop named no pull request',
-        '  bad-box           --add without a positive --box',
+        '  bad-box           --add with both --box and --reference, or neither',
+        '  bad-reference     --reference is not <page>/<frame> in the safe name form',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
         '  bad-pass          --add without a compact UTC --pass stamp',
-        '  bad-theme         --theme is not dark or light, or no --add',
+        '  bad-theme         --theme is not dark or light, or no --add, or rides a --reference',
         '  bad-days          --prune without a positive number of days',
         '  unreadable-frame  the --add file is missing, empty, or not a PNG',
         '  read-only         GitHub refused the write, as on a fork token',
@@ -3084,10 +3095,18 @@ function framesArgumentRefusal(
   if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
   if (
     opts.add !== undefined &&
-    (opts.box === undefined || !POSITIVE_WHOLE.test(opts.box))
+    (opts.box === undefined) === (opts.reference === undefined)
   ) {
     return 'bad-box'
   }
+  if (opts.add !== undefined && opts.box !== undefined) {
+    if (!POSITIVE_WHOLE.test(opts.box)) return 'bad-box'
+  }
+  if (opts.reference !== undefined) {
+    if (opts.add === undefined || referenceSlug(opts.reference) === undefined) {
+      return 'bad-reference'
+    }
+  }
   if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
   if (
     opts.add !== undefined &&
@@ -3097,7 +3116,9 @@ function framesArgumentRefusal(
   }
   if (
     opts.theme !== undefined &&
-    (opts.add === undefined || !isFrameTheme(opts.theme))
+    (opts.add === undefined ||
+      opts.reference !== undefined ||
+      !isFrameTheme(opts.theme))
   ) {
     return 'bad-theme'
   }
@@ -3199,7 +3220,8 @@ async function runFrames(
   if (head === undefined || head === '') return refuseFrames('no-object-head')
   if (!isFrameHead(head)) return refuseFrames('bad-head')
 
-  const box = Number(opts.box)
+  const box = opts.box === undefined ? undefined : Number(opts.box)
+  const reference = opts.reference
   const pass = opts.pass ?? ''
   const theme = opts.theme as FrameTheme | undefined
   const result = await pushFrame(api, {
@@ -3207,6 +3229,7 @@ async function runFrames(
     head,
     pass,
     box,
+    reference,
     theme,
     bytes: bytes ?? new Uint8Array(),
   })
@@ -3215,7 +3238,7 @@ async function runFrames(
   return finish(
     {
       number: pull,
-      box,
+      ...(box === undefined ? { reference } : { box }),
       ...(theme === undefined ? {} : { theme }),
       head,
       pass,

package/src/commands/records.ts

@@ -44,6 +44,7 @@ import {
   plural,
 } from '@/cli/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { fanInFindings } from '@/tasks/fan-in'
 import { readLivePlans, stackFindings } from '@/tasks/stack'
 
 /** Returned when a record carries a finding, which is the gating result. */
@@ -742,7 +743,7 @@ async function runValidate(
 }
 
 /**
- * Appends the one plans finding that reads across files. It sits in the command
+ * Appends the plans findings that read across files. They sit in the command
  * layer because `src/records/` sits below `src/tasks/`.
  */
 async function validateWithStacks(
@@ -752,9 +753,16 @@ async function validateWithStacks(
   const outcome = await validateRecords(root, kind)
   if (!outcome.ok || kind !== 'plans') return outcome
 
-  const stacked = stackFindings(await readLivePlans(root))
+  const live = await readLivePlans(root)
 
-  return { ...outcome, findings: [...outcome.findings, ...stacked] }
+  return {
+    ...outcome,
+    findings: [
+      ...outcome.findings,
+      ...stackFindings(live),
+      ...fanInFindings(live),
+    ],
+  }
 }
 
 function report(

package/src/context/shape-gated.ts

@@ -19,6 +19,7 @@ export const SHAPE_GATED_FOLDERS: readonly string[] = [
   'canon/context/features/',
   'canon/context/surfaces/',
   'canon/context/workflow/',
+  'tooling/base/seeds/',
 ]
 
 /** Whether a repository-relative entry path sits under a gated prefix. */

package/src/markdown/scope.ts

@@ -128,6 +128,10 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/youtube-transcripts/SKILL.md',
   '.claude/skills/internal-',
   'docs/',
+  'tooling/',
+  'wiki/',
+  'README.md',
+  'CONTRIBUTING.md',
 ]
 
 /**
@@ -136,8 +140,8 @@ export const GATED_PATHS: readonly string[] = [
  * entries, the docs pages, and the skill bodies and references through a stage
  * of its own before this measure existed, and waiting on `GATED_PATHS` would
  * reopen that hole. The seeds, the stack references, the wiki, and the root
- * guides were never held to it, and seven runs in the stack references would
- * fail the push on the day this lands, so those wait for their batch.
+ * guides were never held to it, so they joined `GATED_PATHS` only once their
+ * rewrite brought them to zero.
  */
 const ALWAYS_GATED: readonly DensityKind[] = ['bullet-run']
 

package/src/pr/frames.ts

@@ -19,6 +19,9 @@ const PASS_PATTERN = /^\d{8}T\d{6}Z$/
 /** How many times an add rebuilds on a tip another writer moved. */
 const ADD_ATTEMPTS = 3
 
+/** One half of a reference address. It opens on a letter or digit and holds no separator, so `..` and `/` cannot survive it. */
+const REFERENCE_PART = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
 const FOLDER_PATTERN = /^pr-(\d+)$/
 
 const DAY_MS = 86_400_000
@@ -77,7 +80,8 @@ export interface FrameInput {
   readonly number: number
   readonly head: string
   readonly pass: string
-  readonly box: number
+  readonly box?: number
+  readonly reference?: string
   readonly theme?: FrameTheme
   readonly bytes: Uint8Array
 }
@@ -158,6 +162,39 @@ export function frameLink(repo: string, path: string): string {
   return `https://github.com/${repo}/blob/${FRAMES_BRANCH}/${path}?raw=true`
 }
 
+/**
+ * The file-name slug of a `<page>/<frame>` address, or undefined when the
+ * address would not round-trip. Each half must open on a letter or digit and
+ * hold only letters, digits, dots, underscores, and dashes, and neither may
+ * carry `--`, so the joined slug reads back as the same two names and a path
+ * never gains a directory or escapes the pass folder.
+ */
+export function referenceSlug(address: string): string | undefined {
+  const parts = address.split('/')
+  if (parts.length !== 2) return undefined
+  const [page, frame] = parts as [string, string]
+  const valid = [page, frame].every(
+    (part) => REFERENCE_PART.test(part) && !part.includes('--'),
+  )
+  return valid ? `${page}--${frame}` : undefined
+}
+
+/**
+ * Where a design reference capture lands, beside the evidence frames of one
+ * pass. The slug repeats for one reference, so a second capture in a pass
+ * overwrites only itself. Undefined when the address has no valid slug.
+ */
+export function referencePath(
+  number: number,
+  head: string,
+  pass: string,
+  address: string,
+): string | undefined {
+  const slug = referenceSlug(address)
+  if (slug === undefined) return undefined
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/ref-${slug}.png`
+}
+
 /** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
 export async function readFrame(path: string): Promise<Uint8Array | undefined> {
   const bytes = await readFile(path).catch(() => undefined)
@@ -179,17 +216,24 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path = framePath(
-    input.number,
-    input.head,
-    input.pass,
-    input.box,
-    input.theme,
-  )
+  const path =
+    input.reference === undefined
+      ? framePath(
+          input.number,
+          input.head,
+          input.pass,
+          input.box ?? 0,
+          input.theme,
+        )
+      : referencePath(input.number, input.head, input.pass, input.reference)
+  if (path === undefined) return { kind: 'refused', reason: 'push-failed' }
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
-  const message = `chore(frames): add box ${input.box} of #${input.number}`
+  const message =
+    input.reference === undefined
+      ? `chore(frames): add box ${input.box} of #${input.number}`
+      : `chore(frames): add reference ${input.reference} of #${input.number}`
 
   for (let attempt = 0; attempt < ADD_ATTEMPTS; attempt += 1) {
     const tip = await api.readTip()

package/src/records/validate.ts

@@ -48,6 +48,7 @@ export const FINDING_KINDS = [
   'batch-unsplit',
   'source-unquoted',
   'stack-foldable',
+  'fan-in-unmatched',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]

package/src/tasks/answers.ts

@@ -1,8 +1,15 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, isAbsolute, relative, resolve } from 'node:path'
+import { branchRefs } from '@/git/worktree'
+import { fanInBranch, fanInFindings, readFanInMembers } from '@/tasks/fan-in'
 import { isUnder } from '@/tasks/paths'
-import { JUDGED_APART_REMEDY, readLivePlans, stackPairs } from '@/tasks/stack'
+import {
+  JUDGED_APART_REMEDY,
+  readLivePlans,
+  type StackPlan,
+  stackPairs,
+} from '@/tasks/stack'
 import { recordDir, recordDirs } from '@/roots/record'
 import {
   hasStagedBatches,
@@ -49,6 +56,28 @@ export interface PlanAnswers {
 
 export type AnswersOutcome = PlanAnswers | AnswersRefused
 
+/**
+ * Whether `refs/remotes/origin/<branch>` exists, or `null` when the read
+ * itself failed. Injected so the gate is testable without a repository.
+ */
+export type RemoteBranchReader = (
+  root: string,
+  branch: string,
+) => Promise<boolean | null>
+
+/**
+ * Reads the remote-tracking ref as the last fetch left it, so a member pushed
+ * since then reads as absent and holds its integrator, which fails safe. The
+ * local head is not read, since it exists mid-build and a pushed branch is the
+ * only signal a member writes when it is done.
+ */
+export const originBranchPushed: RemoteBranchReader = async (root, branch) => {
+  const report = await branchRefs(branch, root)
+  if (!report.readable) return null
+
+  return report.refs.includes(`refs/remotes/origin/${branch}`)
+}
+
 /**
  * A reference that named a live plan, carrying the absolute path a reader opens
  * and the root-relative spelling a record reports.
@@ -217,6 +246,7 @@ export function resolvePlanReference(
 export async function planAnswers(
   root: string,
   reference: string,
+  readRemoteBranch: RemoteBranchReader = originBranchPushed,
 ): Promise<AnswersOutcome> {
   const resolved = resolvePlanReference(root, reference)
   if (!resolved.ok) return resolved
@@ -233,7 +263,8 @@ export async function planAnswers(
   }
 
   const stem = basename(resolved.path, '.md')
-  const pairs = stackPairs(await readLivePlans(root))
+  const live = await readLivePlans(root)
+  const pairs = stackPairs(live)
 
   for (const { child, parent, shared } of pairs) {
     if (child !== stem) continue
@@ -244,6 +275,8 @@ export async function planAnswers(
     })
   }
 
+  open.push(...(await fanInEntries(root, stem, text, live, readRemoteBranch)))
+
   return {
     ok: true,
     plan: resolved.plan,
@@ -252,6 +285,50 @@ export async function planAnswers(
   }
 }
 
+/**
+ * A plan whose fan-in set disagrees holds on `Fan-in set`, on either side,
+ * since an integrator listing an archived member would otherwise read that
+ * member's leftover branch as done. An integrator whose set agrees holds on
+ * `Fan-in pending` until every member branch is on origin.
+ */
+async function fanInEntries(
+  root: string,
+  stem: string,
+  text: string,
+  live: readonly StackPlan[],
+  readRemoteBranch: RemoteBranchReader,
+): Promise<OpenQuestion[]> {
+  const entries: OpenQuestion[] = fanInFindings(live)
+    .filter(({ record }) => record === `${stem}.md`)
+    .map(({ message }) => ({ label: 'Fan-in set', why: message }))
+
+  const branches = readFanInMembers(text).map(fanInBranch)
+  if (branches.length === 0 || entries.length > 0) return entries
+
+  const pushed = await Promise.all(
+    branches.map((branch) => readRemoteBranch(root, branch)),
+  )
+
+  if (pushed.includes(null)) {
+    return [
+      {
+        label: 'Fan-in pending',
+        why: 'git could not read the member branches on origin, so the set is unread rather than done.',
+      },
+    ]
+  }
+
+  const absent = branches.filter((_, index) => pushed[index] !== true)
+  if (absent.length === 0) return []
+
+  return [
+    {
+      label: 'Fan-in pending',
+      why: `waits on ${absent.map((branch) => `\`${branch}\``).join(', ')} reaching origin. Fetch, then read again.`,
+    },
+  ]
+}
+
 function refuse(
   reason: AnswerRefusal,
   message: string,