@erclx/canon 4.125.0 → 4.127.0

package/README.md

@@ -96,7 +96,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
-- [Target projects](docs/target-projects.md): scaffold, add a domain later, sync upstream drift
+- [Target projects](docs/target/target-projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [Docs index](docs/index.md): every reference doc in this repo
 
@@ -152,7 +152,7 @@ canon init
 
 Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
 
-For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
+For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/target-projects.md).
 
 ### Internal narrative
 

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

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

package/claude/skills/git-pr/references/task-number.md

@@ -21,6 +21,8 @@ The verb resolves the board at the main worktree root in-process, adds `Pull req
 
 The correction reaches only a line that does not read as a list of `#NNN` entries. A line that does takes the new number appended rather than replaced, reported as `appended`, so a task shipped in slices keeps every pull request.
 
+The same write drops this branch from the task's `Pending branch:` line, which `canon tasks outcome` wrote when the branch ticked an outcome, so this step is what lets the merge-time archive close the task.
+
 Skip this silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`. Those are the three cases a guessed write would compound: no board, no task naming the plan, or more than one. One pull request names one task, and a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
 
 The number is what lets the merge close the task. Every merge on `main` is a squash carrying it in the subject, so the number survives where a branch name does not, and `post-merge` reads it back to call `canon tasks archive`. Writing it here rather than at worktree time is what makes it a pull request number rather than a branch the squash discards.

package/claude/skills/task-board/references/archive.md

@@ -42,6 +42,7 @@ Each reason has one resolution and none of them is to archive around it:
 - `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `context-fold` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. When the work is being abandoned, cut it by striking the body, `- ~~<outcome>~~ <why>`, whatever the checkbox holds, so the board records what was dropped rather than meeting this refusal a second time.
 - `ambiguous`: two tasks name one pull request, which is the misfile `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
 - `earlier-slice`: the number is listed on the task but is not the last, so a later slice is still to merge. Leave the task on the board. Its last slice's merge archives it.
+- `pending-branch`: a branch named in `detail` ticked an outcome before its own pull request number was recorded. Leave the task live, since that branch's merge archives it once `git-pr` records the number. When the operator decides a named branch was abandoned, archive by stem, which is the one case for it.
 - `no-match`: the stem or number names nothing on the board. Check the name against the listed stems.
 - `bad-input`: the command line was wrong rather than the board. Read the message, fix the arguments, and run it again. Nothing on the board needs repair, which is what separates this from the two above.
 

package/docs/agents/tasks-archive.md

@@ -22,7 +22,7 @@ canon tasks archive --pull-request 673 --json
 | `--json`             | Emit a machine-readable record on stdout                     |
 | `--root <path>`      | Board root, defaulting to the main worktree                  |
 
-Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `earlier-slice`, or `bad-input`. `earlier-slice` fires when `--pull-request` names a number that is not the last on the task's `Pull request:` line, since outcomes are ticked at ship time and only the last slice's merge closes the task.
+Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `earlier-slice`, `pending-branch`, or `bad-input`. `earlier-slice` fires when `--pull-request` names a number that is not the last on the task's `Pull request:` line, since outcomes are ticked at ship time and only the last slice's merge closes the task. `pending-branch` fires when `--pull-request` meets a `Pending branch:` line, since a branch that ticked an outcome before `git-pr` recorded its number means the last number listed is not yet the last slice. The `detail` array names each pending branch. Selecting by stem skips both checks.
 
 An outcome whose body is struck reads as cut rather than open or closed, whatever its checkbox holds: `- ~~<outcome>~~ <why>`. A task carrying only cut outcomes archives, since the gate refuses `no-outcomes` only when both the closed and the cut counts are zero. The success record carries `closed` and `cut` as counts, so a reader tells a shipped task from an abandoned one without opening the file.
 

package/docs/agents/tasks.md

@@ -60,6 +60,8 @@ canon tasks pull-request 673 --plan worktree-scratch-routing --json
 
 A plan is matched on the token both spellings share, so `worktree-scratch-routing`, `feature-worktree-scratch-routing`, and `.canon/plans/feature-worktree-scratch-routing.md` all select the same task. The `action` field reports `added`, `appended`, `corrected`, or `unchanged`, which makes a rerun against the same number safe.
 
+Run from a branch other than `main` or `master`, the verb also drops that branch from the task's `Pending branch:` line, along with every name its reflog says it was renamed from, and removes the line once it is empty. The renamed names matter because `git-ship` renames a nonconforming branch after `context-fold` wrote the marker. It does so on an `unchanged` run too, so a rerun repairs a marker left behind. The `pending` field lists the branches still on the line after the write.
+
 Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, or `ambiguous`. `git-pr` skips silently on those three, because each is a case where a guessed write would archive the wrong task once the branch merges.
 
 A malformed argument refuses as `bad-input` instead, which sits outside that set on purpose. `git-pr` derives the number by slicing whatever `gh pr create` printed, so a non-numeric value is reachable, and folding it into the swallowed set would lose the number with nothing reporting it.
@@ -82,6 +84,8 @@ canon tasks outcome --plan worktree-scratch-routing --close 2 --json
 
 An outcome already closed comes back under `alreadyClosed` rather than refusing, so a rerun against the same positions changes nothing. A position past the end of the list refuses as `out-of-range`, since a caller counting wrong should hear about it rather than mark a neighbor.
 
+A close that ticks at least one box from a branch other than `main` or `master` names that branch on a `Pending branch:` line, read from `git branch --show-current` in the working directory. The line holds the task against `canon tasks archive --pull-request` until `canon tasks pull-request` records that branch's own number. A detached HEAD, a trunk checkout, or a failed git read writes no line and refuses nothing. The `pending` field lists the branches on the line after the write.
+
 Positions skip fenced blocks. A checkbox inside a sample a task displays is not an outcome the task claims, and counting one would shift every position after it. `canon tasks archive` reads the list through the same walker, so the two verbs cannot disagree about which checkboxes are outcomes.
 
 Exit codes: `0` closed, `1` refused. The `reason` field adds `no-outcomes`, `out-of-range`, and `bad-input` to the three above.

package/docs/index.md

@@ -7,14 +7,6 @@ subtitle: One-line reference for each doc in this folder.
 
 One-line reference for each doc in this folder.
 
-## Agent surface
-
-- [Target migrations](target-migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
-- [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
-- [Target scenarios](target-scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
-- [Target sync](target-sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once
-
-## Sub-catalogs
-
 - [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.
+- [Target](target/index.md): Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
 - [Workflow](workflow/index.md): How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.

package/docs/target/index.md

@@ -0,0 +1,16 @@
+---
+title: Target
+subtitle: Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
+category: Agent surface
+---
+
+# Target
+
+Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
+
+## Agent surface
+
+- [Target migrations](target-migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
+- [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
+- [Target scenarios](target-scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
+- [Target sync](target-sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once

package/docs/{target-projects.md → target/target-projects.md}

@@ -8,7 +8,7 @@ category: Agent surface
 
 How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
 
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `canon/context/<domain>.md`.
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](../agents/index.md). For per-domain mechanics, see each `canon/context/<domain>.md`.
 
 ## Getting the skills
 
@@ -74,7 +74,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `canon:design-extract` to draft `canon/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
 3. Optionally invoke `canon:draft-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
-4. Start the feature loop. See [AI workflow](workflow/ai-workflow.md) for the per-feature sequence.
+4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
 
 A machine without a renderer still gets the diagrams and is told which check was skipped.
 
@@ -135,8 +135,8 @@ When the toolkit updates, a target pulls changes per domain. A project scaffolde
 
 ## Related
 
-- [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
+- [agents](../agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [target migrations](target-migrations.md), [target sync](target-sync.md), [target scenarios](target-scenarios.md): the one-time moves, the recurring sync, and worked setups
-- [AI workflow](workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../canon/context/tooling/index.md), [governance](../canon/context/governance/index.md), [claude plugin](../canon/context/claude-plugin/index.md), [indexes](../canon/context/indexes.md), [snippets](../canon/context/snippets.md), [standards](../canon/context/standards/index.md): per-domain mechanics
-- [sandbox](../canon/context/sandbox/index.md): scenario catalog for verifying domain flows
+- [AI workflow](../workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
+- [tooling](../../canon/context/tooling/index.md), [governance](../../canon/context/governance/index.md), [claude plugin](../../canon/context/claude-plugin/index.md), [indexes](../../canon/context/indexes.md), [snippets](../../canon/context/snippets.md), [standards](../../canon/context/standards/index.md): per-domain mechanics
+- [sandbox](../../canon/context/sandbox/index.md): scenario catalog for verifying domain flows

package/docs/{target-sync.md → target/target-sync.md}

@@ -84,7 +84,7 @@ Use a targeted entry point when only one surface moved upstream. Use the catch-a
 
 ## Verify a sync
 
-Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../canon/context/sandbox/index.md) for the scenario catalog and routing patterns.
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../../canon/context/sandbox/index.md) for the scenario catalog and routing patterns.
 
 ## Running sync from an agent session
 

package/docs/workflow/ai-workflow.md

@@ -44,7 +44,7 @@ Run `canon init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and
 
 ### Bootstrap a new project
 
-See [target projects](../target-projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
+See [target projects](../target/target-projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
 
 ### New feature
 

package/docs/workflow/skill-map.md

@@ -6,7 +6,7 @@ category: Workflow
 
 # Skill map
 
-Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
 
 This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
 

package/package.json

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

package/src/commands/labels.ts

@@ -25,7 +25,7 @@ interface ScanOptions {
 
 /** What a reader does about each way `checkTitleFormat` graded a title as broken. */
 const TITLE_FORMAT_MESSAGES: Record<TitleFormatIssue, string> = {
-  structure: 'does not match <type>(<scope>): <subject>',
+  structure: 'does not match <type>(<scope>)[!]: <subject>',
   'casing-type': 'the type is not lowercase',
   'casing-scope': 'the scope is not lowercase',
   'casing-subject': 'the first word of the subject is not lowercase',
@@ -153,7 +153,7 @@ export function register(program: Command): void {
         'forcing a new dependency.',
         '',
         "It also grades the title alone against standards/pr.md's ## Title",
-        'section: the `<type>(<scope>): <subject>` structure, lowercase casing',
+        '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 scan given no title, whether from a review',
         'or from a bare --body or --body-file invocation, skips this check',
@@ -374,7 +374,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
     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',
+      'the title matches <type>(<scope>)[!]: <subject> and its casing and length rules',
     )
   } else {
     logWarn(

package/src/commands/tasks.ts

@@ -64,6 +64,8 @@ const EXIT_FINDINGS = 2
 /** Matches `trunk.ts`'s bound on a git subprocess this verb also shells out to. */
 const GIT_TIMEOUT_MS = 10_000
 
+const TRUNK_BRANCHES: readonly string[] = ['main', 'master']
+
 interface ArchiveCommandOptions {
   readonly json?: boolean
   readonly pullRequest?: string
@@ -164,6 +166,10 @@ export function register(program: Command): void {
         'folder that does not resolve, or a destination already taken, moves',
         'nothing and refuses nothing.',
         '',
+        'With --pull-request, it refuses earlier-slice when a later number is',
+        'listed, and pending-branch while a Pending branch: line names a branch',
+        'whose own pull request is not recorded yet. A stem skips both.',
+        '',
         'Exit codes:',
         '  0  the task was archived',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -420,6 +426,10 @@ export function register(program: Command): void {
         'list is replaced. The board is shared scratch, so a linked worktree',
         'records against the same board.',
         '',
+        'It also drops the current branch, and each name it was renamed from,',
+        'from the Pending branch: line, even when the number was already',
+        'listed, and removes the line once empty.',
+        '',
         'Examples:',
         '  canon tasks pull-request 673 v28.1-trigger-escalation',
         '  canon tasks pull-request 673 --plan worktree-scratch-routing --json',
@@ -497,6 +507,11 @@ export function register(program: Command): void {
         'An outcome already closed is reported rather than refused, so a rerun',
         'against the same positions is safe.',
         '',
+        'Run from a branch other than main or master, a close that ticks a new',
+        'box names that branch on a Pending branch: line, which holds the task',
+        'against a merge-time archive until canon tasks pull-request records',
+        "the branch's own number.",
+        '',
         'Examples:',
         '  canon tasks outcome v28.1-trigger-escalation --close 1 --close 3',
         '  canon tasks outcome --plan worktree-scratch-routing --close 2 --json',
@@ -644,11 +659,63 @@ async function runPullRequest(
   }
 
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await recordPullRequest(root, selector, Number(number))
+  const branch = await workingBranch()
+  const outcome = await recordPullRequest(
+    root,
+    selector,
+    Number(number),
+    branch ? [branch, ...(await formerNames(branch))] : [],
+  )
 
   return reportPullRequest(outcome, emitJson, root)
 }
 
+const RENAME_PATTERN = /^Branch: renamed refs\/heads\/(.+) to refs\/heads\//
+
+/**
+ * Names the branch carried before each `git branch -m`, read off its reflog,
+ * which moves with a rename and records every earlier one. A marker written
+ * under an old name is otherwise one nothing ever clears.
+ */
+async function formerNames(branch: string): Promise<readonly string[]> {
+  const result = await execa(
+    'git',
+    [
+      '-C',
+      process.cwd(),
+      'reflog',
+      'show',
+      '--format=%gs',
+      `refs/heads/${branch}`,
+    ],
+    { reject: false, timeout: GIT_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+  )
+  if (result.exitCode !== 0) return []
+
+  return result.stdout
+    .split('\n')
+    .map((line) => RENAME_PATTERN.exec(line)?.[1])
+    .filter((name): name is string => name !== undefined)
+}
+
+/**
+ * The branch checked out where the command runs, which is where the work is,
+ * rather than the board root's. Undefined on trunk, a detached HEAD, or a
+ * failed read, where no slice is in flight to hold the task open.
+ */
+async function workingBranch(): Promise<string | undefined> {
+  const result = await execa(
+    'git',
+    ['-C', process.cwd(), 'branch', '--show-current'],
+    { reject: false, timeout: GIT_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+  )
+
+  const branch = result.exitCode === 0 ? result.stdout.trim() : ''
+  if (branch.length === 0 || TRUNK_BRANCHES.includes(branch)) return undefined
+
+  return branch
+}
+
 async function runPlanLink(
   task: string,
   plan: string,
@@ -710,7 +777,12 @@ async function runOutcome(
   }
 
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await closeOutcomes(root, selector, raw.map(Number))
+  const outcome = await closeOutcomes(
+    root,
+    selector,
+    raw.map(Number),
+    await workingBranch(),
+  )
 
   return reportOutcome(outcome, emitJson, root)
 }
@@ -765,6 +837,7 @@ function reportPullRequest(
         path: relative(root, outcome.path),
         pullRequest: outcome.number,
         action: outcome.action,
+        pending: outcome.pending,
       })}\n`,
     )
     return 0
@@ -773,6 +846,9 @@ function reportPullRequest(
   intro('canon tasks pull-request')
   logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
   logInfo(`${outcome.stem} names pull request #${outcome.number}`)
+  if (outcome.pending.length > 0) {
+    logInfo(`still pending on ${outcome.pending.join(', ')}`)
+  }
   if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
   outro()
 
@@ -831,6 +907,7 @@ function reportOutcome(
         path: relative(root, outcome.path),
         closed: outcome.closed,
         alreadyClosed: outcome.alreadyClosed,
+        pending: outcome.pending,
       })}\n`,
     )
     return 0
@@ -841,6 +918,9 @@ function reportOutcome(
 
   for (const closed of outcome.closed) logAdd(closed)
   for (const already of outcome.alreadyClosed) logInfo(`${already} (already)`)
+  if (outcome.pending.length > 0) {
+    logInfo(`pending on ${outcome.pending.join(', ')}`)
+  }
 
   if (outcome.closed.length > 0) logInfo(relative(root, outcome.path))
   outro()

package/src/gate/measures.ts

@@ -312,10 +312,9 @@ export const skillProvenance: Measure = async (ctx) => {
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *
- * Report-only for now: a document past the ceiling warns and the stage still
- * passes, since the corpus carried dozens past it when the stage landed. The
- * flip to a failure is a separate change once the count reads zero, and it
- * replaces the warn path rather than sitting beside it.
+ * A document past the ceiling fails the stage. The failure names every one with
+ * its height rather than the first, so a contributor sees the whole set in one
+ * pass, and an exempt document is counted and never named.
  *
  * Read in-process rather than through `canon markdown audit`, whose exit code
  * stays bans and dead links only. The plan and groundwork skills run that audit
@@ -353,15 +352,12 @@ export const documentCeiling: Measure = async (ctx) => {
     }
   }
 
+  const where = over
+    .map((finding) => `${finding.rel} ${finding.renderedLines} rendered lines`)
+    .join(', ')
   return {
-    emissions: [
-      ...over.map((finding) =>
-        warn(`${finding.rel}  ${finding.renderedLines} rendered lines`),
-      ),
-      info(
-        `${plural(over.length, 'document')} past the ${ceiling}-line ceiling, ${exempt} exempt. Reported only, so the push is not held.`,
-      ),
-    ],
+    emissions: [],
+    failure: `${plural(over.length, 'document')} past the ${ceiling}-line ceiling: ${where}. Split each at a seam, or for a verbatim record add a \`<!-- canon-length-exempt: <reason> -->\` line naming why.`,
   }
 }
 

package/src/gate/stages.ts

@@ -338,7 +338,7 @@ export const STAGES: readonly Stage[] = [
     // Only the citation half of the audit gates. Its length, depth, table, and
     // index findings are judgment thresholds, and failing a push on one would
     // make the stage something to route around. The one length reading that
-    // will gate is the whole-document ceiling, which the Document ceiling stage
+    // gates is the whole-document ceiling, which the Document ceiling stage
     // below owns rather than this audit.
     id: 'context-citations',
     label: 'Context citations',
@@ -360,8 +360,8 @@ export const STAGES: readonly Stage[] = [
     checks: [{ kind: 'measure', measure: architectureRecord }],
   },
   {
-    // Unscoped, since any branch can grow any document. It warns and passes
-    // until the corpus sits under the ceiling, then flips to a failure.
+    // Unscoped, since any branch can grow any document. A document past the
+    // ceiling fails the push.
     id: 'document-ceiling',
     label: 'Document ceiling',
     checks: [{ kind: 'measure', measure: documentCeiling }],

package/src/init/steps.ts

@@ -5,7 +5,7 @@ import type { DomainStep } from '@/init/run'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target-migrations.md`'s backup section in its
+ * States the same fact as `docs/target/target-migrations.md`'s backup section in its
  * own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =

package/src/labels/format.ts

@@ -22,8 +22,8 @@ const TITLE_MAX_LENGTH = 72
 
 // Casing-agnostic on purpose. Casing is graded separately once the shape
 // matches, so `type` and `scope` accept either case here and `structure`
-// reports only a title with no `<type>(<scope>): <subject>` shape at all.
-const TITLE_SHAPE = /^([A-Za-z]+)\(([A-Za-z0-9][\w.-]*)\): (.+)$/
+// reports only a title with no `<type>(<scope>)[!]: <subject>` shape at all.
+const TITLE_SHAPE = /^([A-Za-z]+)\(([A-Za-z0-9][\w.-]*)\)!?: (.+)$/
 const LEADING_LETTERS = /^[A-Za-z]+/
 
 /**

package/src/tasks/archive.ts

@@ -47,6 +47,7 @@ export const ARCHIVE_REFUSALS = [
   'no-outcomes',
   'open-outcomes',
   'earlier-slice',
+  'pending-branch',
   'bad-input',
 ] as const
 
@@ -251,6 +252,22 @@ export function readPullRequest(text: string): readonly number[] {
   return match[1].split(',').map((entry) => Number(entry.trim().slice(1)))
 }
 
+/**
+ * Reads the `Pending branch:` line `canon tasks outcome` writes when a branch
+ * ticks an outcome ahead of its own pull request number reaching the task.
+ * `canon tasks pull-request` clears each branch as it records, so a name left
+ * here is a slice whose number the `Pull request:` line cannot list yet.
+ */
+export function readPendingBranches(text: string): readonly string[] {
+  const match = /^Pending branch:(.*)$/m.exec(text)
+  if (!match) return []
+
+  return match[1]
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
 /** A markdown link on a `Plan:` line, its target captured. */
 const PLAN_LINK_PATTERN = /\[[^\]]*\]\(([^)]+)\)/g
 
@@ -860,6 +877,19 @@ export async function archiveTask(
     )
   }
 
+  // A branch ticks its outcome before `git-pr` appends its number, so in that
+  // window the number above reads as last while it is not. The stem selector
+  // skips this check the way it skips the one above, since a hand archive is
+  // the route out of a pending branch that was abandoned.
+  const pending = readPendingBranches(text)
+  if (selector.kind === 'pull-request' && pending.length > 0) {
+    return refuse(
+      'pending-branch',
+      `${stem} still waits on ${pending.join(', ')}, which closed an outcome before its own pull request was recorded, so the task closes when that pull request merges.`,
+      pending,
+    )
+  }
+
   const { open, closed, cut } = readOutcomes(text)
 
   if (open.length > 0) {

package/src/tasks/record.ts

@@ -10,6 +10,7 @@ import {
   OUTCOME_PATTERN,
   planLine,
   planLineIndex,
+  readPendingBranches,
   readPlanTargets,
   readPullRequest,
   tasksDir,
@@ -63,6 +64,8 @@ export interface PullRequestRecorded {
   readonly path: string
   readonly number: number
   readonly action: LineAction
+  /** Branches still on the `Pending branch:` line after this write. */
+  readonly pending: readonly string[]
 }
 
 export type PullRequestOutcome = PullRequestRecorded | RecordRefused
@@ -85,6 +88,8 @@ export interface OutcomesClosed {
   readonly path: string
   readonly closed: readonly string[]
   readonly alreadyClosed: readonly string[]
+  /** Branches on the `Pending branch:` line after this write. */
+  readonly pending: readonly string[]
 }
 
 export type CloseOutcome = OutcomesClosed | RecordRefused
@@ -146,16 +151,77 @@ export function writePullRequestLine(
   return { text: lines.join('\n'), action: 'added' }
 }
 
-function lastOriginLine(lines: readonly string[]): number | undefined {
+function lastOriginLine(
+  lines: readonly string[],
+  prefixes: readonly string[] = ORIGIN_PREFIXES,
+): number | undefined {
   let found: number | undefined
 
   for (const [index, line] of lines.entries()) {
-    if (ORIGIN_PREFIXES.some((prefix) => line.startsWith(prefix))) found = index
+    if (prefixes.some((prefix) => line.startsWith(prefix))) found = index
   }
 
   return found
 }
 
+const PENDING_PREFIX = 'Pending branch:'
+
+/**
+ * Names a branch on the `Pending branch:` line, which holds the task open
+ * against a merge-time archive until that branch's own number is recorded. The
+ * line sits under `Pull request:` when one exists, since a later slice ticks
+ * after an earlier slice's number is already listed.
+ */
+export function writePendingBranch(
+  text: string,
+  branch: string,
+): { readonly text: string; readonly changed: boolean } {
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith(PENDING_PREFIX))
+
+  if (existing !== -1) {
+    const pending = readPendingBranches(lines[existing])
+    if (pending.includes(branch)) return { text, changed: false }
+    lines[existing] = `${PENDING_PREFIX} ${[...pending, branch].join(', ')}`
+    return { text: lines.join('\n'), changed: true }
+  }
+
+  const line = `${PENDING_PREFIX} ${branch}`
+  const anchor = lastOriginLine(lines, [...ORIGIN_PREFIXES, 'Pull request:'])
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return { text: lines.join('\n'), changed: true }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, changed: true }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), changed: true }
+}
+
+/** Drops a branch from the `Pending branch:` line, and the line once it is empty. */
+export function clearPendingBranch(
+  text: string,
+  branch: string,
+): { readonly text: string; readonly changed: boolean } {
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith(PENDING_PREFIX))
+  if (existing === -1) return { text, changed: false }
+
+  const pending = readPendingBranches(lines[existing])
+  if (!pending.includes(branch)) return { text, changed: false }
+
+  const rest = pending.filter((entry) => entry !== branch)
+  if (rest.length > 0) {
+    lines[existing] = `${PENDING_PREFIX} ${rest.join(', ')}`
+  } else {
+    lines.splice(existing, 1)
+  }
+
+  return { text: lines.join('\n'), changed: true }
+}
+
 export type PlanLineWrite =
   | {
       readonly ok: true
@@ -330,24 +396,43 @@ async function openTask(
  * this from a linked worktree, where an in-place edit through the file-editing
  * tools is refused and a shell stream editor is banned, so the write has to
  * resolve the board root in-process.
+ *
+ * `branches` names the recording branch and every name it carried before a
+ * rename, since `git-ship` renames a branch after `context-fold` has already
+ * written the marker under the old name. Each comes off the `Pending branch:`
+ * line even when the number was already listed, so a rerun repairs a stale
+ * marker.
  */
 export async function recordPullRequest(
   root: string,
   selector: RecordSelector,
   number: number,
+  branches: readonly string[] = [],
 ): Promise<PullRequestOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
 
   const { stem, path } = opened
-  const { text, action } = writePullRequestLine(
-    await readFile(path, 'utf8'),
-    number,
-  )
+  const numbered = writePullRequestLine(await readFile(path, 'utf8'), number)
+  let text = numbered.text
+  let isCleared = false
+
+  for (const branch of branches) {
+    const cleared = clearPendingBranch(text, branch)
+    text = cleared.text
+    isCleared ||= cleared.changed
+  }
 
-  if (action !== 'unchanged') await writeFile(path, text)
+  if (numbered.action !== 'unchanged' || isCleared) await writeFile(path, text)
 
-  return { ok: true, stem, path, number, action }
+  return {
+    ok: true,
+    stem,
+    path,
+    number,
+    action: numbered.action,
+    pending: readPendingBranches(text),
+  }
 }
 
 /**
@@ -399,11 +484,17 @@ export async function recordPlan(
  * Marks the named outcomes `[x]` in place. `context-fold` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions
  * come from the read it already made.
+ *
+ * A `branch` that ticks at least one new box goes on the `Pending branch:`
+ * line, so the merge of an earlier slice cannot archive the task in the window
+ * before this branch's own number is recorded. A rerun that ticks nothing adds
+ * no marker, since its branch has already recorded or is already listed.
  */
 export async function closeOutcomes(
   root: string,
   selector: RecordSelector,
   positions: readonly number[],
+  branch?: string,
 ): Promise<CloseOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
@@ -427,7 +518,12 @@ export async function closeOutcomes(
     )
   }
 
-  if (result.closed.length > 0) await writeFile(path, result.text)
+  const text =
+    result.closed.length > 0 && branch
+      ? writePendingBranch(result.text, branch).text
+      : result.text
+
+  if (result.closed.length > 0) await writeFile(path, text)
 
   return {
     ok: true,
@@ -435,5 +531,6 @@ export async function closeOutcomes(
     path,
     closed: result.closed,
     alreadyClosed: result.alreadyClosed,
+    pending: readPendingBranches(text),
   }
 }

package/standards/commit.md

@@ -17,7 +17,7 @@ Does not govern:
 
 ## Format
 
-- Structure: `<type>(<scope>): <subject>`
+- Structure: `<type>(<scope>): <subject>`, with `!` before the colon for a breaking change
 - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
 - Subject: 72 characters maximum, no trailing period
 

package/standards/pr.md

@@ -20,7 +20,7 @@ Does not govern:
 
 ## Title
 
-- Format: `<type>(<scope>): <subject>`
+- Format: `<type>(<scope>): <subject>`, with `!` before the colon for a breaking change
 - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
 - Length: 72 characters maximum
 

package/standards/tasks.md

@@ -72,7 +72,7 @@ Add no third heading. Status stays inline on an outcome rather than becoming an
 
 Size the outcomes so one pull request closes all of them, and split the task before handing it off rather than after. A task closes whole or not at all, so outcomes spanning two pull requests leave the board showing in-progress work no branch carries.
 
-A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked.
+A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked and no slice left pending.
 
 Prefix the H1 with the `vX.Y:` phase label, then a short title whose form depends on the task type:
 
@@ -134,7 +134,7 @@ One plan per task. A plan cited by two tasks is a misfile rather than a shape to
 
 `Pull request:` records which pull requests carry the task's work, each as a bare `#NNN` the way `Issue:` does. It lists every pull request that shipped part of the task, oldest first and separated by commas, as in `Pull request: #NNN, #NNN`, and a task shipped whole lists one. It is not an origin, so a task without one is well-formed. `git-pr` appends to it when a pull request opens.
 
-The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving.
+The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving. `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number, since `canon tasks outcome` writes it and `canon tasks pull-request` clears it.
 
 ## What goes in