@erclx/canon 5.26.0 → 5.28.0

package/claude/skills/role-orchestrator/scripts/poll.ts

@@ -40,19 +40,33 @@ export interface Row {
   passAt: number
   prior: string
   replyAt: number
+  /** What the pull request writes, null when its diff could not be read. */
+  paths: null | string[]
   resp: number
+  stale: Staleness
+  staleFiles: string[]
   ui: string
   unmatchedCount: number
   unmatchedHeading: string
 }
 
+/**
+ * Whether the base moved under a path the pull request writes since the commit
+ * it branched from. `unknown` is a written set this run could not read, which
+ * must never pass for `fresh`.
+ */
+export type Staleness = 'fresh' | 'stale' | 'unknown'
+
 /** One baseline line, kept as the strings it was written with. */
 export interface Baseline {
   head: string
   merges: string
   number: string
+  /** Open pull requests this one conflicts with, comma-separated, or `none`. */
+  overlaps: string
   prior: string
   resp: string
+  stale: string
   state: string
   ui: string
   unmatched: string
@@ -211,7 +225,7 @@ export const uiState = (payload: Payload, head: string): string => {
   return `${heading}-${covered ? 'head' : 'behind'}-${commit.slice(0, 7)}`
 }
 
-/** Takes the first eight fields and ignores the rest, so a short or padded line still reads. */
+/** Takes the first ten fields and ignores the rest, so a short or padded line still reads. */
 export const parseBaseline = (line: string): Baseline => {
   const fields = line.split(' ')
 
@@ -219,14 +233,21 @@ export const parseBaseline = (line: string): Baseline => {
     head: fields[1] ?? '',
     merges: fields[4] ?? '',
     number: fields[0] ?? '',
+    overlaps: fields[9] ?? '',
     prior: fields[2] ?? '',
     resp: fields[3] ?? '',
+    stale: fields[8] ?? '',
     state: fields[5] ?? '',
     ui: fields[7] ?? '',
     unmatched: fields[6] ?? '',
   }
 }
 
+/**
+ * New fields append at the end, so every positional read of an older line still
+ * lands. A field an older line never carried stays empty and is not written
+ * back as a trailing space.
+ */
 export const formatBaseline = (entry: Baseline): string =>
   [
     entry.number,
@@ -237,10 +258,30 @@ export const formatBaseline = (entry: Baseline): string =>
     entry.state,
     entry.unmatched,
     entry.ui,
-  ].join(' ')
+    entry.stale,
+    entry.overlaps,
+  ]
+    .join(' ')
+    .trimEnd()
 
 const short = (head: string): string => head.slice(0, 7)
 
+const listFiles = (files: string[]): string =>
+  files.length > 3
+    ? `${files.slice(0, 3).join(', ')}, +${files.length - 3} more`
+    : files.join(', ')
+
+/**
+ * A conflict already sends the branch to its owner for a rebase, so a pull
+ * request reading both reports the conflict alone and earns one handback.
+ */
+const staleLine = (row: Row, base: string): string[] =>
+  row.stale === 'stale' && row.merges !== 'conflict'
+    ? [
+        `STALE     #${row.number} ${base} changed ${row.staleFiles.length} file(s) it writes since its base: ${listFiles(row.staleFiles)}`,
+      ]
+    : []
+
 export interface Classification {
   baseline: Baseline
   isChanged: boolean
@@ -266,8 +307,10 @@ const classifyFirstSighting = (
     head: row.head,
     merges: row.merges,
     number: row.number,
+    overlaps: 'none',
     prior: row.prior,
     resp: String(row.resp),
+    stale: row.stale,
     state: row.heading,
     ui: row.ui,
     unmatched: String(row.unmatchedCount),
@@ -280,7 +323,11 @@ const classifyFirstSighting = (
     line = `OPENED    #${row.number} at ${at}`
   }
 
-  return { baseline, isChanged: true, lines: [line] }
+  return {
+    baseline,
+    isChanged: true,
+    lines: [line, ...staleLine(row, context.base)],
+  }
 }
 
 const classifyUi = (row: Row, old: Baseline): string[] => {
@@ -312,11 +359,23 @@ export const classify = (
   let state = row.heading
 
   // A conflict arrives from the base moving, not from the branch, so it is
-  // reported on the transition rather than only when the head changes.
-  if (row.merges === 'conflict' && old.merges !== 'conflict') {
+  // reported on the transition rather than only when the head changes. A push
+  // that leaves it conflicting reports it again, for the same reason STALE does.
+  if (
+    row.merges === 'conflict' &&
+    (old.merges !== 'conflict' || row.head !== old.head)
+  ) {
     lines.push(`CONFLICT  #${row.number} no longer merges into ${context.base}`)
   }
 
+  // Staleness arrives the same way, and reports on its transition so a branch
+  // left behind across several runs earns one handback rather than one a run.
+  // A push that leaves it behind reports it again, since the draft lift reads a
+  // MOVED with no STALE beside it as the rebase having landed.
+  if (old.stale !== 'stale' || row.head !== old.head) {
+    lines.push(...staleLine(row, context.base))
+  }
+
   // A rising count is what is new here. It fires on a tracked pull request
   // only: a first sighting takes whatever already sits on the thread as its
   // baseline rather than flagging history retroactively.
@@ -386,8 +445,10 @@ export const classify = (
     head: row.head,
     merges: row.merges,
     number: row.number,
+    overlaps: old.overlaps,
     prior: row.prior,
     resp: String(row.resp),
+    stale: row.stale,
     state,
     ui: row.ui === '' ? old.ui : row.ui,
     unmatched: String(row.unmatchedCount),
@@ -396,6 +457,29 @@ export const classify = (
   return { baseline, isChanged: lines.length > 0, lines }
 }
 
+/**
+ * One pull request's base movement as a single line. STALE and CONFLICT print
+ * in the poll only on a transition or a push, so a reader deciding a draft
+ * lift reads this instead. A reading that could not be taken is unknown, never
+ * clear.
+ */
+export const standingLine = (
+  entry: Pick<Baseline, 'head' | 'merges' | 'number' | 'stale'>,
+): string => {
+  const at = short(entry.head)
+  if (entry.merges === 'conflict') {
+    return `CONFLICT  #${entry.number} standing at ${at}`
+  }
+  if (entry.stale === 'stale') {
+    return `STALE     #${entry.number} standing at ${at}`
+  }
+  if (entry.merges === 'clean' && entry.stale === 'fresh') {
+    return `CLEAR     #${entry.number} at ${at}`
+  }
+
+  return `UNKNOWN   #${entry.number} at ${at}, whether it merges or is current could not be read`
+}
+
 /**
  * A pull request this run could not read keeps the line it had, so the GONE
  * sweep does not read the gap as a merge. Its heading is blanked to a value no
@@ -532,6 +616,152 @@ const readMerges = (number: string, head: string, ref: string): string => {
     : 'conflict'
 }
 
+interface Written {
+  forkPoint: string
+  paths: string[]
+}
+
+const nonEmptyLines = (output: string): string[] =>
+  output.split('\n').filter((line) => line !== '')
+
+/**
+ * The paths a pull request writes, read from its own diff against the commit it
+ * branched from. `--no-renames` lists both sides of a rename, since a change on
+ * the base to either one is a change under the branch. A head or base that does
+ * not resolve, which a fork or a deleted head leaves, reads as null.
+ */
+const readWritten = (head: string, ref: string): null | Written => {
+  const forkPoint = run('git', ['merge-base', ref, head])
+  if (!forkPoint.isOk) return null
+  const point = forkPoint.stdout.trim()
+  const diff = run('git', ['diff', '--name-only', '--no-renames', point, head])
+  if (!diff.isOk) return null
+
+  return { forkPoint: point, paths: nonEmptyLines(diff.stdout) }
+}
+
+/**
+ * Re-testing after every merge to the base is a merge queue's cost without its
+ * batching, so only a change to a path the branch writes makes it stale. The
+ * net diff rather than the log is read, so a change the base made and then
+ * reverted moves nothing.
+ */
+const readStale = (
+  written: null | Written,
+  ref: string,
+): { files: string[]; stale: Staleness } => {
+  if (written === null) return { files: [], stale: 'unknown' }
+  if (written.paths.length === 0) return { files: [], stale: 'fresh' }
+
+  const moved = run('git', [
+    '--literal-pathspecs',
+    'diff',
+    '--name-only',
+    '--no-renames',
+    written.forkPoint,
+    ref,
+    '--',
+    ...written.paths,
+  ])
+  if (!moved.isOk) return { files: [], stale: 'unknown' }
+
+  const files = nonEmptyLines(moved.stdout)
+
+  return { files, stale: files.length > 0 ? 'stale' : 'fresh' }
+}
+
+export interface Overlap {
+  files: string[]
+  pair: readonly [string, string]
+}
+
+/**
+ * Pairwise merge-tree grows with the square of open pull requests, so only a
+ * pair sharing a written path is tested. Each pair comes lower number first,
+ * which fixes the order its line and its baseline entry are read in.
+ */
+export const sharedPairs = (rows: Row[]): [Row, Row][] => {
+  const readable = rows
+    .filter((row) => row.paths !== null && row.paths.length > 0)
+    .toSorted((a, b) => Number(a.number) - Number(b.number))
+  const pairs: [Row, Row][] = []
+  for (const [index, first] of readable.entries()) {
+    const written = new Set(first.paths)
+    for (const second of readable.slice(index + 1)) {
+      if ((second.paths ?? []).some((path) => written.has(path))) {
+        pairs.push([first, second])
+      }
+    }
+  }
+
+  return pairs
+}
+
+const partnersOf = (entry: Baseline | undefined): string[] =>
+  entry === undefined || entry.overlaps === '' || entry.overlaps === 'none'
+    ? []
+    : entry.overlaps.split(',')
+
+/**
+ * A partner this run could not read keeps its place, so a pull request that
+ * drops out of one run and returns does not report the same pair twice.
+ */
+export const overlapPartners = (
+  number: string,
+  overlaps: Overlap[],
+  old: Baseline | undefined,
+  carried: Set<string>,
+): string => {
+  const partners = new Set(
+    overlaps.flatMap(({ pair: [first, second] }) =>
+      first === number ? [second] : second === number ? [first] : [],
+    ),
+  )
+  for (const partner of partnersOf(old)) {
+    if (carried.has(partner)) partners.add(partner)
+  }
+  const sorted = [...partners].toSorted((a, b) => Number(a) - Number(b))
+
+  return sorted.length === 0 ? 'none' : sorted.join(',')
+}
+
+/** A pair reports once, read off the lower-numbered side's baseline entry. */
+export const overlapLines = (
+  overlaps: Overlap[],
+  known: Map<string, Baseline>,
+): string[] =>
+  overlaps
+    .filter(
+      ({ pair: [first, second] }) =>
+        !partnersOf(known.get(first)).includes(second),
+    )
+    .map(
+      ({ files, pair: [first, second] }) =>
+        `OVERLAP   #${first} #${second} conflict on ${listFiles(files)}`,
+    )
+
+/**
+ * Two pull request heads merged against each other, which is the merge the
+ * second to land will have to make. merge-tree exits 1 on a conflict and
+ * prints the tree then one conflicted path a line. Any other failure prints no
+ * tree, and reads as null beside a clean merge, since neither names a file.
+ */
+const readOverlap = (first: string, second: string): null | string[] => {
+  const merged = run('git', [
+    'merge-tree',
+    '--write-tree',
+    '--name-only',
+    '--no-messages',
+    first,
+    second,
+  ])
+  if (merged.isOk) return null
+  const lines = nonEmptyLines(merged.stdout)
+  if (lines.length < 2) return null
+
+  return [...new Set(lines.slice(1))]
+}
+
 const buildRow = (
   number: string,
   payload: Payload,
@@ -545,17 +775,23 @@ const buildRow = (
     run('canon', ['pr', 'review-state', number, '--json']).stdout,
   )
   const scope = scopeFromVerb(record, now) ?? scopeFallback(payload, now)
+  const merges = readMerges(number, head, ref)
+  const written = merges === 'unknown' ? null : readWritten(head, ref)
+  const stale = readStale(written, ref)
 
   return {
     age: scope.age,
     head,
     heading: scope.state,
-    merges: readMerges(number, head, ref),
+    merges,
     number,
     passAt: scope.readAt,
+    paths: written?.paths ?? null,
     prior: scope.commit,
     replyAt: replies.newestAt,
     resp: replies.count,
+    stale: stale.stale,
+    staleFiles: stale.files,
     ui: uiState(payload, head),
     unmatchedCount: unmatched.count,
     unmatchedHeading: unmatched.heading,
@@ -573,7 +809,37 @@ const countSince =
     return log.isOk ? log.stdout.split('\n').filter((l) => l !== '').length : 0
   }
 
-const main = (): number => {
+/**
+ * `--check <number>` reads the base and the head at call time and writes
+ * nothing. The baseline is as old as the last full run, and a sibling merging
+ * after it would leave a stored reading claiming clear.
+ */
+const check = (number: string): number => {
+  const ref = baseRef()
+  run('git', ['fetch', '-q', 'origin', baseBranch(ref)])
+  const head = readHead(number)
+  if (head === '') {
+    console.error(
+      `poll: #${number} returned no head, so nothing is known about it`,
+    )
+
+    return 1
+  }
+  const merges = readMerges(number, head, ref)
+  const written = merges === 'unknown' ? null : readWritten(head, ref)
+  console.log(
+    standingLine({
+      head,
+      merges,
+      number,
+      stale: readStale(written, ref).stale,
+    }),
+  )
+
+  return 0
+}
+
+const main = (args: string[]): number => {
   const root = mainRoot()
   if (root === null) {
     console.error('poll: not a git repository, so nothing is classified')
@@ -583,6 +849,7 @@ const main = (): number => {
 
   // The baseline is per-machine mutable state, so it stays in gitignored
   // scratch even though the script is tracked.
+  if (args[0] === '--check') return check(args[1] ?? '')
   const stateDir = join(root, '.canon', 'tmp', 'pr', 'poll')
   mkdirSync(stateDir, { recursive: true })
   const statePath = join(stateDir, 'baseline.txt')
@@ -655,6 +922,22 @@ const main = (): number => {
     snapshots.push({ row: buildRow(number, payload, head, ref) })
   }
 
+  const rows = snapshots.flatMap((snapshot) =>
+    'row' in snapshot ? [snapshot.row] : [],
+  )
+  const carried = new Set(
+    snapshots.flatMap((snapshot) =>
+      'baseline' in snapshot ? [snapshot.baseline.number] : [],
+    ),
+  )
+  const overlaps = sharedPairs(rows).flatMap(([first, second]) => {
+    const files = readOverlap(first.head, second.head)
+
+    return files === null
+      ? []
+      : [{ files, pair: [first.number, second.number] as const }]
+  })
+
   let isChanged = false
   const final: string[] = []
   const seen = new Set<string>()
@@ -667,13 +950,24 @@ const main = (): number => {
 
     const { row } = snapshot
     seen.add(row.number)
-    const result = classify(row, known.get(row.number), {
+    const old = known.get(row.number)
+    const result = classify(row, old, {
       base,
       countSince: countSince(row.number),
     })
     for (const line of result.lines) console.log(line)
     if (result.isChanged) isChanged = true
-    final.push(formatBaseline(result.baseline))
+    final.push(
+      formatBaseline({
+        ...result.baseline,
+        overlaps: overlapPartners(row.number, overlaps, old, carried),
+      }),
+    )
+  }
+
+  for (const line of overlapLines(overlaps, known)) {
+    console.log(line)
+    isChanged = true
   }
 
   for (const entry of previous) {
@@ -688,4 +982,4 @@ const main = (): number => {
   return 0
 }
 
-if (import.meta.main) process.exitCode = main()
+if (import.meta.main) process.exitCode = main(process.argv.slice(2))

package/claude/skills/role-planner/REQUIREMENT.md

@@ -89,4 +89,4 @@ four carried at least one, caught only because the planner ran
 - The mechanical addressee resolution, which `session-relay` owns for every session with or without a role
 - The branch, the build, and the pull request, which `role-worker` and `auto-ship` own
 - Deciding which rows run and in what order, which is the controlling session's call and stated in `role-orchestrator`
-- The dispatch itself, its collision check, and its disjointness gate, which `orchestrator-dispatch.md` holds
+- The dispatch itself, its collision check, and its conflict check, which `orchestrator-dispatch.md` holds

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

@@ -1,6 +1,8 @@
 ---
 name: role-planner
 description: Asserts the planner role for a session writing one plan, groundwork track, or intake pass under one row, holding what it reads before deciding, what may be written and where, how to read what is already in flight, and what it hands back. Use when asked to "be the planner", "you are a planner session", at the start of a dispatched or hand-launched planning, groundwork, or intake run, or when a planning session needs to know what it may not write. Do NOT use to write the record itself, which is `plan-feature`, `plan-groundwork`, or `plan-intake`, to make the cross-feature merge call, or to implement.
+metadata:
+  family: parallel
 ---
 
 # Role planner
@@ -40,7 +42,7 @@ Each item below is something a record needed and a launch string did not carry.
 - The task file, and its `## Findings` before deciding anything. A row can carry its own disproof under a title that still states the original claim, which is how one trial nearly planned against a premise the file had already recorded as dead.
 - The source files themselves, opened rather than summarized. Never a count quoted from the task file, which was wrong or stale in ten places across four plans.
 - `CLAUDE.md` and `canon/ARCHITECTURE.md`, for the decision and the alternative it was taken against rather than for the decision alone.
-- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch disjointness gate already reads.
+- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch conflict check already reads. Read it for the shared-path lines and the holds of the constraint block, never as a gate a plan must clear.
 
 Two reads belong to the `plan-feature` path alone, since neither a groundwork
 track nor an intake pass is sequenced behind another row or validated as a plan:
@@ -58,7 +60,7 @@ it.
 - Run `canon sessions list --json`, take the `branch` field of every session whose `repository` matches this one and whose branch is neither null nor the trunk branch, union that with every `headRefName` from `gh pr list --json number,headRefName`, dedupe by branch name, then diff each with `git diff --name-only main...<branch>` for its file set. That resolves locally whether or not a pull request exists, since every track in this repository shares one git directory across its worktrees.
 - A bare branch or worktree with neither a live session nor a pull request behind it is still not evidence, since this repository squash-merges and leaves both behind. The roster read is already filtered to live sessions, so what changed is the second source composed with it rather than a raw count. It still misses a live session that reached its worktree through the direct-path fallback rather than `EnterWorktree`, since that session's registered branch never moves off the trunk.
 - Run the read once per row rather than once per batch. A session working several rows ages its picture of the tree while it goes, and this read is what dates it.
-- Name each in-flight set as a constraint, say which act it forbids, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing. The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in whatever shape its own standard states.
+- Name each in-flight set as a constraint, being a hold that says which act it forbids or a shared path that says which branch rebases, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing. The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in whatever shape its own standard states.
 
 ## The board is read-only
 

package/claude/skills/role-reviewer/REQUIREMENT.md

@@ -57,7 +57,7 @@ a tree the pull request never changed.
 - Restate a boundary `role-orchestrator`, `role-worker`, or `role-planner` states about itself
 - Report progress through the channel, which rebuilds on the sender's side the poll the announcement exists to retire
 - Post outside `review-pr` and `review-ui`, since every reader of the review headings breaks at once when one pass invents its own
-- Be a skill nothing invokes but its author typing the name. `orchestrator-launch.md` names it on the reviewer launch the way it names `role-planner` on a planning one, so a stretch where only a typed invocation reaches it is the signal that the role never took.
+- Be a skill nothing invokes but its author typing the name. `orchestrator-reviewer-launch.md` names it on the reviewer launch the way `orchestrator-launch.md` names `role-planner` on a planning one, so a stretch where only a typed invocation reaches it is the signal that the role never took.
 
 ## Guards
 

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

@@ -1,6 +1,8 @@
 ---
 name: role-reviewer
 description: Asserts the reviewer role for a session dispatched to review one pull request another session built, holding what it may write, what it reads and never reads, the one message it owes on posting, and the acts it refuses. Use when asked to "be the reviewer", "you are a reviewer session", at the start of a dispatched or hand-launched review of one pull request, or when a reviewing session needs to know what it may not write or who it answers to. Do NOT use to run the pass itself, which is `review-pr` for the code and `review-ui` for the running app, to review local changes, which is `review-branch`, or to make the cross-branch call across a wave.
+metadata:
+  family: parallel
 ---
 
 # Role reviewer
@@ -23,7 +25,7 @@ from here.
 
 ## Where the session stands
 
-- Write the review comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`, and nothing else. A UI reviewer writes the comment `review-ui` posts, its body file, and the browser's snapshots and frames, all under `.canon/tmp/pr/review-ui/`. A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch.
+- Write the review comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`, and nothing else. A UI reviewer writes the comment `review-ui` posts, its body file, and the browser's snapshots and frames, all under `.canon/tmp/pr/review-ui/`, and ticks the boxes it passed on the evidence comment through `canon pr tick`. A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch.
 - Never enter a worktree and never check the branch out. The pass reads a change, and a checkout is the first step toward editing it.
 - Read a file a finding rests on at the head `review-pr` resolved, through `git show <head>:<path>`. The main worktree holds the trunk, so a finding read off its copy is about a tree the pull request never changed, and it reads as confidently as one that is right.
 - Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/tmp/` at the main worktree root, and send the body file as a heredoc, the main-root route `session-worktree` states. Report a plan or task that fails to resolve there as unreadable, naming the path, rather than reviewing as though the branch had none.

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

@@ -1,6 +1,8 @@
 ---
 name: role-worker
 description: Asserts the worker role for a building session, holding the boundary set, the lifetime, and the two channel obligations a session owes whoever dispatched it. Use when asked to "be the worker", "you are a worker session", at the start of a dispatched or hand-launched build, or when a building session needs to know what it may not write. Do NOT use to plan the next feature, to run the independent review pass, or to merge.
+metadata:
+  family: parallel
 ---
 
 # Role worker
@@ -47,7 +49,7 @@ The controlling session cannot watch this one build, so the messages below are
 owed and nothing else.
 
 - Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
-- Carry the reach in that same message: the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`. The gate cleared this branch against a prediction it has since outgrown, so the controller holds a disjointness reading that stopped being true hours ago and nothing else tells it. 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 the reach in that same message: the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`. Report each as a rebase the controller should order, never as a breach, since sharing a path is not a hold. The gate cleared this branch against a prediction it has since outgrown, so the controller holds a reading of what this branch shares that stopped being true hours ago and nothing else tells it. 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 in that same message, with its title, its origin, and the surface it would take. Send it as its own message only when the session will end before a pull request opens, since the row has no other way to reach the controller.
 - Announce when an address-review pass finishes, 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 it is what tells the controller to re-review rather than leaving it to poll for an answer nothing marks as landed.
 - Send a block out as a message before it becomes an interactive prompt.
@@ -82,7 +84,8 @@ feature branch and a controller does not.
 - Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and the consequences of complying, rather than reporting reluctance.
 - Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the dispatch that sent it unattended is the defect and the halt is not.
 - Halting is cheap and guessing is not. Four measured halts each cost the dispatcher one reply, and the correction that mattered most reached the right place because a worker argued back rather than complying.
-- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it.
+- Write a file a constraint names as shared, and keep both sides on the rebase. A shared path forbids nothing, so the hunk comparison below does not apply to it.
+- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it. A hold is a dependency, a contract, a relocation, or a sweep.
 - Report that reading to the controller as the hunks or line ranges on each side, and take its reply as the call on whether the file is kept or given up, not a decision this session makes alone.
 - When the holding track carries no commits yet, there is nothing to diff. Compare against the file set its plan declares instead, and report that the hunk comparison could not be taken, rather than conceding on the name or proceeding as if the sets never collided.
 - A dispatcher once named three files a branch was writing. The worker diffed that branch, found its hunks at two lines against its own at three others, and reported the comparison, and the dispatcher reversed the instruction and returned every file.

package/claude/skills/search-craft/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: search-craft
 description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is the `claude-code-guide` agent, or to generate an image, which is not search.
+metadata:
+  family: build
 ---
 
 # Search craft

package/claude/skills/seed-sync/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: seed-sync
 description: Audits a project's installed Claude seed docs against the toolkit's current seed source and proposes per-section edits without overwriting customizations. Use when asked to "sync seeds", "update my seeds", "check seed drift", "did the toolkit seeds change", or when reconciling `CLAUDE.md` and `.claude/` preambles after an upstream toolkit update.
+metadata:
+  family: upkeep
 ---
 
 # Seed sync

package/claude/skills/session-compact/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-compact
 description: Captures a session's memory, then writes one handoff note to .canon/compact/ so the session after a compaction picks up where this one stopped. Use before running /compact, when asked to "write a handoff", "prepare for compaction", "save where we got to", or before moving a session to another machine, or when a PreCompact hook blocks and names this skill. Do NOT use for a session holding the orchestrator role, whose board handoff is `session-map`. Do NOT use to record a decision a groundwork track owns, which is `plan-groundwork`.
+metadata:
+  family: parallel
 ---
 
 # Session compact

package/claude/skills/session-map/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-map
 description: Writes the session map, the board-side handoff at `.canon/tasks/session-<slug>.md`, for an orchestrating session or on a request naming the session map or the task board, running the skill-drift step the write procedure opens with. Use when asked to "write the session map", "write the board handoff", or when a session holding `canon:role-orchestrator` hands off before a compaction. Do NOT use for a plain session about to compact, which is `session-compact` and writes a note outside the board. Do NOT use to route session facts to a context entry or the memory folder, which is `memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+metadata:
+  family: parallel
 ---
 
 # Session map

package/claude/skills/session-relay/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-relay
 description: Relays a message to another session, turning the sessionId the caller named into an address at the moment of sending and composing a copyable block where no send tool exists. Use when asked to "relay this", "message the controller", "send this over to the session that dispatched me", or "tell the other session", with or without a role, and when a session stuck on a question owes the session that dispatched it a message before it stops to ask. Do NOT use to decide what the message says, and do NOT use to assert what a session may write or is on the hook for, which is `role-worker` or `role-planner`.
+metadata:
+  family: parallel
 ---
 
 # Session relay

package/claude/skills/session-resume/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-resume
 description: Resumes a previous session by reading the handoff it left behind, tracked work, and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
+metadata:
+  family: parallel
 ---
 
 # Session resume

package/claude/skills/session-worktree/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-worktree
 description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/plan-feature`. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a memory entry was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
+metadata:
+  family: build
 ---
 
 # Session worktree
@@ -125,17 +127,7 @@ Read the worktree root and evaluate node and python independently against a lite
 
 Name the ecosystem in both installed lines rather than leaving `Dependencies are installed.` unqualified. Both checks can fire on one project, so an unqualified line reported the same sentence twice for a dual-root project with both folders present, and a reader could not tell which half each line answered.
 
-Take `<install>` from the lockfile beside the manifest, checked in this order, first match wins:
-
-| Lockfile                  | Install command |
-| ------------------------- | --------------- |
-| `bun.lock` or `bun.lockb` | `bun install`   |
-| `pnpm-lock.yaml`          | `pnpm install`  |
-| `yarn.lock`               | `yarn install`  |
-| `package-lock.json`       | `npm install`   |
-| none of the above         | `bun install`   |
-
-The order matters only when more than one lockfile sits beside the manifest, such as a project mid-migration between package managers. It is fixed rather than derived from anything about the project, so a reader hitting that rare case checks which manager the project actually uses rather than trusting the row the table picked first.
+Take `<install>` from the lockfile beside the manifest. Read `${CLAUDE_SKILL_DIR}/references/install-command.md` when the Node line reports dependencies not installed, for the order the lockfiles are checked in and the command each one names.
 
 Emit the closing line only on its own direct test, run ahead of the two checks above rather than reached by falling through them unmatched: `[ ! -f package.json ] && [ ! -f pyproject.toml ] && [ ! -f requirements.txt ]`: `No package manifest, so there is nothing to install.` A dual-root project matches both checks above, and a fallthrough test would route it here by accident.