@erclx/canon 4.73.0 → 4.74.0

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

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

package/claude/skills/plan-feature/SKILL.md

@@ -52,8 +52,8 @@ What this skill adds on top of the standard:
 
 A plan sequencing its work into batches declares where one pull request ends, here rather than at ship time. A dependency chain cannot be split once it is built, so the choice exists only while the batches are still a plan.
 
-- One batch is one pull request. Carry one entry per batch naming what it targets, so a plan opening five says five before the first line is written.
-- A dependent batch stacks rather than merging into its neighbor. The batches are built in order and depend on each other in that order, which is what a stack expresses, so the dependency argues for stacking and never for collapsing two batches into one review.
+- One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename, so a `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that one branch across every batch, and the batch that merges first strands every batch behind it with nothing left to open a pull request against. Write a plan opening five batches as five files before the first line of any of them.
+- State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it. The batches are built in order and depend on each other in that order, which is what a stack expresses, so the dependency argues for stacking and never for collapsing two batches into one file or one review.
 - Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request. One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
 - Sequence a sweep last. A batch deliberately rewriting files earlier batches touched is coherent as the final one and forces every batch behind it into one review anywhere else.
 - Keep each batch's commits contiguous once the work starts. A later fix to an earlier batch belongs on that batch's own commits, since a batch interrupted by another cannot be lifted onto its own branch afterward.

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

@@ -46,11 +46,12 @@ List `.canon/groundwork/` from the project root and match the topic against the
 
 Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never a track.
 
-With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. Also list `.canon/intake/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md`. Then route on `.canon/groundwork/<nn>-<slug>/`:
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. That is open mode outright: no folder can carry a slug nothing matched yet, so there is nothing to route on. `<nn>` for it is claimed in Open mode Step 1 rather than here, since the qualifying test below has to run before the folder exists.
 
-- Folder absent: open
-- Folder present without `06-decision.md`: resume
-- Present folder the user judges ready: close
+A matched folder instead routes on its own `<nn>-<slug>/`:
+
+- Present without `06-decision.md`: resume
+- Present and the user judges it ready: close
 
 Detect the mode from the folder. Do not ask which one to run.
 
@@ -73,7 +74,7 @@ The standard sets the open question format and requires it inside a topic file a
 
 ## Open mode
 
-1. Create `.canon/groundwork/<nn>-<slug>/`, with `<nn>` and `<slug>` as derived in Step 1.
+1. Claim the ordinal and create the folder in one act with `canon records ordinal groundwork <slug> --claim`, per `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md`. Where the installed binary carries no such subcommand, fall back to listing both `.canon/groundwork/` and `.canon/intake/` and creating `.canon/groundwork/<nn>-<slug>/` at the highest ordinal present across the two, incremented.
 2. Write `README.md` first. Writing it first forces the question of what the track is for.
 3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
 4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.

package/claude/skills/plan-intake/SKILL.md

@@ -42,7 +42,7 @@ List `.canon/intake/` from the project root and match the topic against the slug
 
 Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
 
-With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Also list `.canon/groundwork/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/intake.md`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Claim the ordinal and create the folder in one act with `canon records ordinal intake <slug> --claim`, per `${CLAUDE_SKILL_DIR}/../../standards/intake.md`. Where the installed binary carries no such subcommand, fall back to listing both `.canon/intake/` and `.canon/groundwork/` and taking the highest ordinal present across the two, incremented. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
 
 ## Step 2: orient
 

package/claude/skills/role-orchestrator/references/orchestrator-dispatch.md

@@ -28,6 +28,7 @@ Run `canon tasks plan-answers <plan> --json` and read `launchable` off the recor
 - `launchable: false`: the row is not dispatchable. Report every entry in `open`, each carrying the question label and the reason its suggestion gave for needing a person, and hand the row to the human-launch line below. Never fill the slot on the operator's behalf, which is the one move the plan standard forbids outright.
 - `reason: archived`: the row's plan sits in `.canon/plans/archive/` and describes work that already shipped. Repoint the row at a live plan rather than dispatching, since `auto-ship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
 - The command refuses for any other reason, or the record carries no `launchable` key: treat the row as unverified rather than clear, name what could not be read, and fall back to the human. A gate that reads nothing and proceeds is the gate not running.
+- The same read also refuses a plan still staging its batches in one file with `**Batch N**` sub-headings. That reports as an entry in `open` labeled `Batch staging`, so a staged plan reads as `launchable: false` the same way an unanswered operator call does, and the row waits on a split rather than on the operator.
 
 Branch on `launchable` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero and so read a held row as a clear one.
 

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

@@ -24,7 +24,7 @@ Take the board rows in board order and finish one before opening the next. Clear
 The blocker cell states what the row waits on, and each kind is tested differently. `canon tasks validate` already re-takes the first two and reports the rest as untested, so run it first and re-take by hand only what it names.
 
 - Collision with a track in flight: the validator tests the file the cell cites against the Touches column of every `## Run now` row. A track that merged since the row was parked is no longer in flight, whatever the sets still share. A cell naming the file in prose rather than in backticks cites nothing, so write the collision the way the board format spells it and the check picks the row up on the next run.
-- A dependency on another task: the validator opens the task a link in the cell names. One whose outcomes are all `[x]`, or one already archived, holds nothing. A cell naming the task in prose resolves to no file, so open it by hand and rewrite the cell as a link.
+- A dependency on another task: the validator opens the task a link in the cell names. One whose outcomes are all `[x]`, one already archived, or one already declined, holds nothing. A cell naming the task in prose resolves to no file, so open it by hand and rewrite the cell as a link.
 - A condition about the tree, such as a count of some shape or the presence of a construct: measure it again, per Two ways a re-test goes wrong below.
 - Waiting on a plan: nothing external holds the row, so the pass writes the plan rather than testing anything. See The plan half below.
 - Waiting on an operator action, such as a run that happens from a shell: record it as untestable this pass and name what the operator has to do. A session cannot clear it, and re-measuring it every pass is waste.
@@ -72,6 +72,7 @@ A scoping defect can wear a blocker. A task whose file set collides with every o
 ```plaintext
 Re-tested: <row>, <blocker> → <what the measurement showed>
 Cleared: <row>, now <group>, plan at <path>
+Declined: <row>, waited on <task> which was declined, now <group>
 Still parked: <row>, <blocker> re-confirmed against <what was measured>
 Untestable: <row>, waits on <operator action>
 Split: <task> into <tasks>, file set collided with everything by construction

package/claude/skills/task-board/SKILL.md

@@ -14,7 +14,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` before writing any file. It
 - Resolve the board at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo. Every read and write below resolves against that root. The board is gitignored scratch shared across worktrees, so a linked worktree writing to its own `pwd` creates a second board nothing else reads.
 - From a linked worktree the file-editing tools refuse that root, so a new task file goes out through `Bash` as a plain single command carrying a heredoc. Archiving already runs through `canon tasks archive`, which resolves the root in-process. Marking an outcome shipped is `docs-fold` and runs through `canon tasks outcome`. Resolve that root the way `session-worktree` does.
 - If `.canon/tasks/` does not exist at that root, stop: `❌ No .canon/tasks/ board. Run canon claude init to set it up.`
-- Route on the request rather than on a flag. Creating names work that does not exist yet, archiving names a task file already on the board. If the request fits neither, stop: `❌ Ambiguous. Say whether to create a task or archive one.`
+- Route on the request rather than on a flag. Creating names work that does not exist yet, archiving names a task file already shipped, and declining names one decided against. If the request fits none of the three, stop: `❌ Ambiguous. Say whether to create a task, archive one, or decline one.`
 - Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter after a write. Do not run the regen command directly, except after a shell write from a linked worktree: the hook matches `Write|Edit|MultiEdit` and nothing fires on `Bash`, so that one case regenerates explicitly with `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`.
 
 ## Create
@@ -63,13 +63,13 @@ Scan for work that has been decided and would otherwise be forgotten. Three orig
 
 List `.canon/groundwork/` and run `gh issue list --state open` when a remote is configured, then grep the board for each track name and issue number. Report any with no task, one line each.
 
-Read the dumps through `canon intake list --json`, which reports items, open, unread, and malformed per folder and owns the parse of the answer contract `${CLAUDE_SKILL_DIR}/../../standards/intake.md` fixes. Then grep both `.canon/tasks/` and `.canon/tasks/archive/` for each folder slug. A dump with no live task is the ordinary shape of one already promoted and shipped, so a check reading the board by itself reports every finished folder as abandoned.
+Read the dumps through `canon intake list --json`, which reports items, open, unread, and malformed per folder and owns the parse of the answer contract `${CLAUDE_SKILL_DIR}/../../standards/intake.md` fixes. Then grep `.canon/tasks/`, `.canon/tasks/archive/`, and `.canon/tasks/declined/` for each folder slug. A dump with no live task is the ordinary shape of one already promoted and either shipped or declined, so a check reading the board by itself reports every settled folder as abandoned.
 
 A dump is the stronger case for this scan rather than the weaker one. A track holds one question and stays visible, while a dump holds dozens of items whose verdicts were reached and then left with nothing carrying them forward.
 
 Those two reads give four states, and the first three earn a line each:
 
-- Every item answered, `malformed` at zero, and neither the board nor the archive cites the folder. Decided work nobody promoted, which is what this step exists to find.
+- Every item answered, `malformed` at zero, and none of the board, the archive, or the declined folder cites it. Decided work nobody promoted, which is what this step exists to find.
 - Unread items. The folder is waiting on the operator rather than forgotten, so it takes its own wording and never lands in the block above.
 - `malformed` above zero. An item carrying no answer slot can be reached by no verb, so name the folder as a file to repair rather than as work in either state above.
 - The archive cites it. Promoted and shipped, so say nothing.
@@ -129,6 +129,40 @@ Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It recor
 
 The command drops the task's row from `.canon/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the rows that changed, since a stale count reads as board state.
 
+## Decline
+
+A task decided against carries no `post-merge` hook of its own, so every decline request arrives here directly rather than through work the hook already did.
+
+Do not move the file, edit `priority.md` or `backlog.md`, or regenerate the index by hand. `canon tasks decline` owns all three as one unit.
+
+### Step 1: gather the reason
+
+Ask for the reason when the request does not carry one, and stop rather than guessing: `❌ No reason. Say why the task is being declined.` The command takes it as `--reason <text>` and refuses without it, so gathering it here saves a round trip through that refusal.
+
+### Step 2: run the decline
+
+Pass the task's filename stem:
+
+```bash
+canon tasks decline <stem> --reason "<text>" [--by <name>] --json
+```
+
+The command refuses rather than reports, and the refusal reaches this skill through the record rather than through the exit, the same wrapper hazard `canon tasks archive` carries. Branch on `ok`, then on `reason`.
+
+On success the record carries `from`, `to`, `priorityRowRemoved`, `backlogRowRemoved`, and `indexRegenerated`, where `backlogRowRemoved` is decline's own field since a task can be declined straight off `backlog.md` and archive never checks that file. It also carries `plan` when the task was the last live citation of a live plan, holding the `from` and `to` of the plan moved alongside it, the same shape `canon tasks archive` uses for its own `plan` field.
+
+### Step 3: route on a refusal
+
+- `no-match`: the stem does not name exactly one task. Either none matches, or exactly one starts with it and the full name is needed. Check the name against the listed stems.
+- `ambiguous`: the stem is a prefix more than one task starts with, unlike archive's own `ambiguous`, which fires on a shared pull request. Decline takes no pull-request selector, so this is the only route to it. Pass the full stem.
+- `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.
+
+Do not move a plan by hand from this skill. The command carries the plan with the task when no other live task cites it, and retargets the declined task's `Plan:` line at the new path. A second mover drifts into relocating the same file differently.
+
+### Step 4: clear prose naming the task
+
+The command drops the task's row from `.canon/tasks/priority.md` or `.canon/tasks/backlog.md` and leaves prose alone. Remove any sentence that still names the declined task or counts the rows that changed, since a stale count reads as board state.
+
 ## Output
 
 Emit the full relative path from the project root for every file written or moved. A bare filename names a file the reader cannot open.

package/docs/agents/commands.md

@@ -48,6 +48,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon teach nav`                | Rewrite the teach-root listing, a workspace's contents page, and each lesson's chrome from its four marker regions (`--json`)                                                                                                                                                                                          |
 | `canon records validate`         | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                                                                                                                                                                           |
 | `canon records migrate`          | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                                                                                                                                                                         |
+| `canon records ordinal`          | Report or claim the next ordinal `intake` and `groundwork` share, creating the folder atomically (`--claim`, `--json`)                                                                                                                                                                                                 |
 | `canon records size`             | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                                                                                                                                                                           |
 | `canon records push`             | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                                                                                                                                                                             |
 | `canon records pull`             | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                                                                                                                                                                                |

package/docs/agents/index.md

@@ -29,7 +29,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
-- [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates

package/docs/agents/install-and-sync.md

@@ -402,16 +402,19 @@ so this section reports and gates nothing.
 
 ## Bootstrap
 
-`canon init` installs up to four core domains and reports each one independently. A
+`canon init` installs up to five core domains and reports each one independently. A
 domain that fails does not abort the run, so the command finishes the rest and
 exits 1 naming the failures. Passing any flag skips the confirmation prompt,
 which is what makes it scriptable.
 
 `--stack` defaults to `base`, and the default
 does not read as a passed flag, so a bare `canon init` installs governance and
-still prompts. `--skip` takes `wiki` and `governance`, and warns
-without aborting on any other value. There is no `--standards` and no
-`--snippets`, since no run writes either corpus into the target.
+still prompts. `--skip` takes `wiki`, `governance`, and `records`, and warns
+without aborting on any other value. Records has nothing to run non-interactively,
+since the private backup repository does not exist yet at scaffold time, so its
+step only prints the one-time setup reminder and `--skip records` silences it.
+There is no `--standards` and no `--snippets`, since no run writes either corpus
+into the target.
 
 ## Unguarded tooling primitives
 

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+description: The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -39,14 +39,14 @@ Nothing fires it automatically. The five record folders are gitignored, so the s
 
 ### What each kind checks
 
-| Kind         | What it reports                                                                                                                                                                                                                                                                                                  |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot                                                                               |
-| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                            |
-| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                       |
-| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                  |
-| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                   |
-| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal |
+| Kind         | What it reports                                                                                                                                                                                                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, a question carrying no suggestion or no answer slot, and a batch still staged with a `**Batch N**` sub-heading inside the one file rather than split into its own plan |
+| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                                                             |
+| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                                                        |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                                                   |
+| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                                                    |
+| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal                                  |
 
 The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
 
@@ -104,6 +104,26 @@ A transform runs only where the missing value is recoverable from the file itsel
 
 Exit codes: `0` nothing carried a known transform, or `--write` repaired everything it found. `1` refused for a reason `validate` shares, every candidate it found failed to repair, or `--write` repaired only some of them. `2` a record carries a known transform and `--write` was not passed.
 
+## Ordinal
+
+`canon records ordinal <kind> <slug>` reports the next ordinal `intake` and `groundwork` share, or claims it with `--claim`. The two kinds share one sequence, per `standards/intake.md` and `standards/groundwork.md`, so this reads both `.canon/intake/` and `.canon/groundwork/` regardless of which kind was asked for.
+
+```bash
+canon records ordinal intake my-topic
+canon records ordinal groundwork my-topic --claim
+canon records ordinal groundwork my-topic --claim --json
+```
+
+| Option          | Behavior                                               |
+| --------------- | ------------------------------------------------------ |
+| `--json`        | Add a machine-readable record on stdout                |
+| `--claim`       | Create the folder atomically instead of only reporting |
+| `--root <path>` | Project root, defaulting to the main worktree          |
+
+Without `--claim` this only reports, so two sessions reading at once can still report the same number, which is what let two sessions open two different record folders under one ordinal on the same day. `--claim` closes that: it reserves the number at a path both an `intake` claim and a `groundwork` claim resolve to identically, whichever kind is asking, and only creates the kind's own `<nn>-<slug>/` folder once that reservation is won. A losing reservation is retried against a freshly read ordinal rather than reported as a collision, bounded to five attempts before refusing as `ordinal-contended`.
+
+Exit codes: `0` reported the next ordinal, or `--claim` created the folder. `1` refused, `unknown-kind` when the argument names neither `intake` nor `groundwork`. `2` `--claim` lost every retry to a collision.
+
 ## Size
 
 `canon records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus the scratch folder, and it gates nothing.

package/docs/agents/tasks.md

@@ -141,6 +141,8 @@ A relative path resolves against the project root first and against `.canon/task
 
 `canon tasks plan-citations` reads a task's `Plan:` line against those same two bases in the opposite order, and tests that the target lands under the live plans folder, which this verb does not. Both answer the same file for every spelling a board writes. Liveness is a separate refusal here: a plan resolving inside `.canon/plans/archive/` returns `archived` rather than a launchable reading, since it answers every question and describes work that already shipped.
 
+A plan still staging its batches with a `**Batch N**` sub-heading inside one file's `**Files to touch:**` reads `launchable: false` the same way, alongside the operator-call case. It reports as an entry in `open` labeled `Batch staging`, stating that the plan must split into one file per batch before it can dispatch, since the row waits on a split rather than on the operator.
+
 | Option          | Effect                                      |
 | --------------- | ------------------------------------------- |
 | `--json`        | Emit a machine-readable record on stdout    |

package/docs/target-projects.md

@@ -143,6 +143,10 @@ The first line takes the `.canon/` ignore entry, and the verb refuses until the
 
 Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
 
+### Back records up off this machine, once
+
+Moving records under `.canon/` relocates them, and relocating them is not the same as backing them up. Run `canon records push` once a private repository exists for them, and it prints the one-time setup command when it finds none, since the task board, the memory pen, and the groundwork trails otherwise live on one disk with nothing pushing them off it. `canon init` prints the same reminder as a notice-only step rather than trying to run this non-interactively, since the private repository does not exist yet at scaffold time.
+
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 
 A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the nearest non-blank line above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.

package/package.json

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

package/src/commands/records.ts

@@ -3,6 +3,13 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
 import { migrateRecord } from '@/records/migrate'
+import {
+  type ClaimOutcome,
+  claimOrdinal,
+  highestOrdinal,
+  isOrdinalKind,
+  ORDINAL_KINDS,
+} from '@/records/ordinal'
 import {
   type FolderSize,
   formatBytes,
@@ -40,6 +47,9 @@ const EXIT_FINDINGS = 2
 /** Returned when a record carries a known transform and `--write` was not passed. */
 const EXIT_MIGRATABLE = 2
 
+/** Returned when `--claim` loses every retry to a collision. */
+const EXIT_CONTENDED = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -51,6 +61,10 @@ interface MigrateCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
 }
 
+interface OrdinalCommandOptions extends ValidateCommandOptions {
+  readonly claim?: boolean
+}
+
 export function register(program: Command): void {
   const records = program
     .command('records')
@@ -140,6 +154,49 @@ export function register(program: Command): void {
       process.exitCode = await runMigrate(kind, opts)
     })
 
+  records
+    .command('ordinal')
+    .description(
+      'Report or claim the next ordinal shared by intake and groundwork folders',
+    )
+    .argument('<kind>', `Ordinal-bearing folder: ${ORDINAL_KINDS.join(', ')}`)
+    .argument('<slug>', 'The kebab-case slug the new folder will carry')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--claim',
+      'Create the folder atomically instead of only reporting the ordinal',
+    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'intake and groundwork folders share one ordinal sequence, so this reads',
+        'both .canon/intake/ and .canon/groundwork/ regardless of which kind was',
+        'asked for.',
+        '',
+        'Exit codes:',
+        '  0  reported the next ordinal, or --claim created the folder',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  --claim lost every retry to a collision',
+        '',
+        'Without --claim this only reports, so two sessions reading at once can',
+        'still report the same number. --claim resolves that by creating the',
+        'folder as part of the same act, retrying past a losing race rather than',
+        'reporting one.',
+        '',
+        'Examples:',
+        '  canon records ordinal intake my-topic',
+        '  canon records ordinal groundwork my-topic --claim',
+        '  canon records ordinal groundwork my-topic --claim --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, slug: string, opts: OrdinalCommandOptions) => {
+      process.exitCode = await runOrdinal(kind, slug, opts)
+    })
+
   records
     .command('size')
     .description('Report what each record folder holds and how much is recent')
@@ -726,3 +783,84 @@ export function migrateExitCode(
   if (!write) return EXIT_MIGRATABLE
   return refused.length > 0 ? 1 : 0
 }
+
+async function runOrdinal(
+  kind: string,
+  slug: string,
+  opts: OrdinalCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isOrdinalKind(kind)) {
+    return reportRefusal(
+      'canon records ordinal',
+      {
+        reason: 'unknown-kind',
+        message: `Not an ordinal-bearing kind: ${kind}. Expected one of: ${ORDINAL_KINDS.join(', ')}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const claim = opts.claim ?? false
+
+  if (!claim) {
+    const next = String((await highestOrdinal(root)) + 1).padStart(2, '0')
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: true, root, kind, slug, ordinal: next, claimed: false })}\n`,
+      )
+    } else {
+      intro('canon records ordinal')
+      logStep('Next')
+      logInfo(`${next}-${slug} (report only, pass --claim to create it)`)
+      outro()
+    }
+
+    return 0
+  }
+
+  return reportOrdinal(root, await claimOrdinal(root, kind, slug), emitJson)
+}
+
+function reportOrdinal(
+  root: string,
+  outcome: ClaimOutcome,
+  emitJson: boolean,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stderr.write(`${outcome.message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({
+          ok: false,
+          reason: outcome.reason,
+          message: outcome.message,
+          lastOrdinal: outcome.lastOrdinal,
+        })}\n`,
+      )
+      return EXIT_CONTENDED
+    }
+
+    intro('canon records ordinal')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return EXIT_CONTENDED
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, ...outcome, claimed: true })}\n`,
+    )
+  } else {
+    intro('canon records ordinal')
+    logStep('Claimed')
+    logInfo(outcome.path)
+    outro()
+  }
+
+  return 0
+}

package/src/commands/transcripts.ts

@@ -1,24 +1,41 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { recordDir } from '@/record-root'
 import { ensureYtDlp, fetchOne } from '@/transcripts/fetch'
 import { palette } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 interface TranscriptOptions {
-  out: string
+  out?: string
   keepTimestamps?: boolean
 }
 
+/**
+ * A caller-supplied `--out` resolves against the CWD, since naming a path
+ * explicitly opts out of the backed default. With none, the destination is
+ * the backed `transcripts` record folder at the main worktree root, which
+ * `canon records push` and `canon records pull` carry along with the rest.
+ */
+export async function resolveOutDir(opts: TranscriptOptions): Promise<string> {
+  return opts.out
+    ? resolve(process.cwd(), opts.out)
+    : recordDir(await mainWorktreeRoot(), 'transcripts')
+}
+
 export function register(program: Command): void {
   program
     .command('transcripts <url>')
     .description('Fetch a YouTube transcript with metadata frontmatter')
-    .option('-o, --out <path>', 'Output directory', 'transcripts')
+    .option(
+      '-o, --out <path>',
+      'Output directory, defaulting to the backed transcripts record folder',
+    )
     .option(
       '--keep-timestamps',
       'Prefix each line with [mm:ss] instead of prose',
     )
     .action(async (url: string, opts: TranscriptOptions) => {
-      const outDir = resolve(process.cwd(), opts.out)
+      const outDir = await resolveOutDir(opts)
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}canon transcripts${NC}\n`,

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance'] as const
+export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'records'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -104,6 +104,13 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
+  if (!flags.skip.skipped.has('records')) {
+    preview.push({
+      level: 'info',
+      text: 'records (one-time backup setup notice)',
+    })
+  }
+
   const total = preview.filter((line) => line.level === 'info').length
 
   return { preview, total }

package/src/init/steps.ts

@@ -4,6 +4,13 @@ import type { DomainStep } from '@/init/run'
 /** Builds the child-process invocation for one domain. */
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
+/**
+ * States the same fact as `docs/target-projects.md`'s backup section in its
+ * own words. Keep the two in step by hand; nothing compares them.
+ */
+const RECORDS_SETUP_NOTICE =
+  "No private repository to push to yet. Run 'canon records push' once one exists to print the one-time setup command, or --skip records to silence this."
+
 /**
  * Orders the domains an init installs. Base tooling seeds the files the later
  * domains install alongside, so the sequence is part of the contract rather
@@ -56,6 +63,16 @@ export function buildSteps(
     })
   }
 
+  if (!flags.skip.skipped.has('records')) {
+    // `skip` here means there is nothing to run non-interactively, not that
+    // the caller opted out, unlike every other push of this kind above.
+    steps.push({
+      kind: 'skip',
+      label: 'Records backup',
+      notice: RECORDS_SETUP_NOTICE,
+    })
+  }
+
   return steps
 }
 

package/src/intake/folder.ts

@@ -138,7 +138,7 @@ function matchSlug(names: readonly string[], slug: string): SlugMatch {
   return { kind: 'none' }
 }
 
-function extractOrdinal(name: string): string {
+export function extractOrdinal(name: string): string {
   return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
 }