@erclx/canon 4.3.0 → 4.4.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-orchestrate/references/orchestrator-dispatch.md +34 -9
- package/claude/skills/repo-metadata/REQUIREMENT.md +37 -0
- package/claude/skills/repo-metadata/SKILL.md +51 -0
- package/docs/agents/commands.md +64 -62
- package/docs/agents/sandbox.md +3 -1
- package/docs/agents/tasks.md +35 -0
- package/docs/operating-model.md +1 -1
- package/package.json +1 -1
- package/scripts/lib/sandbox-dispatch.sh +182 -0
- package/src/claude/cases/misc.ts +4 -0
- package/src/cli.ts +4 -0
- package/src/commands/repo.ts +393 -0
- package/src/commands/tasks.ts +100 -0
- package/src/paths.ts +16 -0
- package/src/repo/metadata.ts +206 -0
- package/src/tasks/answers.ts +195 -0
- package/src/tasks/archive.ts +2 -9
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Orchestrator dispatch runbook
|
|
3
|
-
description: The collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
|
|
3
|
+
description: The plan-answer gate, the collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The disjointness gate below is where that row's file set is tested against every track in flight.
|
|
@@ -11,6 +11,25 @@ Resolve `<slug>` from `<plan>`, the row's plan file, the way `claude-worktree` S
|
|
|
11
11
|
|
|
12
12
|
This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and a slug mismatch no longer fails the run downstream on its own, since `claude-autoship` now takes `<plan>` directly rather than resolving it from the worker's own branch. The check above is what has to catch a wrong candidate now.
|
|
13
13
|
|
|
14
|
+
## Check the plan waits on nobody
|
|
15
|
+
|
|
16
|
+
Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record.
|
|
17
|
+
|
|
18
|
+
- `launchable: true`: the plan answers itself, so proceed to the branch check.
|
|
19
|
+
- `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.
|
|
20
|
+
- `reason: archived`: the row's plan sits in `.claude/plans/archive/` and describes work that already shipped. Repoint the row at a live plan rather than dispatching, since `claude-autoship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
|
|
21
|
+
- 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.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
This gate runs ahead of the two collision checks because it is the cheapest reading of the three, needing no roster and no ref, and because it is the only one asking about the row itself rather than about what else is in flight. A row nobody can launch does not need testing against the tracks already out.
|
|
26
|
+
|
|
27
|
+
It also reads the plan rather than a cell describing one, which is the input the gate below it does not have. The disjointness gate compares the sets a dispatcher wrote into the constraints and the Touches column, so a cell omitting a file clears a check the tree would fail. That happened on 2026-08-31, when two rows were cleared against each other with one constraints block leaving out the context entry both were about to write, and what caught it was a worker sending a message rather than any check.
|
|
28
|
+
|
|
29
|
+
A blank `- Answer:` is not an unanswered question. `${CLAUDE_SKILL_DIR}/../../standards/plan.md` fixes an empty slot as accepting the `- Suggested:` line above it, which is what makes a plan decision-ready in one pass. The narrow case this reads is `- Suggested: needs your call, <why>` over an empty slot, the form that same standard writes where the answer turns on preference rather than on a technical default. A gate reading every blank slot as open would refuse every plan in the folder.
|
|
30
|
+
|
|
31
|
+
What it prevents is a halt nobody is watching for. `claude-worker` instructs a session to stop on a question written as needing the operator's call, correctly and by its own body, so a dispatch that never reads the plan lands a worker in a wait for a person who does not know it is waiting. The worker's halt is not the defect, and the dispatch that made it necessary is.
|
|
32
|
+
|
|
14
33
|
## Check the branch is unclaimed
|
|
15
34
|
|
|
16
35
|
Run `canon sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
|
|
@@ -43,7 +62,7 @@ The finding names which row contributed the containing path, and a bare-folder c
|
|
|
43
62
|
|
|
44
63
|
Disjointness is necessary and not sufficient, so hold a candidate whose sets do not touch when a stated reason serializes it, and write the reason on the hold. One row creating a skill and another auditing that catalog and counting it write nothing in common, measured 2026-08-27, and dispatching both still leaves the audit counting a denominator that moves underneath it. Nothing verifies that a reason was written, so the rule holds only while the dispatcher applies it.
|
|
45
64
|
|
|
46
|
-
What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session.
|
|
65
|
+
What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session. The one number this skill carries is the review fallback's count of three in `## Parallelism`, which moves a review rather than binding a track, and this runbook carries none.
|
|
47
66
|
|
|
48
67
|
## Pick the model
|
|
49
68
|
|
|
@@ -186,12 +205,16 @@ resolved off the row the way the build shape resolves one off a plan.
|
|
|
186
205
|
reads `planner-` for the reason the worker's reads `worker-`, which is that it
|
|
187
206
|
marks the role of the session it names rather than the one that launched it.
|
|
188
207
|
|
|
189
|
-
|
|
190
|
-
and the disjointness gate has nothing to compare, since a
|
|
191
|
-
no track in flight can hold.
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
208
|
+
None of the three checks above binds this shape. The branch check has no
|
|
209
|
+
candidate to read, and the disjointness gate has nothing to compare, since a
|
|
210
|
+
planner writes one file no track in flight can hold. The plan-answer gate
|
|
211
|
+
reaches no plan at all, because the planner is dispatched to write the file a
|
|
212
|
+
build would later read, so running it here would refuse every planning dispatch
|
|
213
|
+
over a plan nobody has written yet.
|
|
214
|
+
|
|
215
|
+
What a planning dispatch owes instead is the reverse reading, because the plan
|
|
216
|
+
it produces carries a constraint per track in flight and a row planned during a
|
|
217
|
+
wave is planned against a tree that wave is changing. `claude-planner` states that read as a command over open pull
|
|
195
218
|
requests, which is why the brief carries no branch list for it.
|
|
196
219
|
|
|
197
220
|
One row per dispatch. A session reused across a batch pays the context load once
|
|
@@ -202,7 +225,9 @@ session where the saving is worth it and say what the cap was.
|
|
|
202
225
|
|
|
203
226
|
## Fall back to the human
|
|
204
227
|
|
|
205
|
-
Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.
|
|
228
|
+
Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the plan still waits on the operator, the plan-answer read could not be taken, the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.
|
|
229
|
+
|
|
230
|
+
The first of those five is the one that reaches a person rather than the board. A row held for a collision or for a serialize reason waits on the wave clearing, where a row held on its plan waits on an answer only the operator can give, so hand that one over with the question label and its stated reason attached rather than as a name and a refusal.
|
|
206
231
|
|
|
207
232
|
## Stop the loop
|
|
208
233
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: repo-metadata
|
|
3
|
+
description: Why an About text nobody re-derives drifts from the README it summarizes, and why writing it stays a second, explicit step
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Repo metadata requirement
|
|
7
|
+
|
|
8
|
+
## Gap
|
|
9
|
+
|
|
10
|
+
Without this skill, a repository's GitHub About description, homepage, and topics are set once by hand and never checked again. Nothing in either skill corpus reads or writes them, so a README rewrite carries no signal back to the three fields a stranger reads before the README, and they drift silently. That already happened here: the About text disagreed with the README's own opening line, and nobody noticed until someone read both side by side.
|
|
11
|
+
|
|
12
|
+
A session that fixes this by hand skips the gate a repeatable proposal would have given it. It reads the README once, writes a description from memory, and never records what it compared against or gives anyone else a chance to see the diff before it goes out. The write is also public and immediate: `gh repo edit` changes what every visitor to the repository page sees, with no draft state and no second confirmation from GitHub itself.
|
|
13
|
+
|
|
14
|
+
## Must
|
|
15
|
+
|
|
16
|
+
- Compute the proposal from the tree alone, through `canon repo metadata propose`, and report the diff against the remote before any write is discussed
|
|
17
|
+
- Route the choice of which fields to write through the structured question surface, since which field to accept is the operator's preference to decide
|
|
18
|
+
- Run `canon repo metadata apply` only in a turn separate from the one that ran propose, carrying only the fields the operator answered in this conversation
|
|
19
|
+
|
|
20
|
+
## Must not
|
|
21
|
+
|
|
22
|
+
- Call apply in the same invocation that ran propose, whatever the operator's request already names
|
|
23
|
+
- Write a field the operator has not answered in this conversation, even when the CLI's own proposal suggested a value for it
|
|
24
|
+
- Read an absent field in the proposal as a suggestion to clear what the remote already carries
|
|
25
|
+
- Edit `README.md` or any repository setting other than description, homepage, and topics
|
|
26
|
+
- Fire from a request with no repository-metadata content, since a skill invoked on a vague signal risks presenting a write path the operator never asked for
|
|
27
|
+
|
|
28
|
+
## Guards
|
|
29
|
+
|
|
30
|
+
- No `gh` remote resolves. Stop, naming the refusal `canon repo metadata propose` reports, since a proposal with nothing to compare against is a suggestion nobody asked for.
|
|
31
|
+
- `canon repo metadata propose` or `apply` does not resolve on an older install. Report that rather than proceeding, since the fix without the verb reintroduces the hand-written write this skill exists to gate.
|
|
32
|
+
|
|
33
|
+
## Out of scope
|
|
34
|
+
|
|
35
|
+
- Editing the README's own content, which is a request against that file rather than against repository metadata
|
|
36
|
+
- Repository settings outside description, homepage, and topics, such as visibility or branch protection, which carry a different blast radius and no local source to propose from
|
|
37
|
+
- Any repeat run outside a target project's own tree, since the proposal is computed from that tree's README and manifest rather than from this toolkit's shape
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: repo-metadata
|
|
3
|
+
description: Proposes a GitHub About description, homepage, and topic set computed from the README's opening line and package.json, reports the difference against what the repository's remote already carries, and stops without writing. A later invocation, carrying the operator's answered fields, writes the change through gh repo edit. Use when asked to "propose repo metadata", "check the github description", "does our github about text match the readme", "sync github topics", "update the repo homepage", or "apply the repo metadata answers". Do NOT use to edit README.md itself, or to change a repository setting other than description, homepage, or topics.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Repo metadata
|
|
7
|
+
|
|
8
|
+
Reads what `canon repo metadata propose` computes locally and reports it against the remote. Writing is a separate step: `canon repo metadata apply` never runs in the same invocation that ran propose, whatever the operator answers in the same breath. The gate is the two invocations, not a prompt inside one.
|
|
9
|
+
|
|
10
|
+
## Guards
|
|
11
|
+
|
|
12
|
+
- Report it rather than proceeding silently when `canon repo metadata propose` or `canon repo metadata apply` does not resolve. Both ship with the CLI, so a project on an older install meets a missing subcommand rather than a refusal.
|
|
13
|
+
- The propose read refuses when the repository has no remote `gh` can read. Report that refusal verbatim and stop. A proposal with nothing to compare against is a suggestion nobody asked for.
|
|
14
|
+
- Never call apply in the same turn that ran propose, even when the operator's request already names the fields to write. Surface the proposal, get the answer, then run apply as its own step.
|
|
15
|
+
- Never write a field the operator did not confirm in this conversation. A field the proposal computed and the operator has not answered stays unwritten, whatever the CLI's own suggestion for it was.
|
|
16
|
+
- A field absent from the proposal has no local source and is never a suggestion to clear what the remote already carries. Report it as unchanged, not as a removal.
|
|
17
|
+
|
|
18
|
+
## Propose
|
|
19
|
+
|
|
20
|
+
1. Run `canon repo metadata propose --json`.
|
|
21
|
+
2. Read `diff` and `repo` from the record. `repo` is the `--repo` value the later apply step must carry. An empty `diff` means the remote already matches what this run computed: report that and stop, since there is nothing to answer.
|
|
22
|
+
3. For each field `diff` carries, put the change to the operator through the structured question surface: which of the differing fields to write. Rank accepting the proposed value first for a field whose current value is stale or wrong, and give the reject option the cost of leaving the remote as it stands. Never pre-select an answer for the operator.
|
|
23
|
+
4. Report the fields the proposal left absent as unchanged, naming that neither the README nor `package.json` carried a source for them.
|
|
24
|
+
5. Stop. Do not run apply here even when the operator answers immediately, since answering is not yet an apply invocation.
|
|
25
|
+
|
|
26
|
+
## Apply
|
|
27
|
+
|
|
28
|
+
1. Confirm every field about to be written was answered by the operator in this conversation. Carry no field forward unanswered.
|
|
29
|
+
2. Run `canon repo metadata apply`, always passing `--repo <owner/name>` from the propose record's `repo` field, plus the flags for the answered fields: `--description <text>`, `--homepage <url>`, `--topics <comma-separated list>`. `--topics` is the full desired set, and the command reads the current set itself to compute what to add and remove. The command refuses rather than writing when `--repo` does not match what `--root` resolves to, so never omit it and never guess it from anything but the propose record's `repo` field.
|
|
30
|
+
3. Report the written state from the JSON record.
|
|
31
|
+
|
|
32
|
+
## Output
|
|
33
|
+
|
|
34
|
+
Propose:
|
|
35
|
+
|
|
36
|
+
```plaintext
|
|
37
|
+
📋 Repo metadata proposal
|
|
38
|
+
description: "<current>" → "<proposed>"
|
|
39
|
+
homepage: unchanged, no local source
|
|
40
|
+
topics: +<added>, -<removed>
|
|
41
|
+
|
|
42
|
+
Answer which fields to write, then ask again to apply.
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Apply:
|
|
46
|
+
|
|
47
|
+
```plaintext
|
|
48
|
+
✅ Applied: <fields written>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Omit a line from the proposal block for a field `diff` did not carry.
|
package/docs/agents/commands.md
CHANGED
|
@@ -9,68 +9,70 @@ 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 docs [topic]`
|
|
24
|
-
| `canon design render`
|
|
25
|
-
| `canon slides render`
|
|
26
|
-
| `canon slides list`
|
|
27
|
-
| `canon feedback`
|
|
28
|
-
| `canon transcripts <url>`
|
|
29
|
-
| `canon tasks archive`
|
|
30
|
-
| `canon tasks pull-request`
|
|
31
|
-
| `canon tasks outcome`
|
|
32
|
-
| `canon tasks validate`
|
|
33
|
-
| `canon intake list`
|
|
34
|
-
| `canon intake answer`
|
|
35
|
-
| `canon teach list`
|
|
36
|
-
| `canon teach open`
|
|
37
|
-
| `canon teach resource`
|
|
38
|
-
| `canon teach glossary`
|
|
39
|
-
| `canon records validate`
|
|
40
|
-
| `canon records migrate`
|
|
41
|
-
| `canon records size`
|
|
42
|
-
| `canon records push`
|
|
43
|
-
| `canon records pull`
|
|
44
|
-
| `canon migrate rename`
|
|
45
|
-
| `canon sessions list`
|
|
46
|
-
| `canon worktrees list`
|
|
47
|
-
| `canon comments scan`
|
|
48
|
-
| `canon context audit`
|
|
49
|
-
| `canon markdown audit`
|
|
50
|
-
| `canon claude skills audit`
|
|
51
|
-
| `canon standards audit`
|
|
52
|
-
| `canon claude skills drift`
|
|
53
|
-
| `canon claude skills reach`
|
|
54
|
-
| `canon claude skills rank`
|
|
55
|
-
| `canon claude routing`
|
|
56
|
-
| `canon gov test-order`
|
|
57
|
-
| `canon gov superseded`
|
|
58
|
-
| `canon gov restated`
|
|
59
|
-
| `canon gov citations`
|
|
60
|
-
| `canon secrets scan`
|
|
61
|
-
| `canon deps audit`
|
|
62
|
-
| `canon labels audit`
|
|
63
|
-
| `canon labels scan`
|
|
64
|
-
| `canon autoship classify`
|
|
65
|
-
| `canon pr key-changes`
|
|
66
|
-
| `canon
|
|
67
|
-
| `canon
|
|
68
|
-
| `canon
|
|
69
|
-
| `canon
|
|
70
|
-
| `canon
|
|
71
|
-
| `canon
|
|
72
|
-
| `canon
|
|
73
|
-
| `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 docs [topic]` | Emit toolkit reference docs (`list`, or a topic by name) |
|
|
24
|
+
| `canon design render` | Render `.claude/DESIGN.md` tokens to HTML and CSS |
|
|
25
|
+
| `canon slides render` | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr |
|
|
26
|
+
| `canon slides list` | List the available slide layouts (`--json` for the catalog) |
|
|
27
|
+
| `canon feedback` | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github` |
|
|
28
|
+
| `canon transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`) |
|
|
29
|
+
| `canon tasks archive` | Move a shipped task off the board, clear its ordering row, and regenerate the index |
|
|
30
|
+
| `canon tasks pull-request` | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`) |
|
|
31
|
+
| `canon tasks outcome` | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`) |
|
|
32
|
+
| `canon tasks validate` | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`) |
|
|
33
|
+
| `canon intake list` | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`) |
|
|
34
|
+
| `canon intake answer` | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`) |
|
|
35
|
+
| `canon teach list` | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`) |
|
|
36
|
+
| `canon teach open` | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`) |
|
|
37
|
+
| `canon teach resource` | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`) |
|
|
38
|
+
| `canon teach glossary` | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`) |
|
|
39
|
+
| `canon records validate` | Report a session record or a standard against the standard governing it, per kind (`--json`) |
|
|
40
|
+
| `canon records migrate` | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`) |
|
|
41
|
+
| `canon records size` | Report what each record folder holds and how much of it is recent, heaviest first (`--json`) |
|
|
42
|
+
| `canon records push` | Commit the nine backed record folders and push them to a private records remote (`--json`) |
|
|
43
|
+
| `canon records pull` | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`) |
|
|
44
|
+
| `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`) |
|
|
45
|
+
| `canon sessions list` | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`) |
|
|
46
|
+
| `canon worktrees list` | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`) |
|
|
47
|
+
| `canon comments scan` | Measure comment density by language and comment kind, with a trend recomputed from git |
|
|
48
|
+
| `canon context audit` | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
|
|
49
|
+
| `canon markdown audit` | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints |
|
|
50
|
+
| `canon claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md` |
|
|
51
|
+
| `canon standards audit` | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`) |
|
|
52
|
+
| `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`) |
|
|
53
|
+
| `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 |
|
|
54
|
+
| `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>`) |
|
|
55
|
+
| `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`) |
|
|
56
|
+
| `canon gov test-order` | Report where an implementation reached history ahead of the test covering it (`--json`) |
|
|
57
|
+
| `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`) |
|
|
58
|
+
| `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`) |
|
|
59
|
+
| `canon gov citations` | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`) |
|
|
60
|
+
| `canon secrets scan` | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`) |
|
|
61
|
+
| `canon deps audit` | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
|
|
62
|
+
| `canon labels audit` | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`) |
|
|
63
|
+
| `canon labels scan` | Fail a pull request whose title or body carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--json`) |
|
|
64
|
+
| `canon autoship classify` | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`) |
|
|
65
|
+
| `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`) |
|
|
66
|
+
| `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`) |
|
|
67
|
+
| `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`) |
|
|
68
|
+
| `canon census [path]` | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`) |
|
|
69
|
+
| `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`) |
|
|
70
|
+
| `canon audits list` | List every audit the set runs, with the corpus each reads and whether it gates (`--json`) |
|
|
71
|
+
| `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`) |
|
|
72
|
+
| `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`) |
|
|
73
|
+
| `canon capture [source]` | Render HTML capture sources to PNG, toolkit-only and absent from an installed package |
|
|
74
|
+
| `canon serve [dir]` | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`) |
|
|
75
|
+
| `canon upgrade` | Reinstall the CLI globally with the package manager the install path names (`--json`) |
|
|
74
76
|
|
|
75
77
|
`canon serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and 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. 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.
|
|
76
78
|
|
package/docs/agents/sandbox.md
CHANGED
|
@@ -68,4 +68,6 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
|
|
|
68
68
|
|
|
69
69
|
`exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
|
|
70
70
|
|
|
71
|
-
`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
|
|
71
|
+
`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
|
|
72
|
+
|
|
73
|
+
Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
|
package/docs/agents/tasks.md
CHANGED
|
@@ -63,6 +63,41 @@ A `live` location with an empty `citedBy` is the sweep to run. One whose `citedB
|
|
|
63
63
|
canon tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
+
## Plan answers
|
|
67
|
+
|
|
68
|
+
`canon tasks plan-answers <plan>` answers whether a plan is launchable, which is whether it still waits on the operator for a call only they can make. It reports and never writes.
|
|
69
|
+
|
|
70
|
+
Name the plan by its path or by its slug, which resolve to the same file:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
canon tasks plan-answers dispatch-answer-gate
|
|
74
|
+
canon tasks plan-answers .claude/plans/feature-dispatch-answer-gate.md
|
|
75
|
+
canon tasks plan-answers ../plans/feature-dispatch-answer-gate.md
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
A relative path resolves against the project root first and against `.claude/tasks/` second. The third form above is what a board row writes, since its link is relative to the board, and a dispatcher copying the reference out of the row it is dispatching has that spelling to hand rather than either of the other two. A refusal names every base it looked under.
|
|
79
|
+
|
|
80
|
+
`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 `.claude/plans/archive/` returns `archived` rather than a launchable reading, since it answers every question and describes work that already shipped.
|
|
81
|
+
|
|
82
|
+
| Option | Effect |
|
|
83
|
+
| --------------- | ------------------------------------------- |
|
|
84
|
+
| `--json` | Emit a machine-readable record on stdout |
|
|
85
|
+
| `--root <path>` | Board root, defaulting to the main worktree |
|
|
86
|
+
|
|
87
|
+
The record carries `launchable` and `open`, the questions still waiting, each with the `label` that names it and the `why` its suggestion gave for needing a person. Exit codes: `0` launchable, `1` refused with `no-plan`, `archived`, or `bad-input`, `2` waiting on the operator.
|
|
88
|
+
|
|
89
|
+
A blank `- Answer:` is not a waiting question. The plan standard fixes an empty slot as accepting the `- Suggested:` line above it, so the one shape this reads is `- Suggested: needs your call, <why>` over an empty slot, which is what that standard writes where the answer turns on preference rather than on a technical default. A verb reading every blank slot as open would report every plan in the folder.
|
|
90
|
+
|
|
91
|
+
The question block is read through the same parser `canon tasks validate` runs, so the gate and the conformance check cannot drift into disagreeing about what a question is. A question carrying no suggestion at all is that check's finding rather than this one's, and it goes unread here.
|
|
92
|
+
|
|
93
|
+
Branch on `launchable` rather than on the exit code, for the reason the section above states: a shell profile wrapping `canon` in a function can take a later command's status and mask every non-zero exit, which reads a waiting plan as a launchable one.
|
|
94
|
+
|
|
95
|
+
The orchestrator dispatch runbook calls this before it checks the branch or the file sets, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'
|
|
99
|
+
```
|
|
100
|
+
|
|
66
101
|
## Pull request
|
|
67
102
|
|
|
68
103
|
`canon tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.
|
package/docs/operating-model.md
CHANGED
|
@@ -70,7 +70,7 @@ and no later session recovers that vantage.
|
|
|
70
70
|
One feature travels this path end to end.
|
|
71
71
|
|
|
72
72
|
1. The next feature is planned with `claude-feature`, writing a plan to `.claude/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
|
|
73
|
-
2. Orchestrator checks the branch is unclaimed and the plan's file set is disjoint from every track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the sets overlap, or a stated reason serializes the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
|
|
73
|
+
2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks the plan's file set is disjoint from every track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the plan still waits on an answer only the operator can give, the check refuses, the sets overlap, or a stated reason serializes the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
|
|
74
74
|
3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
|
|
75
75
|
4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `canon sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
|
|
76
76
|
5. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. A pass finding nothing where a close-out already stands rewrites that comment to cover what it read rather than posting a second one, so the thread carries one live verdict. Repeat from step 4 until a pass closes the review.
|
package/package.json
CHANGED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
|
|
3
|
+
# The bound on a nested background dispatch, and the recording behind it.
|
|
4
|
+
#
|
|
5
|
+
# An arm invoked without the narration its fixture states dispatched a real
|
|
6
|
+
# `claude --bg` session against the machine's own process table, and nothing in
|
|
7
|
+
# the harness noticed. `snapshot_tree` reads the sandbox and `snapshot_root`
|
|
8
|
+
# reads four scratch directories, and a dispatched session writes into none of
|
|
9
|
+
# them, so the escape watch reported clean throughout and was right to. The run
|
|
10
|
+
# spent real cost until a person found it, and `SIGTERM` alone did not end it.
|
|
11
|
+
#
|
|
12
|
+
# Three mechanisms sit here rather than in `scripts/sandbox/run.sh`, which is the
|
|
13
|
+
# only caller. Each is reachable from a test that never launches a session:
|
|
14
|
+
# `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
|
|
15
|
+
# reap against a `sleep`, where proving either through `run.sh` would mean
|
|
16
|
+
# spawning the thing the bound exists to prevent.
|
|
17
|
+
|
|
18
|
+
# The prevention. Writes a `claude` that refuses a background dispatch by flag
|
|
19
|
+
# name and delegates everything else, for `run.sh` to place first on the PATH of
|
|
20
|
+
# the session it spawns.
|
|
21
|
+
#
|
|
22
|
+
# The real binary is baked into the file rather than passed through the
|
|
23
|
+
# environment. An env var carrying it would sit in the spawned session's own
|
|
24
|
+
# environment, which hands any arm the exact string that walks around the shim.
|
|
25
|
+
#
|
|
26
|
+
# It names itself in its refusal. No arm shells to `claude` today, and one
|
|
27
|
+
# written tomorrow would meet this and read it as the harness being broken
|
|
28
|
+
# unless the text says which layer refused and why.
|
|
29
|
+
#
|
|
30
|
+
# It is not the whole bound. A dispatch reaching the binary by an absolute path
|
|
31
|
+
# never resolves through PATH at all, which is what `reap_process_group`
|
|
32
|
+
# backstops.
|
|
33
|
+
install_dispatch_shim() {
|
|
34
|
+
local dir="$1"
|
|
35
|
+
local real="$2"
|
|
36
|
+
|
|
37
|
+
cat >"$dir/claude" <<SHIM
|
|
38
|
+
#!/usr/bin/env bash
|
|
39
|
+
# Generated by install_dispatch_shim in scripts/lib/sandbox-dispatch.sh.
|
|
40
|
+
for arg in "\$@"; do
|
|
41
|
+
case "\$arg" in
|
|
42
|
+
--bg | --background)
|
|
43
|
+
echo "canon sandbox harness: refusing \$arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2
|
|
44
|
+
exit 64
|
|
45
|
+
;;
|
|
46
|
+
esac
|
|
47
|
+
done
|
|
48
|
+
exec "$real" "\$@"
|
|
49
|
+
SHIM
|
|
50
|
+
|
|
51
|
+
chmod +x "$dir/claude"
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
# True while any process still carries this group id. Reads the whole table
|
|
55
|
+
# rather than `ps -g`, which selects by session on some builds and reports an
|
|
56
|
+
# empty group as a clean exit either way.
|
|
57
|
+
process_group_alive() {
|
|
58
|
+
ps -eo pgid= 2>/dev/null | tr -d ' ' | grep -qx "$1"
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
# The backstop. Signals a process group `run.sh` created, escalating rather than
|
|
62
|
+
# sending one signal and reporting success, since the dispatch that produced this
|
|
63
|
+
# row took two signals to reap.
|
|
64
|
+
#
|
|
65
|
+
# Prints its outcome and always exits zero. Every caller runs under `set -e`, and
|
|
66
|
+
# a survivor is something to report rather than a reason to abandon the verdict
|
|
67
|
+
# the run already took.
|
|
68
|
+
#
|
|
69
|
+
# The group has to be one the run created, and the refusal below is what makes
|
|
70
|
+
# that property travel with the function rather than living in one caller.
|
|
71
|
+
# `run.sh` reads the harness group once and reports `inherited` when the session
|
|
72
|
+
# failed to lead a group of its own, which is a diagnosis; this is the floor
|
|
73
|
+
# under it, and under every caller after it, because the cost of getting the
|
|
74
|
+
# argument wrong is the operator's own shell.
|
|
75
|
+
#
|
|
76
|
+
# What it cannot reach is a dispatch that called `setsid` on its way out, which
|
|
77
|
+
# leaves the group before this reads it. That is the half the shim covers.
|
|
78
|
+
reap_process_group() {
|
|
79
|
+
local pgid="$1"
|
|
80
|
+
|
|
81
|
+
if [ "$pgid" = "$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')" ]; then
|
|
82
|
+
printf 'refused-own-group\n'
|
|
83
|
+
return 0
|
|
84
|
+
fi
|
|
85
|
+
|
|
86
|
+
if ! process_group_alive "$pgid"; then
|
|
87
|
+
printf 'clear\n'
|
|
88
|
+
return 0
|
|
89
|
+
fi
|
|
90
|
+
|
|
91
|
+
kill -TERM -"$pgid" 2>/dev/null || true
|
|
92
|
+
wait_for_group_exit "$pgid"
|
|
93
|
+
|
|
94
|
+
if ! process_group_alive "$pgid"; then
|
|
95
|
+
printf 'reaped-term\n'
|
|
96
|
+
return 0
|
|
97
|
+
fi
|
|
98
|
+
|
|
99
|
+
kill -KILL -"$pgid" 2>/dev/null || true
|
|
100
|
+
wait_for_group_exit "$pgid"
|
|
101
|
+
|
|
102
|
+
if process_group_alive "$pgid"; then
|
|
103
|
+
printf 'survived\n'
|
|
104
|
+
else
|
|
105
|
+
printf 'reaped-kill\n'
|
|
106
|
+
fi
|
|
107
|
+
return 0
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
# Five seconds per signal. A shorter window reports a survivor for a process
|
|
111
|
+
# that was already exiting, and a longer one stalls a run whose verdict is
|
|
112
|
+
# already taken.
|
|
113
|
+
wait_for_group_exit() {
|
|
114
|
+
local pgid="$1"
|
|
115
|
+
local waited=0
|
|
116
|
+
|
|
117
|
+
while [ "$waited" -lt 20 ] && process_group_alive "$pgid"; do
|
|
118
|
+
sleep 0.25
|
|
119
|
+
waited=$((waited + 1))
|
|
120
|
+
done
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
# The client's own session registry, which is the only surface a nested dispatch
|
|
124
|
+
# leaves a trace on that this harness can read. It is client-owned and carries no
|
|
125
|
+
# contract, so a client that stops writing a record per session breaks the
|
|
126
|
+
# detection silently. That is why what reads it reports rather than asserts.
|
|
127
|
+
sessions_dir() {
|
|
128
|
+
printf '%s/sessions\n' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
# Set whenever the registry directory existed at snapshot time. An absent
|
|
132
|
+
# registry produces the same empty manifest a quiet run does, and the two mean
|
|
133
|
+
# opposite things, so the report carries this rather than letting an unwatched
|
|
134
|
+
# run read as a clean one. Same distinction `escape_watched` draws in `run.sh`,
|
|
135
|
+
# which is also the only reader, hence the exemption on the write below.
|
|
136
|
+
sessions_watched=0
|
|
137
|
+
|
|
138
|
+
# Record names only, never hashes. A live session rewrites its own record on
|
|
139
|
+
# every status change, so a content manifest would name every session running
|
|
140
|
+
# beside this one, which is the noise the escape watch was already narrowed to
|
|
141
|
+
# avoid. A record that appears between the two snapshots is a session that
|
|
142
|
+
# started during the run, and that is the whole question.
|
|
143
|
+
snapshot_sessions() {
|
|
144
|
+
local manifest="$1"
|
|
145
|
+
local dir
|
|
146
|
+
dir="$(sessions_dir)"
|
|
147
|
+
|
|
148
|
+
: >"$manifest"
|
|
149
|
+
[ -d "$dir" ] || return 0
|
|
150
|
+
# shellcheck disable=SC2034
|
|
151
|
+
sessions_watched=1
|
|
152
|
+
|
|
153
|
+
find "$dir" -maxdepth 1 -type f -name '*.json' 2>/dev/null |
|
|
154
|
+
sed 's|.*/||' | sort >"$manifest"
|
|
155
|
+
return 0
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
# The new side alone, unlike `writes_between`. A record that vanished is a
|
|
159
|
+
# session that ended and a record that changed is one that was already running,
|
|
160
|
+
# and neither is a dispatch this run made.
|
|
161
|
+
sessions_between() {
|
|
162
|
+
comm -13 "$1" "$2"
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
# Turns a record name into a line a person can act on. The file can be gone by
|
|
166
|
+
# the time this reads it, since a session that started and exited inside the run
|
|
167
|
+
# takes its record with it, so an unreadable record still reports its name rather
|
|
168
|
+
# than dropping out of the list.
|
|
169
|
+
#
|
|
170
|
+
# One record is one line. The name is written by whatever peer claimed the
|
|
171
|
+
# session, so a newline inside it would split one record across two entries in a
|
|
172
|
+
# list every reader takes as one line each.
|
|
173
|
+
describe_session() {
|
|
174
|
+
local record desc
|
|
175
|
+
record="$(sessions_dir)/$1"
|
|
176
|
+
|
|
177
|
+
desc="$(jq -r '"\(.name // "unnamed") in \(.cwd // "an unrecorded directory")"
|
|
178
|
+
| gsub("\\s+"; " ")' "$record" 2>/dev/null || true)"
|
|
179
|
+
[ -z "$desc" ] && desc="record already gone"
|
|
180
|
+
|
|
181
|
+
printf '%s: %s\n' "$1" "$desc"
|
|
182
|
+
}
|