@erclx/canon 4.60.0 → 4.62.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/claude-tasks/REQUIREMENT.md +2 -2
- package/claude/skills/claude-tasks/SKILL.md +4 -4
- package/claude/skills/setup-indexes/REQUIREMENT.md +3 -0
- package/claude/skills/setup-indexes/SKILL.md +8 -0
- package/claude/skills/setup-smoke/REQUIREMENT.md +38 -0
- package/claude/skills/setup-smoke/SKILL.md +53 -0
- package/claude/skills/setup-verify/REQUIREMENT.md +4 -4
- package/claude/skills/setup-verify/SKILL.md +3 -3
- package/docs/agents/commands.md +83 -79
- package/docs/agents/tasks.md +26 -0
- package/docs/target-projects.md +2 -0
- package/docs/workflow/ai-workflow.md +11 -10
- package/governance/rules/ui/440-surface-capture.md +4 -2
- package/package.json +1 -1
- package/src/claude/cases/setup.ts +5 -0
- package/src/commands/migrate.ts +136 -0
- package/src/commands/tasks.ts +84 -0
- package/src/migrate/scratch-evidence.ts +319 -0
- package/src/tasks/label.ts +110 -0
- package/tooling/astro/reference.md +6 -0
- package/tooling/web/configs/e2e/screenshot.ts +28 -1
- package/tooling/web/manifest.toml +1 -0
- package/tooling/web/reference.md +3 -2
|
@@ -7,7 +7,7 @@ description: Why creating and archiving a task file is one skill, the origin inv
|
|
|
7
7
|
|
|
8
8
|
## Gap
|
|
9
9
|
|
|
10
|
-
Without this skill, a task file gets a filename and frontmatter invented on the spot, so the board sorts wrong and the regenerated index reads fields that are not there. A task arrives with no origin, which is either lost context or work nobody decided to do, and by the time anyone notices there is no way to recover which it was. The phase label gets derived from a version file rather than from what the board already means, and a single-digit phase sorts after a double-digit one because nobody padded it.
|
|
10
|
+
Without this skill, a task file gets a filename and frontmatter invented on the spot, so the board sorts wrong and the regenerated index reads fields that are not there. A task arrives with no origin, which is either lost context or work nobody decided to do, and by the time anyone notices there is no way to recover which it was. The phase label gets derived from a version file rather than from what the board already means, and a single-digit phase sorts after a double-digit one because nobody padded it. A label picked off the live board alone repeats one the archive already spent, since the archive holds most of what has ever been allocated and a board-only scan cannot see it.
|
|
11
11
|
|
|
12
12
|
Archiving fails in two ways that both lose work. Moving the file, editing the ordering file, and regenerating the index as three separate acts drifts from the one command the merge hook calls, so the attended and unattended paths stop agreeing. And an all-`[x]` task gets archived while its pull request is still open, because marking outcomes happens on the branch as the first step of shipping. The board is gitignored, so nothing restores a task archived early.
|
|
13
13
|
|
|
@@ -18,7 +18,7 @@ Placing a row without checking for another writer collides the same way. Two ses
|
|
|
18
18
|
- Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
|
|
19
19
|
- Read the tasks standard before writing, rather than working the filename and frontmatter from memory
|
|
20
20
|
- Require an origin at creation, because that is the only moment the invariant is enforceable
|
|
21
|
-
-
|
|
21
|
+
- Read the phase label from `canon tasks next-label` rather than proposing one by hand
|
|
22
22
|
- Check the roster for a live orchestrator before writing a row, and hand off rather than write when one is found
|
|
23
23
|
- Confirm the work reached the default branch before archiving
|
|
24
24
|
- Run the archive command and route on the reason it refuses, since each reason has one resolution
|
|
@@ -27,11 +27,11 @@ A task with no origin is either lost context or work nobody decided to do. This
|
|
|
27
27
|
|
|
28
28
|
Accept work whose origin is the conversation itself only when the user says so explicitly, and record what it was in the intro paragraph instead of writing a link line to a file that does not exist.
|
|
29
29
|
|
|
30
|
-
### Step 2:
|
|
30
|
+
### Step 2: allocate the phase label
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
Run `canon tasks next-label --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows.
|
|
33
33
|
|
|
34
|
-
Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the
|
|
34
|
+
Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the verb's two folders are the only surface that knows what a label currently means.
|
|
35
35
|
|
|
36
36
|
### Step 3: write the file
|
|
37
37
|
|
|
@@ -138,7 +138,7 @@ Create:
|
|
|
138
138
|
```plaintext
|
|
139
139
|
✅ Created: .canon/tasks/vXX.Y-<slug>.md
|
|
140
140
|
|
|
141
|
-
<label
|
|
141
|
+
<label>, next after <highest>.
|
|
142
142
|
<board or backlog, and why it landed there>.
|
|
143
143
|
|
|
144
144
|
**Origin with no task:**
|
|
@@ -15,6 +15,8 @@ One failure predates the scan. `setup-init` declines an install that wants the C
|
|
|
15
15
|
|
|
16
16
|
Drafted frontmatter is a proposal, and a session that writes it before the user sees it turns a review into a cleanup. The convention block has the mirror failure. A session that paraphrases it into `CLAUDE.md` produces a copy that reads correctly and no longer matches its source, so the two drift with nothing reporting it. And a project with no `CLAUDE.md` gets one scaffolded to hold the block, which installs a file the project declined.
|
|
17
17
|
|
|
18
|
+
A fourth failure sits after the scan rather than inside it. `## Present candidates` had no branch for a scan that finds zero folders, so an empty result walked straight into the ask with nothing to choose from. `setup-init` folds this skill into the onboarding chain, and a fresh scaffold usually carries no markdown-heavy folder yet, so the ordinary onboarding run reached the undefined case.
|
|
19
|
+
|
|
18
20
|
## Must
|
|
19
21
|
|
|
20
22
|
- Bootstrap all-or-nothing per chosen folder, since a folder carrying partial frontmatter hard-errors on regen
|
|
@@ -36,6 +38,7 @@ Drafted frontmatter is a proposal, and a session that writes it before the user
|
|
|
36
38
|
|
|
37
39
|
- A folder with fewer than the sibling threshold stays out of the candidate list unless the user names it explicitly, so the scan proposes and the user overrides
|
|
38
40
|
- A `CLAUDE.md` already carrying the convention section skips the seed silently rather than appending a second copy
|
|
41
|
+
- A scan that finds no candidate reports a one-line result and returns, skipping the ask and every step between it and the seed offer, rather than opening a prompt with nothing in it
|
|
39
42
|
|
|
40
43
|
## Out of scope
|
|
41
44
|
|
|
@@ -29,6 +29,14 @@ For each candidate, capture:
|
|
|
29
29
|
|
|
30
30
|
## Present candidates
|
|
31
31
|
|
|
32
|
+
If the scan found no candidate, report the flat result and skip ahead:
|
|
33
|
+
|
|
34
|
+
```plaintext
|
|
35
|
+
No folder has three or more markdown siblings without an index.md already. Nothing to bootstrap.
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Skip past the ask below and every step between it and the seed offer, straight to `## Offer the convention seed`. There is no candidate to ask about, so this stops rather than opening a prompt with nothing in it.
|
|
39
|
+
|
|
32
40
|
Output one line per candidate:
|
|
33
41
|
|
|
34
42
|
```plaintext
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup-smoke
|
|
3
|
+
description: Why the heavy scaffold stages need an owner and what heuristic judges a server smoke pass
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Setup smoke requirement
|
|
7
|
+
|
|
8
|
+
## Gap
|
|
9
|
+
|
|
10
|
+
Without this skill, a freshly scaffolded project's dev server, preview server, end-to-end suite, and screenshot harness never run anywhere. `setup-verify` excludes all three for the flakiness reasons that make them wrong for an unattended chain, and names no destination for any of them, so a broken dev server or a missing end-to-end dependency surfaces only once the user hits it by hand.
|
|
11
|
+
|
|
12
|
+
A dev or preview server carries no exit code to read, since it runs until stopped rather than finishing on its own, unlike the leaf scripts `setup-verify` runs. Judging it needs a heuristic rather than a pass/fail read.
|
|
13
|
+
|
|
14
|
+
## Must
|
|
15
|
+
|
|
16
|
+
- Read the scripts the project declares and run only those, skip absent ones
|
|
17
|
+
- Run `dev`, `preview`, `test:e2e`, `screenshot` in that fixed order, stopping at the first failure
|
|
18
|
+
- Judge a server script by running it in the background, waiting a fixed window, checking the process is alive and its output carries no fatal error string, then killing it regardless of the outcome
|
|
19
|
+
- Install dependencies itself when missing, so it runs standalone without `setup-verify` having run first
|
|
20
|
+
|
|
21
|
+
## Must not
|
|
22
|
+
|
|
23
|
+
- Invent a fallback command for an absent script
|
|
24
|
+
- Run a composite script
|
|
25
|
+
- Require `setup-verify` to have passed first
|
|
26
|
+
- Duplicate a leaf script `setup-verify` already runs
|
|
27
|
+
- Get invoked by anything other than a person or a chain naming it directly. Review this at each future change, since nothing can answer it before the skill has run. `canon docs target-projects` states the scaffold chain that keeps it outside the unattended path, for the same flakiness reasons that keep it out of `setup-verify`'s own leaf-script order.
|
|
28
|
+
|
|
29
|
+
## Guards
|
|
30
|
+
|
|
31
|
+
- No `package.json` at the project root stops, since there are no declared scripts to read
|
|
32
|
+
- A missing dependency folder installs first rather than letting every script fail on the same cause
|
|
33
|
+
|
|
34
|
+
## Out of scope
|
|
35
|
+
|
|
36
|
+
- The leaf scripts `setup-verify` already runs: `lint:fix`, `typecheck`, `check`, `test:run`, `build`
|
|
37
|
+
- Generating the configs these scripts drive, which the tooling stack reference owns
|
|
38
|
+
- A true port-probe readiness check, since no manifest key exposes a generic port across stacks
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup-smoke
|
|
3
|
+
description: Runs the heavy scaffold checks setup-verify skips - dev and preview server smoke, Playwright end-to-end tests, and the screenshot harness - on the same declared-scripts contract. Use after setup-verify passes, or when asked to "run the smoke tests", "check the dev server", "run e2e against the scaffold", or "run the heavy checks". Do NOT use in place of setup-verify, or on a project without package.json.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Smoke scaffold
|
|
7
|
+
|
|
8
|
+
Runs the local checks a scaffold's leaf scripts cannot cover: whether the dev and preview servers actually start, whether the end-to-end suite passes against a real server, and whether the screenshot harness produces output. Standalone from `setup-verify`. Neither skill requires the other to have run first.
|
|
9
|
+
|
|
10
|
+
## Guards
|
|
11
|
+
|
|
12
|
+
- If `package.json` does not exist at the project root, stop: `❌ No package.json found. Cannot smoke test.`
|
|
13
|
+
- If `node_modules/` does not exist, run `bun install` first, then proceed.
|
|
14
|
+
|
|
15
|
+
## Step 1: read scripts
|
|
16
|
+
|
|
17
|
+
Read `package.json` from the project root and extract the `scripts` block. Do not hardcode script names.
|
|
18
|
+
|
|
19
|
+
## Step 2: run the chain
|
|
20
|
+
|
|
21
|
+
Run the scripts below in order. Stop on the first failure and surface the error.
|
|
22
|
+
|
|
23
|
+
| Order | Script | Skip if | How judged |
|
|
24
|
+
| ----- | ------------ | ------- | ----------------------- |
|
|
25
|
+
| 1 | `dev` | absent | server smoke, see below |
|
|
26
|
+
| 2 | `preview` | absent | server smoke, see below |
|
|
27
|
+
| 3 | `test:e2e` | absent | leaf script: exit code |
|
|
28
|
+
| 4 | `screenshot` | absent | leaf script: exit code |
|
|
29
|
+
|
|
30
|
+
Skip any script not present in `package.json`. Do not invent a fallback command. Run each leaf script as `bun run <script>` from the project root.
|
|
31
|
+
|
|
32
|
+
### Server smoke
|
|
33
|
+
|
|
34
|
+
`dev` and `preview` run until stopped, so there is no exit code to read. Start the script backgrounded, wait 5 seconds, then check two things: the process is still running, and its captured output carries no string matching `error`, `Error`, or `fatal`. Kill the process either way once judged. Report a failure on either check failing.
|
|
35
|
+
|
|
36
|
+
This is weaker than a real readiness probe. No manifest key exposes a generic port to poll across stacks, so port-probing is out of reach here.
|
|
37
|
+
|
|
38
|
+
## Step 3: report
|
|
39
|
+
|
|
40
|
+
For each script run, report one of:
|
|
41
|
+
|
|
42
|
+
- `✅ <script>`
|
|
43
|
+
- `❌ <script>` followed by the failing output (last 40 lines) or, for a server script, the reason judged (process died, or a fatal string in its output)
|
|
44
|
+
|
|
45
|
+
End with a summary line:
|
|
46
|
+
|
|
47
|
+
- On pass: `✅ Scaffold smoke-tested (<n> scripts passed).`
|
|
48
|
+
- On fail: `❌ Scaffold failed at <script>. Fix the error and re-run setup-smoke.`
|
|
49
|
+
|
|
50
|
+
## Out of scope
|
|
51
|
+
|
|
52
|
+
- `lint:fix`, `typecheck`, `check`, `test:run`, `build`. Those are `canon:setup-verify`'s leaf-script chain.
|
|
53
|
+
- Generating the configs these scripts drive, which the tooling stack reference owns.
|
|
@@ -11,7 +11,7 @@ Without this skill, a freshly scaffolded project is handed over on the strength
|
|
|
11
11
|
|
|
12
12
|
The naive check fails two ways. A session that assumes script names runs `test` against a stack that exposes `test:run`, or invents a fallback command when a script is absent, and either result reports on something the project never declared. A session that runs a composite script gets one failure covering several stages, so the output names the wrapper rather than the break.
|
|
13
13
|
|
|
14
|
-
The stages left out are the ones that lie. A dev server or a preview reads as failed when it starts slowly, a browser test needs an install and a running server before it can even fail correctly, and a CI workflow cannot be judged locally at all. Including any of them turns a scaffold check into a flaky one, and a flaky check gets ignored.
|
|
14
|
+
The stages left out are the ones that lie, and each now has an owner in `canon:setup-smoke` rather than nowhere at all. A dev server or a preview reads as failed when it starts slowly, a browser test needs an install and a running server before it can even fail correctly, and a CI workflow cannot be judged locally at all. Including any of them turns a scaffold check into a flaky one, and a flaky check gets ignored.
|
|
15
15
|
|
|
16
16
|
## Must
|
|
17
17
|
|
|
@@ -33,7 +33,7 @@ The stages left out are the ones that lie. A dev server or a preview reads as fa
|
|
|
33
33
|
|
|
34
34
|
## Out of scope
|
|
35
35
|
|
|
36
|
-
- Dev and preview smoke tests, which `project-commands` starts on request
|
|
37
|
-
- Browser end-to-end tests, which need a browser install and a running server
|
|
38
|
-
- CI workflow validation, which runs on the pull request rather than locally
|
|
36
|
+
- Dev and preview smoke tests, which `project-commands` starts on request and `canon:setup-smoke` checks automatically
|
|
37
|
+
- Browser end-to-end tests, which need a browser install and a running server, covered by `canon:setup-smoke`
|
|
38
|
+
- CI workflow validation, which runs on the pull request rather than locally. `canon:setup-smoke` runs the same stages locally as the closest proxy
|
|
39
39
|
- Generating the configs it checks, which the tooling stack reference owns
|
|
@@ -46,6 +46,6 @@ End with a summary line:
|
|
|
46
46
|
|
|
47
47
|
## Out of scope
|
|
48
48
|
|
|
49
|
-
- Dev server and preview server smoke tests. Too flaky for a scaffold check, where a slow start reads as a failure. Use `project-commands` to start one on request.
|
|
50
|
-
- Playwright E2E tests. Require browser install and a running server.
|
|
51
|
-
- CI workflow validation. Runs in GitHub Actions on PR, not locally.
|
|
49
|
+
- Dev server and preview server smoke tests. Too flaky for a scaffold check, where a slow start reads as a failure. Use `project-commands` to start one on request, or `canon:setup-smoke` to check both automatically.
|
|
50
|
+
- Playwright E2E tests. Require browser install and a running server. Use `canon:setup-smoke`.
|
|
51
|
+
- CI workflow validation. Runs in GitHub Actions on PR, not locally. `canon:setup-smoke` runs the same end-to-end and screenshot stages locally, as the closest proxy.
|
package/docs/agents/commands.md
CHANGED
|
@@ -9,85 +9,87 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
|
|
|
9
9
|
|
|
10
10
|
## Project-level
|
|
11
11
|
|
|
12
|
-
| Command
|
|
13
|
-
|
|
|
14
|
-
| `canon init [path]`
|
|
15
|
-
| `canon sync [path]`
|
|
16
|
-
| `canon sync --check`
|
|
17
|
-
| `canon sandbox [cat:cmd]`
|
|
18
|
-
| `canon sandbox reset`
|
|
19
|
-
| `canon sandbox clean`
|
|
20
|
-
| `canon sandbox check`
|
|
21
|
-
| `canon sandbox coverage`
|
|
22
|
-
| `canon indexes regen`
|
|
23
|
-
| `canon indexes list [path]`
|
|
24
|
-
| `canon docs [topic]`
|
|
25
|
-
| `canon design render`
|
|
26
|
-
| `canon design regen`
|
|
27
|
-
| `canon design css`
|
|
28
|
-
| `canon design install`
|
|
29
|
-
| `canon design sync`
|
|
30
|
-
| `canon slides render`
|
|
31
|
-
| `canon slides list`
|
|
32
|
-
| `canon feedback`
|
|
33
|
-
| `canon transcripts <url>`
|
|
34
|
-
| `canon tasks archive`
|
|
35
|
-
| `canon tasks pull-request`
|
|
36
|
-
| `canon tasks plan-link`
|
|
37
|
-
| `canon tasks outcome`
|
|
38
|
-
| `canon tasks validate`
|
|
39
|
-
| `canon
|
|
40
|
-
| `canon intake
|
|
41
|
-
| `canon
|
|
42
|
-
| `canon teach
|
|
43
|
-
| `canon teach
|
|
44
|
-
| `canon teach
|
|
45
|
-
| `canon teach
|
|
46
|
-
| `canon teach
|
|
47
|
-
| `canon
|
|
48
|
-
| `canon records
|
|
49
|
-
| `canon records
|
|
50
|
-
| `canon records
|
|
51
|
-
| `canon records
|
|
52
|
-
| `canon
|
|
53
|
-
| `canon migrate
|
|
54
|
-
| `canon migrate
|
|
55
|
-
| `canon migrate
|
|
56
|
-
| `canon
|
|
57
|
-
| `canon
|
|
58
|
-
| `canon
|
|
59
|
-
| `canon
|
|
60
|
-
| `canon
|
|
61
|
-
| `canon
|
|
62
|
-
| `canon
|
|
63
|
-
| `canon
|
|
64
|
-
| `canon claude skills
|
|
65
|
-
| `canon
|
|
66
|
-
| `canon claude skills
|
|
67
|
-
| `canon claude
|
|
68
|
-
| `canon
|
|
69
|
-
| `canon
|
|
70
|
-
| `canon gov
|
|
71
|
-
| `canon gov
|
|
72
|
-
| `canon
|
|
73
|
-
| `canon
|
|
74
|
-
| `canon
|
|
75
|
-
| `canon
|
|
76
|
-
| `canon
|
|
77
|
-
| `canon
|
|
78
|
-
| `canon
|
|
79
|
-
| `canon pr
|
|
80
|
-
| `canon
|
|
81
|
-
| `canon
|
|
82
|
-
| `canon
|
|
83
|
-
| `canon
|
|
84
|
-
| `canon
|
|
85
|
-
| `canon
|
|
86
|
-
| `canon
|
|
87
|
-
| `canon
|
|
88
|
-
| `canon
|
|
89
|
-
| `canon
|
|
90
|
-
| `canon
|
|
12
|
+
| Command | Purpose |
|
|
13
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `canon init [path]` | Bootstrap a project with selected toolkit domains |
|
|
15
|
+
| `canon sync [path]` | Sync all installed domains in a target project |
|
|
16
|
+
| `canon sync --check` | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`) |
|
|
17
|
+
| `canon sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads |
|
|
18
|
+
| `canon sandbox reset` | Reset sandbox to baseline |
|
|
19
|
+
| `canon sandbox clean` | Wipe the sandbox |
|
|
20
|
+
| `canon sandbox check` | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict) |
|
|
21
|
+
| `canon sandbox coverage` | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`) |
|
|
22
|
+
| `canon indexes regen` | Regenerate `index.md` files from sibling frontmatter |
|
|
23
|
+
| `canon indexes list [path]` | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`) |
|
|
24
|
+
| `canon docs [topic]` | Emit toolkit reference docs (`list`, or a topic by name) |
|
|
25
|
+
| `canon design render` | Render `.claude/DESIGN.md` tokens to HTML and CSS |
|
|
26
|
+
| `canon design regen` | Rewrite this repository's `.claude/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts` |
|
|
27
|
+
| `canon design css` | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone) |
|
|
28
|
+
| `canon design install` | Install the base stylesheet into a project at `.claude/design/base.css` |
|
|
29
|
+
| `canon design sync` | Update a base stylesheet already installed under `.claude/design/` |
|
|
30
|
+
| `canon slides render` | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr |
|
|
31
|
+
| `canon slides list` | List the available slide layouts (`--json` for the catalog) |
|
|
32
|
+
| `canon feedback` | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`, refusing either when a required field is absent |
|
|
33
|
+
| `canon transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`) |
|
|
34
|
+
| `canon tasks archive` | Move a shipped task and its plan off the board, clear its ordering row, and regenerate the index |
|
|
35
|
+
| `canon tasks pull-request` | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`) |
|
|
36
|
+
| `canon tasks plan-link` | Write or correct a task's `Plan:` line to point at a plan, by stem and plan path or slug (`--json`) |
|
|
37
|
+
| `canon tasks outcome` | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`) |
|
|
38
|
+
| `canon tasks validate` | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`) |
|
|
39
|
+
| `canon tasks next-label` | Report the next unused phase label across the board and its archive (`--json`) |
|
|
40
|
+
| `canon intake list` | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`) |
|
|
41
|
+
| `canon intake answer` | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`) |
|
|
42
|
+
| `canon teach list` | Report learning workspaces and the ordinal a new one takes, or what one workspace holds and what its records schedule (`--json`) |
|
|
43
|
+
| `canon teach open` | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`) |
|
|
44
|
+
| `canon teach resource` | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`) |
|
|
45
|
+
| `canon teach glossary` | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`) |
|
|
46
|
+
| `canon teach stylesheet` | Seed a workspace stylesheet from the design source, leaving an existing one alone without `--force` (`--json`) |
|
|
47
|
+
| `canon teach nav` | Rewrite the teach-root listing, a workspace's contents page, and each lesson's chrome from its four marker regions (`--json`) |
|
|
48
|
+
| `canon records validate` | Report a session record or a standard against the standard governing it, per kind (`--json`) |
|
|
49
|
+
| `canon records migrate` | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`) |
|
|
50
|
+
| `canon records size` | Report what each record folder holds and how much of it is recent, heaviest first (`--json`) |
|
|
51
|
+
| `canon records push` | Commit the nine backed record folders and push them to a private records remote (`--json`) |
|
|
52
|
+
| `canon records pull` | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`) |
|
|
53
|
+
| `canon migrate rename` | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`) |
|
|
54
|
+
| `canon migrate records` | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`) |
|
|
55
|
+
| `canon migrate record-tree` | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`) |
|
|
56
|
+
| `canon migrate rule-layout` | Move a target's installed rules from the flat `.claude/rules/<subdir>/` layout to `.claude/rules/canon/<subdir>/`, reporting the plan without `--write` (`--root`, `--json`) |
|
|
57
|
+
| `canon migrate scratch-evidence` | Move a folder under `.tmp/` that a durable record cites as evidence to `.canon/review/evidence/`, repointing every citation live or archived, reporting the plan without `--write` (`--root`, `--json`) |
|
|
58
|
+
| `canon sessions list` | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`) |
|
|
59
|
+
| `canon worktrees list` | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`) |
|
|
60
|
+
| `canon worktrees reclaim` | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`) |
|
|
61
|
+
| `canon comments scan` | Measure comment density by language and comment kind, with a trend recomputed from git |
|
|
62
|
+
| `canon context audit` | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
|
|
63
|
+
| `canon markdown audit` | Fail any markdown path on a banned character, word, or spelling, or a dead relative link, and report the structural checkpoints |
|
|
64
|
+
| `canon claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md` |
|
|
65
|
+
| `canon standards audit` | Report the corpus against the success-criterion gate `standards/standard.md` states, failing only on a standard new to the branch (`--json`, `--arrivals-only`) |
|
|
66
|
+
| `canon claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`) |
|
|
67
|
+
| `canon claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one |
|
|
68
|
+
| `canon claude skills rank` | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`) |
|
|
69
|
+
| `canon claude routing` | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`) |
|
|
70
|
+
| `canon gov test-order` | Report where an implementation reached history ahead of the test covering it (`--json`) |
|
|
71
|
+
| `canon gov superseded` | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
|
|
72
|
+
| `canon gov restated` | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`) |
|
|
73
|
+
| `canon gov citations` | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`) |
|
|
74
|
+
| `canon secrets scan` | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`) |
|
|
75
|
+
| `canon deps audit` | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
|
|
76
|
+
| `canon labels audit` | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`) |
|
|
77
|
+
| `canon labels scan` | Fail a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`) |
|
|
78
|
+
| `canon autoship classify` | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`) |
|
|
79
|
+
| `canon pr key-changes` | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`) |
|
|
80
|
+
| `canon pr head` | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`) |
|
|
81
|
+
| `canon pr checks` | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`) |
|
|
82
|
+
| `canon repo metadata propose` | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`) |
|
|
83
|
+
| `canon repo metadata apply` | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`) |
|
|
84
|
+
| `canon census [path]` | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`) |
|
|
85
|
+
| `canon audits run` | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`, `--corpus`) |
|
|
86
|
+
| `canon audits list` | List every audit the set runs, with the corpus each reads and whether it gates (`--json`) |
|
|
87
|
+
| `canon gate run` | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`) |
|
|
88
|
+
| `canon inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`) |
|
|
89
|
+
| `canon drive <url> <run>` | Walk a page through named interactions and measure each state it reaches, reporting findings rather than gating (`--json`) |
|
|
90
|
+
| `canon capture [source]` | Render HTML sources to PNG and prove the font each one declares resolved (`--selector` required, `--out`) |
|
|
91
|
+
| `canon serve [dir]` | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`) |
|
|
92
|
+
| `canon upgrade` | Reinstall the CLI globally with the package manager the install path names (`--json`) |
|
|
91
93
|
|
|
92
94
|
`canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
|
|
93
95
|
|
|
@@ -161,6 +163,8 @@ Every citation in scope is reported with its file, its line number, and the line
|
|
|
161
163
|
|
|
162
164
|
`migrate rule-layout` moves a target still on the flat installed-rule layout onto the `canon/`-wrapped one. It classifies each flat file against the target's own recorded stamp: an unchanged hash is clean, a changed one is edited, and a name neither the stamp nor the current rule catalog can vouch for is unclaimed and left in place. Clean and edited files both relocate with their content untouched, since moving a rule is a different decision from re-syncing it. The one renumbered rule reads its destination from a table rather than from its own current name, so it never lands as a second copy under the retired number.
|
|
163
165
|
|
|
166
|
+
`migrate scratch-evidence` moves a folder out of `.tmp/` for good rather than repointing a citation in place. A promoted folder is one a durable record, live or archived, cites as its evidence, and no source file under `claude/`, `scripts/`, `src/`, `governance/`, or `standards/` names by path, which is what a script still writing into it fails. It walks every `canon records push` folder rather than the live ones alone, since most of what it repoints sits in `tasks/archive/`, `plans/archive/`, and `groundwork/`. A destination already occupied is a refusal, and a second run rewriting nothing is the same idempotence check `migrate record-tree` uses.
|
|
167
|
+
|
|
164
168
|
A destination that already holds the same bytes marks the flat file a duplicate, which `--write` deletes rather than moves. One holding different bytes is a real collision: neither file is touched, it is reported by name, and every other planned move still applies independently. Run this before `canon gov install` or `canon gov sync` against a target still on the flat layout, since neither bootstrap verb detects or clears it on its own.
|
|
165
169
|
|
|
166
170
|
## Version skew
|
package/docs/agents/tasks.md
CHANGED
|
@@ -5,6 +5,32 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
|
|
|
5
5
|
|
|
6
6
|
# Tasks
|
|
7
7
|
|
|
8
|
+
## Next label
|
|
9
|
+
|
|
10
|
+
`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. It reports and never writes.
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
canon tasks next-label
|
|
14
|
+
canon tasks next-label --json
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
| Option | Effect |
|
|
18
|
+
| --------------- | ------------------------------------------- |
|
|
19
|
+
| `--json` | Emit a machine-readable record on stdout |
|
|
20
|
+
| `--root <path>` | Board root, defaulting to the main worktree |
|
|
21
|
+
|
|
22
|
+
The record carries `label`, the next free `vXX.Y`, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
|
|
23
|
+
|
|
24
|
+
Exit codes: `0` derived, `1` refused with `no-board`.
|
|
25
|
+
|
|
26
|
+
The minor digit rolls from 9 to 0 on the next major rather than growing a second digit, which is the single-digit-minor shape every phase label already takes. `canon tasks archive` moves a task's file from the live folder into the archive without renumbering it, so the same label counts toward the maximum wherever it currently sits, and a label claimed by two different files folds into the same scan without a dedicated check.
|
|
27
|
+
|
|
28
|
+
It reports rather than gates. Two sessions calling it in the same second can still take the same answer, since the board is gitignored files rather than a store with a lock, and `standards/versioning.md` permits free renumbering, so a collision costs a rename rather than anything worse.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
canon tasks next-label --json | jq -r '.label'
|
|
32
|
+
```
|
|
33
|
+
|
|
8
34
|
## Archive
|
|
9
35
|
|
|
10
36
|
`canon tasks archive` moves a shipped task from `.canon/tasks/` into `.canon/tasks/archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
|
package/docs/target-projects.md
CHANGED
|
@@ -63,6 +63,8 @@ The chain is:
|
|
|
63
63
|
|
|
64
64
|
The chain stops at the project edge. `repo-metadata` and `git-commit` also ship, reaching a remote and the project's history respectively, and neither runs as part of it. The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `canon:canon-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
|
|
65
65
|
|
|
66
|
+
Run `canon:setup-smoke` by hand once `setup-verify` passes, for the heavier server smoke, end-to-end, and screenshot pass, since the same flakiness reasons that excluded those stages from `setup-verify` keep it out of this unattended chain too.
|
|
67
|
+
|
|
66
68
|
Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations: .claude/context/development.md -->
|
|
67
69
|
|
|
68
70
|
### From scaffold to first feature
|