@erclx/canon 4.0.0

package/claude/skills/claude-review/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: claude-review
+description: Reviews all changes since main for bugs, edge cases, and logic flaws. Reads CLAUDE.md, REQUIREMENTS.md, and ARCHITECTURE.md for context, then applies a structured review to the full diff and outputs a findings report. Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Use when asked to review changes, run a code review, or check the current branch. Do NOT auto-trigger on vague signals like "looks good" or "can you check this". Require an explicit review request or an autoship invocation.
+---
+
+# Claude review
+
+## Guards
+
+- Resolve the base ref first, per Diff baseline below. If the staged set, the branch set, and the working set are all empty, stop: `✅ No changes to review.` A guard reading bare local `main` stops the skill on `main` before it ever reaches Step 2.
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in the guard and in Step 2:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill reports a clean branch rather than admitting it cannot see the work.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while the staged set and `git diff HEAD` still report work at correct scope. Review those and lead the report with `⚠ Baseline unusable. Reviewed the uncommitted set only.`, so a clean summary is never read as a clean branch.
+
+## Step 1: read context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: project type, conventions, and commands
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- `.claude/ARCHITECTURE.md`: technical design decisions
+
+Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Always-on rules apply every session. Path-scoped rules apply to files matching their `paths:` glob.
+
+## Step 2: get the diff and changed files
+
+Resolve the base ref per Diff baseline above, then run these in parallel from the project root:
+
+```bash
+git diff --staged
+```
+
+```bash
+git diff --staged --name-only
+```
+
+```bash
+git diff <base> HEAD
+```
+
+```bash
+git diff <base> HEAD --name-only
+```
+
+If `git diff --staged` is non-empty, use it as the diff scope and use the `--staged --name-only` list as the file list. Otherwise use `git diff <base> HEAD` and its name-only list.
+
+When the baseline is unusable, substitute `git diff HEAD` and `git diff HEAD --name-only` for the branch pair. Never substitute the whole tree for a missing baseline.
+
+## Step 3: read changed files
+
+Read each file from the changed file list. Skip deleted files. Run reads in parallel.
+
+## Step 4: review and persist
+
+Review the full diff and changed file contents for:
+
+1. Bugs and edge cases
+2. Error handling gaps
+3. Logic flaws that will cause problems when the code is extended
+4. Security issues relevant to the project context
+5. Violations of rules from `.claude/rules/` that apply to the changed files
+
+Use `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`, and the auto-loaded `.claude/rules/` as project context to inform what is intentional vs problematic. Do not fix, rewrite, or suggest refactors outside the scope of a finding.
+
+### High-signal filter
+
+Flag only issues that will definitely cause incorrect behavior or break a documented rule. Skip:
+
+- Code style or quality concerns
+- Subjective suggestions
+- Linter territory
+- Issues that depend on unverified state
+
+A comment that makes a false claim about the code is a correctness finding, not a style one. Flag it past the exclusions above and let the severity ladder rank it.
+
+If uncertain, do not flag. False positives erode trust.
+
+### Severity
+
+- **critical**: blocks the feature. Broken in production if shipped.
+- **should-fix**: fix in same session while context is fresh. Not a blocker.
+- **minor**: not worth fixing now. Include for visibility.
+
+### Report format
+
+Start with a summary line. Group findings by file. Within each file, list findings sorted by severity (critical first, then should-fix, then minor). Omit files with no findings.
+
+```markdown
+X critical, Y should-fix, Z minor across N files.
+
+File: path/to/file.ext
+
+- **critical**: finding
+- **should-fix**: finding
+- **minor**: finding
+
+File: path/to/other.ext
+
+- **critical**: finding
+- **minor**: finding
+```
+
+If nothing is wrong, use: `✅ No findings.`
+
+### Persist
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+Write the full report directly to `.claude/review/branch/review-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the report goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+If there are no findings, write `✅ No findings.` to the file with a timestamp.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+The report is disposable. It outlives the ship chain that reads it, and `claude-docs` sweeps it once the branch it names is gone, because the durable record of what a review found is the comment `claude-pr-review` posts on the pull request. A review run on a branch that never opens one leaves nothing behind once that branch is gone, so fold anything worth keeping into the pull request body or a task finding while the report is still on disk.
+
+### Chat output
+
+Output only the summary line and the file path. Do not repeat the full report in chat.
+
+```plaintext
+X critical, Y should-fix, Z minor across N files.
+📝 Wrote .claude/review/branch/review-<slug>.md
+```
+
+If no findings: `✅ No findings. Wrote .claude/review/branch/review-<slug>.md`

package/claude/skills/claude-seed-sync/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: claude-seed-sync
+description: Scope boundary for section-granular seed reconciliation against the bulk install and sync commands
+---
+
+# Claude seed sync requirement
+
+## Gap
+
+Without this skill, a project that edited a seed has no way to take an upstream change without losing something. No `canon` command touches a seed at all, so the only route is a hand copy that overwrites the file and takes the edits with it, unrecorded. Nothing can deliver one upstream section into a file the project has customized, which is the case a grown project is always in.
+
+A whole-file diff does not close it either. It cannot separate a section the user rewrote on purpose from a section the toolkit moved on without them, so the choice reaches the user as accept everything or lose everything, and the safe answer is always to skip.
+
+Naming the bulk command carries a failure of its own. This skill decides which files the bulk sync should take and then hands that command over without stating what it does to them, and the boundary line below names the reference holding that answer where no session reads it. Claude Code loads the skill entry alone, so a sibling named here reaches nobody.
+
+Two failures belong to the audit rather than to the diff. A decision taken in chat dies with the session, so an audit half applied cannot be resumed and the second run starts over. And a file the toolkit generates rather than ships, such as an index rebuilt from sibling frontmatter, is absent from every source catalog by design, so a naive comparison reports it as a local addition and invites the user to reconcile something nothing owns.
+
+## Must
+
+- Read seed content from the CLI rather than holding a copy, so the audit and the install cannot disagree
+- Diff per section, treating the preamble as a section of its own
+- Separate a customized section from a stale one by reading the attribution the drift report records, not by how the section looks, and default the customized one to no action
+- Fall back to appearance only when attribution is unavailable, and mark every verdict reached that way as unverified
+- Leave a file the report proves untouched to the bulk sync that owns it, rather than auditing what carries no edits
+- Route to the overwrite contract from the body, at the point the bulk command is named, since the boundary below is read by an author and never by a session
+- Persist the proposal and every decision to a review file that stays the source of truth across re-pings
+- Apply one section at a time, never by rewriting a file
+
+## Must not
+
+- Propose removing a section present only in the target. Those are the customizations the skill exists to preserve.
+- Write a target file before a decision is recorded against the item
+- Read an empty decision slot as consent
+
+## Guards
+
+- No `canon` on PATH, or no `.claude/` directory at the project root, stops before any read
+
+## Out of scope
+
+- Bulk install and sync of a whole domain, which `canon <domain> install` and `canon <domain> sync` own and `canon-cli` documents. Reach for this skill when the target holds edits worth keeping, and for those commands when it does not.
+- Golden configs, which overwrite by design and carry no section structure to diff
+- Governance rules: `canon gov sync`
+- First-time scaffold of a project that has installed nothing yet: `setup-init`
+- Public `README.md` and `docs/` prose: `docs-sync`

package/claude/skills/claude-seed-sync/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: claude-seed-sync
+description: Audits a project's installed Claude seed docs against the toolkit's current seed source and proposes per-section edits without overwriting customizations. Use when asked to "sync seeds", "update my seeds", "check seed drift", "did the toolkit seeds change", or when reconciling `CLAUDE.md` and `.claude/` preambles after an upstream toolkit update.
+---
+
+# Claude seed sync
+
+Surfaces drift between the toolkit's current seed docs and what was installed in this project, then proposes targeted edits. The CLI emits seed content. This skill diffs, reasons, and writes the proposal to a review file. It does not write target files until the user confirms.
+
+## Guards
+
+- If the `canon` CLI is not on PATH, stop: `❌ canon CLI not found. Install the toolkit first.`
+- If no `.claude/` directory exists at the project root, stop: `❌ No .claude/ directory found. Run canon claude init first.`
+
+## Step 1: read toolkit sources and the drift report
+
+Run both in parallel from the project root:
+
+```bash
+canon claude seeds list --json 2>/dev/null
+canon sync --check . --json 2>/dev/null
+```
+
+Seeds emit an array of `{name, source, target, content}`, where `target` is the path relative to the project root where the file installs.
+
+Seeds are the whole subject. No standard installs into a project, so there is no installed copy to audit and nothing to reconcile against the corpus. A standard a session needs is read with `canon standards <name>`, which resolves against the copy inside the package.
+
+### Narrow the set by attribution
+
+The report is what separates a file the project edited from one the toolkit moved on without it. Read `seeds.entries` for seed paths.
+
+Keep every seed regardless of state. `CLAUDE.md` is the file a project edits most, and its `drifted` verdict is the case this skill exists for.
+
+Read the `canon-cli` skill before naming a sync command in the output. It states which surfaces a sync overwrites, merges, or writes once.
+
+Fall back to the appearance heuristic in step 3 when the report cannot attribute, which is `historyUnavailable` set on the relevant section or the command failing outright. Say so in the summary block, because a fallback audit reports guesses rather than facts.
+
+## Step 2: read installed copies
+
+For each entry in the merged list, read the file at its `target` path from the project root. Run reads in parallel.
+
+Mark missing files for **Add** treatment. Skip non-text seeds (`.json`) for section diffing. Record a one-line note in the scope table that the user can compare manually.
+
+When detecting target-only files for `local-only` flagging, skip files the toolkit's own walkers regenerate from sibling frontmatter (today: any `index.md` produced by `canon indexes regen`). They are absent from source catalogs by design, so flagging them as `local-only` is a false positive.
+
+Note on `settings.json`: the seed now ships only the PostToolUse hook block. If a target project's `.claude/settings.json` carries `attribution` or `permissions` keys, those are stale: the user-level `~/.claude/settings.json` (installed via `canon claude setup`) owns them now. Flag those keys in the scope table for removal rather than diffing them as content drift.
+
+## Step 3: diff per section
+
+For each seed file present in both sides, parse the body into a preamble (everything between H1 and the first H2) plus one part per `##` header, then compare part by part. Treat the preamble as a single unit with the same verdicts as a section. Use `(preamble)` as its label in the proposal.
+
+- **Identical:** ignore.
+- **Toolkit-only section** (present in source, absent in target): candidate to **Add**. Number it whatever the file's own verdict is. The verdict rules below govern a section present in both, and a section the project never had cannot be the customization a `drifted` file is being credited with. A pass that reads the file-level verdict first proposes nothing on a target missing eleven sections, which is the shape this bullet exists to catch.
+  - A deliberate removal reads the same as one that never arrived, and no decline is carried between runs, so a section the user skips is proposed again on the next branch. Say so beside the item rather than letting a reader meet it a third time wondering. The way to settle it for good is to keep the heading and write the project's own content under it, which moves the section onto the drifted path below, where the customization rule protects it and stops numbering it.
+- **Target-only section** (present in target, absent in source): preserve, never propose removal. These are user customizations.
+- **Drifted section** (present in both, content differs): candidate to **Update**.
+  - Read the file's verdict from the report rather than judging it by eye. `drifted` means the content matches no version the toolkit ever published, so the project wrote it: call it **Customized**, default to skip, record in the scope table only, never numbered.
+  - `stale` at the file level means the toolkit moved and the project did not, so any section differing inside it is **Stale**. Default action: propose update.
+  - Only when the report could not attribute the file, judge by appearance: a version carrying extra bullets, project-specific paths, or filled-in placeholders reads as **Customized**, and one reading like the original toolkit text reads as **Stale**. Mark every verdict reached this way as unverified in the proposal.
+
+The user judges intent. The skill makes the judgment legible.
+
+### Absorbed-already check
+
+Before proposing an Update, grep the target section for the seed text's keywords. If the rule is already implied by an adjacent bullet in the target version, drop the proposal and record the section as `in sync` in the scope table.
+
+## Step 4: write the proposal to the review file
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+Write the full proposal to `.claude/review/seed-audit-<slug>.md` at the main worktree root. Do not print the proposal inline.
+
+From a linked worktree the file-editing tools refuse that path, so the proposal goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+Structure: a summary block at the top, a legend, a scope table, then one H2 per numbered item. Number items across all files so the user can reference them by number. Fuse the status, action, and target into each H2. Every item starts as 📝 pending.
+
+````markdown
+# Seed audit: <slug>
+
+**Pending:** <all numbers>
+
+Legend: ✅ applied · ⏭ skipped · 📝 pending
+
+How to respond: fill in `Decision:` per item (`apply` or `skip`), then ping. Chat shortcut: `all`, `none`, or a list of numbers.
+
+## Scope
+
+Mark target-only files (present in target, absent in source) as `local-only` and leave them untouched.
+
+| Source | File       | Status     | Note                         |
+| ------ | ---------- | ---------- | ---------------------------- |
+| seed   | `<target>` | diffed     | <counts>                     |
+| seed   | `<target>` | in sync    |                              |
+| seed   | `<target>` | skipped    | non-text, compare manually   |
+| seed   | `<target>` | customized | <section> skipped by default |
+| seed   | `<target>` | local-only | not in toolkit, preserved    |
+
+## 1. 📝 Update → `<target-path>` / <section>
+
+Why: <one-line reason>
+
+``​`diff
+
+- <project line removed>
+  <unchanged context line>
+
+* <seed line added>
+  ​```
+
+Decision:
+
+## 2. 📝 Add → `<target-path>` / <section>
+
+Why: <one-line reason>
+
+``​`diff
+
+- <seed section body, each line prefixed with +>
+  ​```
+
+Decision:
+````
+
+Update items show both sides in one `diff` block: removed lines from the project version with `-`, added lines from the seed version with `+`, unchanged context lines without a prefix. Add items show only `+` lines. Customized sections appear in the scope table only, never numbered. A file with no drift still appears in the scope table as `in sync`.
+
+After writing, tell the user `✅ Wrote proposal to .claude/review/seed-audit-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping or use the chat shortcut.
+
+Rewrite the review file in place whenever the proposal changes mid-review. The file stays the source of truth for the current decisions.
+
+## Step 5: apply
+
+Re-read the review file as source of truth. For each item, parse `Decision:`:
+
+- `apply` (or affirmative): run the `Edit`, flip emoji to ✅.
+- `skip`: leave the target section as-is, flip emoji to ⏭.
+- `defer` or empty: leave 📝 pending, no action.
+- Contains `?` or unrecognized verb: leave 📝 pending, no action.
+
+Chat shortcut: the user replies with `all`, `none`, a comma-separated list of numbers, or `skip <nums>`. Write the matching verb into the `Decision:` slot of every item the reply names, `apply` for `all` or a bare list and `skip` for a `skip` reply, then run the parse above against the file. A reply of `none` writes nothing. A slot the reply does not name keeps its own value, so the receipt stays the source of truth and an empty slot still means take no action.
+
+Apply edits one at a time via `Edit`, replacing one section at a time. Never rewrite a whole file. Claude Code's tool permission dialog is the confirmation gate per edit.
+
+As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied or ⏭ for skipped. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until the next `claude-seed-sync` run overwrites it or the user clears it.
+
+## After completion
+
+Output one line per action taken:
+
+- `✅ Updated: <target-path> / <section>`
+- `⏭ Skipped: <target-path> / <section>`
+
+End with a one-line bucket summary: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Omit empty buckets. If anything is pending, remind the user they can fill in a `Decision:` and re-ping, or commit a skip with `skip <nums>` in chat.
+
+If the user accepted nothing, output:
+
+`✅ No changes applied.`

package/claude/skills/claude-standards-audit/REQUIREMENT.md

@@ -0,0 +1,33 @@
+---
+name: claude-standards-audit
+description: What the standards audit is for, the gaps it closes, and the fixing it deliberately refuses
+---
+
+# Claude standards audit requirement
+
+## Gap
+
+Without this skill, markdown ships unchecked against the authoring standards it was written under. A session fresh from writing prose does not reopen the standard it was meant to follow, banned punctuation survives because it reads fine, and the mapping from a file to the standards governing it gets re-derived by guess on every pass.
+
+## Must
+
+- Scope the audit to markdown the project hand-authors, so a generated file is not reported against a standard nobody applies to it
+- Decide which standards govern each changed file, rather than auditing every file against every standard
+- Grep for the violations a standard makes mechanically detectable, because reading alone misses occurrences
+- Report each finding with a file and a line, grouped so one file is one fix pass
+
+## Must not
+
+- Fix a violation, or propose the fix inline. The cheap swap satisfies the grep and breaks the rule the grep was standing in for.
+- Enumerate specific rules or tokens from a standard. The standard is the list, and a copy of it here drifts the moment the standard changes.
+
+## Guards
+
+- No markdown changed since main: stop with a pass, not an error
+- No installed standards to audit against: stop and say where they come from
+
+## Out of scope
+
+- Code style and structure, which `.claude/rules/` governs and Claude Code loads directly
+- Whether a standard is itself correct. A finding against the corpus is an argument to change the standard, and that is a standards edit rather than an audit result.
+- Persisting a report. The diff is the living state and the audit is a check against it at a moment.

package/claude/skills/claude-standards-audit/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: claude-standards-audit
+description: Audits changed markdown files against every authoring standard that declares jurisdiction over their paths and reports violations without fixing. Reads the standards catalog to map each file, greps for banned tokens, and groups findings by file. Use when asked to "audit prose", "audit standards", "check standards", "standards audit", or after editing markdown where standards compliance matters. Do NOT fix violations. Reporting only.
+---
+
+# Claude standards audit
+
+## Guards
+
+- Resolve the base ref first, per Diff baseline below, then scope the file list exactly as Step 1 does, fallback included. If no markdown files changed, stop: `✅ No markdown changes to audit.` A guard that reads bare local `main`, or that skips the unusable-baseline fallback, passes the skill clean on a branch it never read.
+- If `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` is not present, stop: `❌ markdown.md standard not found. Reinstall the canon plugin.` Test the file rather than the directory, since a plugin cache built before a given file existed keeps the directory without ever receiving that file.
+- `markdown.md` is the one standard testable before the mapping runs, since its scope statement declares an attribute and every changed markdown file therefore maps to it. Every other standard is tested in Step 3, where the mapping has named which ones the run needs.
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in the guard and in Step 1:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the audit passes clean rather than admitting it cannot see the files.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. Audit `git diff HEAD --name-only` instead and lead the report with `⚠ Baseline unusable. Audited the uncommitted set only.`, so a clean result is never read as a clean branch.
+
+## Step 1: scope the audit
+
+Get the changed file list, substituting `git diff HEAD --name-only` when the baseline is unusable:
+
+```bash
+git diff <base> HEAD --name-only
+```
+
+Filter to markdown (`.md`), then drop what the project does not hand-author:
+
+- `index.md`, unless its frontmatter carries `auto: false`
+- Any file in a gitignored directory
+- Any file sitting in a skill's bundled reference folder whose frontmatter names the consumers a generator copied it out to
+
+The last rule keeps a fan-out from multiplying one edit into a finding per copy. The source is the file to audit and the only one an author can fix, because the next regen overwrites every copy.
+
+It takes both halves. A generator copies frontmatter verbatim, so the field alone matches the source as well and drops the one file the rule means to keep. The location alone matches a reference the skill author wrote by hand, which carries no such field and is governed like the rest of the folder.
+
+## Step 2: map files to standards
+
+Read the mapping rather than holding it here. Every standard declares the paths it governs, so a standard added later joins this audit with no edit to this body:
+
+```bash
+canon standards list --json
+```
+
+Each entry carries `appliesTo`, the paths its `## Scope` statement declares. Match every changed file against every entry:
+
+- `*` matches every changed markdown file
+- An entry ending in `/` matches when the file path contains it at a path-segment boundary
+- Any other entry matches when the file path ends with it at a path-segment boundary
+
+Add any standard the catalog did not list, reading `${CLAUDE_SKILL_DIR}/../../standards/` and whatever folder the project authors its own standards in, and derive every declaration the same way when `canon` is unavailable: the backticked paths in the first sentence under `## Scope`, or `*` when that sentence says the standard governs an attribute. Skip `index.md`, which is generated from the others and declares nothing.
+
+An entry whose `appliesTo` is empty declared nothing this can read. Report it as a finding against that standard's own file in Step 4 and audit the rest. A standard dropped in silence is the same miss this mapping exists to remove, one level up.
+
+Every mapping names a changed markdown file, which is the only thing Step 1 produces. Text that never lands in the tree, such as a branch name or a pull request body, is checked by the skill that publishes it rather than here.
+
+## Step 3: read standards and audit
+
+Read each applicable standard once from `${CLAUDE_SKILL_DIR}/../../standards/<name>`, testing the file before reading it. A standard the mapping named and that path does not carry is reported as a finding against the file that mapped to it rather than skipped, since a standard read from nowhere reports every file under it clean.
+
+For each changed file, audit against every rule:
+
+- **Pattern rules**: grep the file for every token the standard bans. Grep is authoritative. Reading alone misses occurrences.
+- **Judgment rules**: check each rule in context against the standard that states it.
+
+Every changed markdown file gets the pattern pass, since `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` applies to all of them. Take the banned tokens from that standard at read time rather than from a list held here. It carries the banned words, the banned spellings, and the banned characters together, so one read covers every token this pass greps for.
+
+## Step 4: report
+
+Group findings by file with line references, naming the standard each one comes from. One file is one fix pass, and the standard is what the reader opens to settle a finding they disagree with. Use this shape:
+
+```markdown
+path/to/file.md
+
+- L12: `markdown.md`, em dash in prose
+- L34: `markdown.md`, semicolon used to join clauses
+- L51: `markdown.md`, vague qualifier `simply`
+- L67: `context.md`, decision entry names no rejected alternative
+```
+
+If clean, respond with `✅ No violations.`
+
+Reporting only. Do not rewrite any file, swap any punctuation, or propose fixes inline. Fixes are a separate user-initiated step because a lazy swap (semicolon to period, em dash to comma) leaves the sentence in the shape the ban exists to remove.
+
+## Output
+
+Chat output is the full report. This skill does not persist a file. The audit is a momentary check and living state is the diff itself.

package/claude/skills/claude-tasks/REQUIREMENT.md

@@ -0,0 +1,43 @@
+---
+name: claude-tasks
+description: Why creating and archiving a task file is one skill, the origin invariant enforceable only at creation, and why archiving routes through the command the merge hook calls
+---
+
+# Claude tasks requirement
+
+## Gap
+
+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.
+
+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.
+
+## Must
+
+- Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
+- Read the tasks standard before writing, rather than working the filename and frontmatter from memory
+- Require an origin at creation, because that is the only moment the invariant is enforceable
+- Propose the phase label from what is already on the board and pad it to two digits
+- Confirm the work reached the default branch before archiving
+- Run the archive command and route on the reason it refuses, since each reason has one resolution
+- Report an origin that carries no task, as a list rather than a prompt
+
+## Must not
+
+- Mark an outcome complete or archive a plan
+- Hand-edit the index or the ordering file, or move the task file directly
+- Write a pull request line at creation, when any number is a guess at someone else's work
+- Archive around a refusal
+- Split the legacy single-file archive into per-task files nobody wrote
+
+## Guards
+
+- No task board at the main root: stop
+- The request fits neither creating nor archiving: stop rather than picking one
+- Work not yet on the default branch: stop, because the board has no history to restore from
+- No origin given and none offered: stop
+
+## Out of scope
+
+- Editing the contents of a task that already exists, which `claude-docs` owns along with marking outcomes and sweeping plans
+- Deciding what the task should argue. This owns the file's existence and its shape, not its content.
+- Relocating a plan, which one skill owns so two do not relocate it differently