@erclx/canon 5.68.0 → 5.70.0

package/claude/skills/plan-ready/references/ready.md

@@ -1,128 +0,0 @@
----
-title: Ready reference
-description: Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
----
-
-# Ready reference
-
-Applies to a ready folder at `.canon/ready/<nn>-<slug>/`. A warm session that has already written a finished file uses it to hand the exact text to the worker that ships it, since a cold worker reading a plan's description writes the file again from scratch.
-
-The folder holds the finished files at their destination paths, so the worker copies rather than authors. It is gitignored, which is why the archive step below is a move rather than a cleanup.
-
-- Where a records remote is configured, `canon records push` and `canon records pull` protect it against the machine being lost
-- Where none is, they refuse with `no-remote`
-- Neither protects a folder deleted before anyone has pushed
-
-## Contents
-
-- [Scope](#scope)
-- [What a working ready folder looks like](#what-a-working-ready-folder-looks-like)
-- [Folder name](#folder-name)
-- [00-overview.md](#00-overviewmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
-- [The mirrored tree](#the-mirrored-tree)
-- [The thin-plan contract](#the-thin-plan-contract)
-- [Lifecycle](#lifecycle)
-- [Anti-patterns](#anti-patterns)
-- [Template](#template)
-
-## Scope
-
-The `plan-ready` skill owns the procedure, and this standard owns the shape. It governs a ready folder under `.canon/ready/<nn>-<slug>/`, being its layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
-
-Does not govern:
-
-- The thin plan itself, its filename, its sections, and its suggested-and-answer contract: `plan.md`
-- The task file that reaches a ready folder through a plan, and the origin line pointing back at it: `tasks.md`
-- Voice, rhythm, and sentence construction: the `write-human` skill
-- Headings, punctuation, word choice, and file references: `markdown.md`
-- Whether a change earns a ready folder over a plan a worker builds from scratch, which belongs to the warm session deciding how to hand off its own work
-
-## What a working ready folder looks like
-
-A ready folder works when a worker that has never seen the warm session's conversation can copy from it alone:
-
-- Which destination path does each file land at, and does the folder hold nothing else?
-- What is the worker still responsible for that the files themselves do not carry, such as a docs sync, a sandbox scenario, or a test?
-- What branch type does the change take?
-- Is every path the folder mirrors also declared in the thin plan's `## Files to touch`?
-
-A ready folder failing these is non-conforming even when it satisfies every shape rule below.
-
-## Folder name
-
-- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug matching the plan's own slug.
-- The ordinal marks a folder per handoff, opened once by the warm session that writes it
-- It runs on its own sequence, separate from groundwork and intake's shared one, since a ready folder is not a measurement track
-- The first folder opened takes `01`. After that, read the highest existing `.canon/ready/<nn>-*/` folder, including the archive, and take the next integer.
-- Never renumber an existing folder. The ordinal is the order it opened, and the pull request that shipped it cites the folder by that name.
-
-## 00-overview.md
-
-Every ready folder carries `00-overview.md` at its root, beside the mirrored tree. It orients the worker and states what the files themselves cannot.
-
-- `title` (required): the change in sentence case
-- `description` (required): one line naming what the handoff carries
-- `type` (required): the branch type the plan should take, one of the types `branch.md` fixes
-- `destinations` (required): the list of destination paths the folder mirrors, matching the thin plan's `## Files to touch` exactly
-
-```yaml
----
-title: <Change in sentence case>
-description: <one line naming what the handoff carries>
-type: <feat | fix | chore | ...>
-destinations:
-  - <path/to/file>
----
-```
-
-Below the frontmatter, state in prose what the worker still owns beyond copying the files: a docs sync, a sandbox scenario update, a test the files do not include, or "nothing further" where the files are the whole of the change.
-
-The overview body and the thin plan both hold to the six structure criteria under `### Structure` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. The mirrored files are exempt, since each lands as its destination's own standard fixes.
-
-## The mirrored tree
-
-Every other file in the folder sits at the same relative path its destination has in the project.
-
-- For example, `standards/ready.md` in the destination tree sits at `<nn>-<slug>/standards/ready.md` in the ready folder <!-- canon-allow-reference: a target tree -->
-- Carry no file the destination tree would not carry. The folder is a source for `git mv`-shaped copies, never a scratch pad, and anything else goes in the plan or the pull request body.
-- Write each file exactly as it should land. The worker copies verbatim and edits only what the gate or the overview's list requires, so a placeholder ships as written.
-
-## The thin-plan contract
-
-- A ready folder ships through an ordinary task row and a plan at `.canon/plans/feature-<slug>.md`, per `plan.md`. No new plan shape exists for it.
-- Name the ready folder in the plan's `## Constraints`, stating that the folder's files are the verbatim source for the paths the plan's `## Files to touch` lists.
-- List every destination path in `## Files to touch`, matching `00-overview.md`'s `destinations` field
-- A path the plan omits is invisible to `plan-reach`'s collision check, so a mismatch between the two lists is a defect in the plan, not a variant
-- Keep the plan thin. Its `## Files to touch` entries may point at the folder's copy for the reason behind each file, since the overview and the files carry that detail.
-
-## Lifecycle
-
-- Write the ready folder in the same session that writes the files it carries. A folder assembled later from memory is a plan with extra steps, not a handoff.
-- Leave the move to `canon tasks archive`, which carries the folder to `.canon/ready/archive/<nn>-<slug>/` with its plan when the shipping task archives, retargeting its `Ready:` line
-- A plan another live task still cites keeps its folder
-- Never delete a ready folder. The archived copy sits beside the merged pull request as the exact text that shipped, the way an archived plan sits beside the reasoning that produced it.
-
-## Anti-patterns
-
-- **The folder with an undeclared destination.** A file the plan's `## Files to touch` omits passes the collision check unseen, so a second track can write the same path with neither side finding out.
-- **The rewritten copy.** A worker that reads the folder's files as inspiration and writes its own version loses the exact text the handoff exists to carry.
-- **The folder as scratch.** Notes, alternates, or draft passages left in the folder beside the real files leave the worker guessing which is the source.
-- **The folder left live after shipping.** An unmoved folder reads as unshipped work to the next session listing it. The verb skips one whose task has no `Ready:` line and whose plan cites no folder.
-
-## Template
-
-```markdown
-.canon/ready/<nn>-<slug>/
-├── 00-overview.md
-└── <path/to/file> # mirrors the destination tree, one entry per file
-```
-
-```yaml
----
-title: <Change in sentence case>
-description: <one line naming what the handoff carries>
-type: <feat | fix | chore | ...>
-destinations:
-  - <path/to/file>
----
-```

package/docs/target/migrations.md

@@ -1,203 +0,0 @@
----
-title: Target migrations
-description: One-time moves a project scaffolded under an older toolkit runs before its next sync
-category: Agent surface
----
-
-# Target migrations
-
-Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves a project still needs in the order to run them. The recurring sync that follows is in [target sync](sync.md).
-
-`canon:target-update` is the guided path through both. It runs the moves in that order once you approve its preview.
-
-## Move the records first, once
-
-Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
-
-```bash
-canon tooling sync claude . --write
-canon migrate records --json
-canon migrate records --write --json
-```
-
-The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
-
-Then sweep the citations inside the records, which the verb above never reaches.
-
-```bash
-canon migrate record-tree --json
-canon migrate record-tree --write --json
-```
-
-It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
-
-## Back records up off this machine, once
-
-Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
-
-## Move rules off the flat layout, once
-
-Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
-
-```bash
-canon migrate rule-layout --json
-canon migrate rule-layout --write --json
-```
-
-Run it once, ahead of `canon gov sync` or `canon gov install`.
-
-## Rename the skill citations, once
-
-Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. The five per-kind drafters merged into `write-doc`, and no pointer under an old name ships. <!-- canon-keep-retired -->
-
-The seven `draft-` skills took verb-first names for what each makes. `canon migrate skill-names --write` carries a project across, and a pointer under each old name answers a typed invocation until it retires.
-
-| Old name           | New name                                        |
-| ------------------ | ----------------------------------------------- |
-| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
-| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
-| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
-| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
-| `draft-and-pick`   | `pick-by-eye` <!-- canon-keep-retired -->       |
-| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
-| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
-
-Replace a citation of a skill with no successor by hand, or delete the sentence.
-
-- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare prose mention by hand. <!-- canon-keep-retired -->
-- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request. Replace a bare mention of the skill by hand. <!-- canon-keep-retired -->
-- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
-- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
-- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, and `ux-walkthrough` have no successor <!-- canon-keep-retired -->
-
-The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
-
-- `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
-- `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
-
-Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
-
-```bash
-canon gov sync
-canon tooling sync <stack> . --write
-canon migrate skill-names --json
-canon migrate skill-names --write --json
-```
-
-## Rename the pull request template headings, once
-
-The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
-
-## Move the surfaces off `.claude/`, once
-
-`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
-
-```bash
-canon migrate surface-roots --json
-canon migrate surface-roots --write --json
-```
-
-It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
-
-## Delete the retired snippets, once
-
-A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
-
-```bash
-canon sync --check . --json | jq '.reverse'
-```
-
-- `dropped` is the toolkit's copy, unchanged, so delete it
-- `unattributed` is often an edited copy, so read what changed first
-- `project` is the project's own content, so leave it
-
-From the registry the walk reports `historyUnavailable`, so check both paths by hand.
-
-## Stop calling the standards verb, once
-
-`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
-
-| Skill             | Standards                                                     |
-| ----------------- | ------------------------------------------------------------- |
-| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
-| `context-fold`    | `context`                                                     |
-| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
-| `docs-sync`       | `docs`, `readme`                                              |
-| `draw-figure`     | `figures`, `mermaid`                                          |
-| `create-rule`     | `rule`                                                        |
-| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
-| `git-branch`      | `branch`, `slug`                                              |
-| `git-commit`      | `commit`, `versioning`                                        |
-| `git-pr`          | `pr`, `publish`                                               |
-| `markdown-craft`  | `markdown`                                                    |
-| `teach-workspace` | `glossary`, `teach` <!-- canon-keep-retired -->               |
-| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
-| `plan-intake`     | `intake`                                                      |
-| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
-| `plan-ready`      | `ready`                                                       |
-| `write-doc`       | `requirements`, `wiki`                                        |
-| `session-map`     | `session`                                                     |
-
-The `standard` name became `skill-reference.md` in `create-skill`.
-
-## Keep or delete the wireframes folder, your call
-
-The wireframes record is retired, and nothing deletes what a project holds.
-
-- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
-- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
-- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
-
-## Keep or delete the retired product files, your call
-
-The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
-
-- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
-- `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
-- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
-
-A reference to a retired skill takes a hand edit.
-
-- Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
-- Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
-- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:pick-by-eye` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
-
-## Move decisions out of a held architecture record, once
-
-The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.
-
-## Deny subagents and merges, and turn auto memory off, once
-
-The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
-
-```bash
-canon migrate session-defaults --json
-canon migrate session-defaults --write --json
-```
-
-The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
-
-The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.
-
-## Move the capture cases out of the harness, once
-
-A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
-
-- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
-- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
-- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
-
-## Fold the ui rules onto one pointer, once
-
-Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
-
-```bash
-canon gov sync .
-```
-
-## Group a long paths section in `CLAUDE.md`, once
-
-The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
-
-- Regroup the section by hand under H3s, each opening on a one-sentence lead.
-- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.