@erclx/canon 5.21.0 → 5.22.0

package/src/slides/package/test-face.ts

@@ -0,0 +1,113 @@
+/**
+ * Builds the smallest sfnt the font step reads, holding only the `OS/2`,
+ * `head`, and `name` tables an EOT header is built from, plus `fvar` when the
+ * face should read as variable. It carries no glyphs, so it embeds and never
+ * renders. Tests use it in place of a real face, whose license the repository
+ * would then have to carry.
+ */
+
+export interface TestFaceOptions {
+  readonly family?: string
+  readonly subfamily?: string
+  readonly weight?: number
+  readonly isItalic?: boolean
+  readonly fsType?: number
+  readonly isVariable?: boolean
+  /** The first four bytes, `0x00010000` for TrueType. */
+  readonly version?: number
+}
+
+/** Values distinct enough that a header copying the wrong field shows it. */
+export const TEST_FACE = {
+  panose: [2, 11, 5, 3, 3, 4, 3, 2, 2, 4],
+  unicodeRanges: [0xe0000aff, 0x5000e5ff, 0x00000009, 0x00000001],
+  codePages: [0x0000019f, 0x01020000],
+  checkSumAdjustment: 0x1234abcd,
+} as const
+
+function os2(options: TestFaceOptions): Buffer {
+  const table = Buffer.alloc(96)
+  table.writeUInt16BE(4, 0)
+  table.writeUInt16BE(options.weight ?? 400, 4)
+  table.writeUInt16BE(options.fsType ?? 0, 8)
+  Buffer.from(TEST_FACE.panose).copy(table, 32)
+  TEST_FACE.unicodeRanges.forEach((range, index) => {
+    table.writeUInt32BE(range, 42 + index * 4)
+  })
+  table.write('TEST', 58, 'latin1')
+  table.writeUInt16BE(options.isItalic ? 0x0001 : 0x0040, 62)
+  TEST_FACE.codePages.forEach((page, index) => {
+    table.writeUInt32BE(page, 78 + index * 4)
+  })
+  return table
+}
+
+function head(): Buffer {
+  const table = Buffer.alloc(54)
+  table.writeUInt32BE(0x00010000, 0)
+  table.writeUInt32BE(TEST_FACE.checkSumAdjustment, 8)
+  table.writeUInt32BE(0x5f0f3cf5, 12)
+  return table
+}
+
+function name(strings: ReadonlyMap<number, string>): Buffer {
+  const encoded = [...strings].map(([id, text]) => ({
+    id,
+    bytes: Buffer.from(text, 'utf16le').swap16(),
+  }))
+  const header = Buffer.alloc(6 + encoded.length * 12)
+  header.writeUInt16BE(0, 0)
+  header.writeUInt16BE(encoded.length, 2)
+  header.writeUInt16BE(header.length, 4)
+  let offset = 0
+  encoded.forEach(({ id, bytes }, index) => {
+    const at = 6 + index * 12
+    header.writeUInt16BE(3, at)
+    header.writeUInt16BE(1, at + 2)
+    header.writeUInt16BE(0x0409, at + 4)
+    header.writeUInt16BE(id, at + 6)
+    header.writeUInt16BE(bytes.length, at + 8)
+    header.writeUInt16BE(offset, at + 10)
+    offset += bytes.length
+  })
+  return Buffer.concat([header, ...encoded.map(({ bytes }) => bytes)])
+}
+
+export function testFace(options: TestFaceOptions = {}): Buffer {
+  const family = options.family ?? 'Fixture Sans'
+  const subfamily = options.subfamily ?? 'Regular'
+  const tables = new Map<string, Buffer>([
+    ['OS/2', os2(options)],
+    ['head', head()],
+    [
+      'name',
+      name(
+        new Map([
+          [1, family],
+          [2, subfamily],
+          [4, `${family} ${subfamily}`],
+          [5, 'Version 1.000'],
+        ]),
+      ),
+    ],
+  ])
+  if (options.isVariable) tables.set('fvar', Buffer.alloc(16))
+
+  const entries = [...tables].sort(([a], [b]) => a.localeCompare(b))
+  const directory = Buffer.alloc(12 + entries.length * 16)
+  directory.writeUInt32BE(options.version ?? 0x00010000, 0)
+  directory.writeUInt16BE(entries.length, 4)
+  let offset = directory.length
+  const bodies: Buffer[] = []
+  entries.forEach(([tag, table], index) => {
+    const at = 12 + index * 16
+    directory.write(tag, at, 'latin1')
+    directory.writeUInt32BE(offset, at + 8)
+    directory.writeUInt32BE(table.length, at + 12)
+    const padded = Buffer.alloc(Math.ceil(table.length / 4) * 4)
+    table.copy(padded)
+    bodies.push(padded)
+    offset += padded.length
+  })
+  return Buffer.concat([directory, ...bodies])
+}

package/src/sync/check.ts

@@ -10,8 +10,10 @@ import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
   collectSuperseded,
   detectUnmigrated,
+  detectUnmovedSurfaces,
   type SupersededEntry,
   type UnmigratedDomain,
+  type UnmovedSurface,
 } from '@/sync/layout'
 import {
   buildReverseReport,
@@ -178,6 +180,11 @@ export interface CheckReport {
   readonly seeds: SeedsReport
   readonly superseded: readonly SupersededEntry[]
   readonly unmigrated: readonly UnmigratedDomain[]
+  /**
+   * Report-only like `superseded`, since a target's CI gating on `--exit-code`
+   * would otherwise start failing on a layout nobody asked it to move yet.
+   */
+  readonly unmovedSurfaces: readonly UnmovedSurface[]
   readonly newSkills: readonly string[]
   /**
    * Rules the toolkit authored after this target's governance anchor, filtered
@@ -440,6 +447,7 @@ export async function buildCheckReport(
       seeds: { entries: [], historyUnavailable: false },
       superseded: [],
       unmigrated: [],
+      unmovedSurfaces: [],
       newSkills: [],
       newRules: [],
       reverse: emptyReverseReport(),
@@ -456,6 +464,7 @@ export async function buildCheckReport(
     seeds: buildSeedsReport(toolkitRoot, target),
     superseded: collectSuperseded(target),
     unmigrated,
+    unmovedSurfaces: detectUnmovedSurfaces(target),
     newSkills: await readNewSkills(toolkitRoot, anchors),
     newRules: await readNewRules(toolkitRoot, target, stamp),
     reverse: buildReverseReport(toolkitRoot, target),

package/src/sync/layout.ts

@@ -2,7 +2,7 @@ import { existsSync, statSync } from 'node:fs'
 import { basename, join, relative } from 'node:path'
 import { SUBDIRS } from '@/claude/seeds'
 import { creationRel, isRecordEntry } from '@/record-root'
-import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
+import { SURFACE_ENTRIES, spell, surfaceDir } from '@/surface-root'
 import type { StampDomain } from '@/sync/stamp'
 
 const CLAUDE_DIR = '.claude'
@@ -122,6 +122,32 @@ export function detectUnmigrated(
   return found
 }
 
+/**
+ * A tracked surface the target still reads at its `.claude/` spelling, with
+ * nothing at the `canon/` one, and where `canon migrate surface-roots` moves it.
+ */
+export interface UnmovedSurface {
+  readonly rel: string
+  readonly movesTo: string
+}
+
+/**
+ * Surfaces a target holds only at the root the surface move retired. Kept
+ * apart from `detectUnmigrated`, which models a domain stranded at the project
+ * root under a stamp domain, while a surface carries neither. A rule names the
+ * current layout only, so a target here stops loading the rules scoped to these
+ * files, and this report is what points it at the verb.
+ */
+export function detectUnmovedSurfaces(target: string): UnmovedSurface[] {
+  return SURFACE_ENTRIES.filter(
+    (entry) =>
+      relative(target, surfaceDir(target, entry)) === join(CLAUDE_DIR, entry),
+  ).map((entry) => ({
+    rel: join(CLAUDE_DIR, entry),
+    movesTo: join('canon', spell('canon', entry)),
+  }))
+}
+
 /**
  * Root files whose basename matches something the toolkit ships for this domain.
  * Basenames rather than relative paths, because the root layout an older toolkit

package/standards/architecture.md

@@ -3,7 +3,6 @@ title: Architecture reference
 description: Shape and content rules for canon/ARCHITECTURE.md
 paths:
   - 'canon/ARCHITECTURE.md'
-  - '.claude/ARCHITECTURE.md'
 rule:
   - "Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one."
 ---

package/standards/context.md

@@ -3,7 +3,6 @@ title: Context entry reference
 description: Shape and content rules for canon/context/<domain>.md entries
 paths:
   - 'canon/context/**'
-  - '.claude/context/**'
 rule:
   - 'Before non-trivial work in a domain, read its `canon/context/<domain>.md` entry. Use `canon/context/index.md` to find it.'
   - 'Leave the entry conforming when work in its domain changes what it describes.'

package/standards/design.md

@@ -3,7 +3,6 @@ title: Design reference
 description: Shape and content rules for canon/DESIGN.md
 paths:
   - 'canon/DESIGN.md'
-  - '.claude/DESIGN.md'
 ---
 
 # Design reference

package/standards/diagrams.md

@@ -3,12 +3,9 @@ title: Diagram reference
 description: Shape and content rules for .canon/diagrams/<kind>.md files
 paths:
   - '.canon/diagrams/**'
-  - '.claude/DIAGRAMS.md'
 rule:
   - 'Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. The mermaid standard routes them.'
   - 'A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.'
-  - 'Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`'
-  - 'Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it'
 ---
 
 # Diagram reference

package/standards/requirements.md

@@ -3,7 +3,6 @@ title: Requirements reference
 description: Shape and content rules for canon/REQUIREMENTS.md
 paths:
   - 'canon/REQUIREMENTS.md'
-  - '.claude/REQUIREMENTS.md'
 ---
 
 # Requirements reference

package/standards/rule.md

@@ -89,6 +89,7 @@ paths:
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
 - Keep the file to one topic. A second topic is a second rule file.
 - Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
+- Name the current layout only, in a glob and in the body alike. A layout change ships a migration verb, as `canon migrate surface-roots` and `canon migrate records` did, rather than a rule line or a glob that keeps the old spelling loading.
 
 ## Examples
 

package/standards/wireframes.md

@@ -3,7 +3,6 @@ title: Wireframe reference
 description: Shape and content rules for canon/wireframes/<surface>.md files
 paths:
   - 'canon/wireframes/**'
-  - '.claude/wireframes/**'
 rule:
   - 'Read it before adding or revising a surface.'
 ---

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -19,15 +19,20 @@ IFS= read -r -d '' -t 2 input
   exit 1
 }
 
+# Two shapes open a pull request. `gh pr create` names itself in the command.
+# git-pr opens one over REST and prints `opened=true` only on that path, since
+# its edit path prints a URL as well and is not an opening.
 command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+stdout=$(printf '%s' "$input" | jq -r '.tool_response.stdout // empty')
 case "$command" in
 *"gh pr create"*) ;;
-*) exit 0 ;;
+*)
+  printf '%s\n' "$stdout" | grep -qx 'opened=true' || exit 0
+  ;;
 esac
 
-# gh pr create prints the new pull request's URL to stdout on success, so
+# Either shape prints the new pull request's URL to stdout on success, so
 # matching it is what tells a creation apart from a failed or refused call.
-stdout=$(printf '%s' "$input" | jq -r '.tool_response.stdout // empty')
 url=$(printf '%s' "$stdout" | grep -Eo 'https://github\.com/[^[:space:]]+/pull/[0-9]+' | tail -1)
 [ -n "$url" ] || exit 0
 

package/claude/skills/draft-context/REQUIREMENT.md

@@ -1,37 +0,0 @@
----
-name: draft-context
-description: Why a brand-new canon/context/<domain>.md entry needs a catalog collision check and a confirm step, not the refresh path context-fold already owns
----
-
-# Context draft requirement
-
-## Gap
-
-Without this skill, a session documenting a domain that has no context entry yet either invents a shape from memory or reaches for the refresh mechanism, which reads an existing entry and a diff and has neither to work from for a domain that never had one. Either way the entry ships with no read of `standards/context.md` and no check against the catalog for a sibling already covering the same ground under a different name.
-
-## Must
-
-- Read `standards/context.md` before drafting, since the frontmatter contract and the three-question test are what make the entry arguable against a sibling
-- Check the domain against the existing catalog by slug and by title-and-description, not by slug alone, since a domain can be covered under a name the topic phrase does not guess
-- Default a brand-new entry to a flat file, since a fresh domain never holds the three or more sub-areas the standard requires before it earns a folder
-- Confirm the resolved path and the full content with the user before writing, since placement is a judgment call with no diff to preview it against
-- Run `canon indexes regen` on `canon/context/` after writing, so the catalog picks up the new domain immediately rather than drifting until the next unrelated regen
-
-## Must not
-
-- Refresh or rewrite an existing entry. A domain already covered refuses toward the refresh mechanism.
-- Hand-edit `canon/context/index.md`. It regenerates from sibling frontmatter, and a hand edit is overwritten on the next regen.
-- Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an author typing its name has no answer at creation time, so a review pass some months in should read that back rather than take the assumption on faith.
-
-## Guards
-
-- No domain given: stop and ask what domain the entry should cover.
-- The derived slug already resolves to `canon/context/<slug>.md` or `canon/context/<slug>/index.md`: stop and point at the refresh mechanism instead.
-- The catalog already covers the domain under a different name: stop the same way, checked against the titles and descriptions the Placement step already reads.
-
-## Out of scope
-
-- Refreshing an existing `canon/context/<domain>.md` entry against a diff: `context-fold`
-- Drafting a `canon/wireframes/<surface>.md` file: `draft-wireframes`
-- Drafting a `docs/*.md` page: `draft-docs`
-- Drafting a standard or a governance rule: `create-standard`, `create-rule`

package/claude/skills/draft-context/SKILL.md

@@ -1,61 +0,0 @@
----
-name: draft-context
-description: Drafts a brand-new `canon/context/<domain>.md` entry against the context standard, checks the catalog for a name-or-topic collision, decides flat-file placement, confirms with the user, then writes. Use when asked to "write a context entry for X", "document the X domain", "add a context entry for X", or "create a canon/context page for X" where no existing entry covers the domain. Do NOT use to refresh an existing entry against a diff, which is `context-fold`.
----
-
-# Context draft
-
-Drafts one brand-new `canon/context/<domain>.md` entry end to end: read the standard, decide whether the domain is already covered under a different name, confirm the draft with the user, then write.
-
-A project the surface move has not reached keeps its context folder under `.claude/` rather than `canon/`. Check and write at whichever root already carries the folder, and create it under `canon/` only when neither does, since a new `canon/` folder would hide every entry the old one holds.
-
-Read these files in parallel:
-
-- `${CLAUDE_SKILL_DIR}/../../standards/context.md`: the three questions an entry must answer, its frontmatter, required and expected sections, and what stays out of it
-- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: punctuation and formatting for all generated text
-- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-
-## Guards
-
-- If no domain is given, stop: `❌ No domain given. Name the domain this entry should cover.`
-- Derive a kebab-case slug from the domain and check whether `canon/context/<slug>.md` or `canon/context/<slug>/index.md` already exists. Either resolving means the domain is already covered under that exact name. Stop: `❌ <slug> already has a context entry. Use context-fold to refresh it instead.`
-
-## Placement
-
-- Read `canon/context/index.md` and check every title and description it lists against the domain. The Guards check above only catches an exact-slug collision, and a domain already covered under a different name still resolves here at no extra cost, since this read already runs.
-- Stop the same way on a match: `❌ <path> already covers this domain under a different name. Use context-fold to refresh it instead.`
-- Default a brand-new entry to a flat file, `canon/context/<slug>.md`. A domain starts as one page's worth of narrative, and the standard only splits it into a folder once it holds three or more sub-areas, which a fresh domain never does on day one.
-
-## Draft
-
-- Read the domain's own folders and files well enough to answer the standard's three questions: where things live, why they are that way, and how to add one more of what the domain holds.
-- Draft `title` and `description` frontmatter, then `## Overview`, `## Layout` (folder ownership lines only, never a file-by-file list), and `## Decisions` or `## Gotchas` wherever the domain's history supplies a non-obvious choice or a workaround worth preserving. Omit an expected section with nothing to put in it rather than padding it.
-- Draft against `${CLAUDE_SKILL_DIR}/../../standards/context.md`'s template and ordering: `Overview`, `Layout`, `Decisions`, `Gotchas`, then anything else.
-
-## Confirm
-
-- Show the resolved path and the full drafted content before writing.
-- Confirm both with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since placement here is a judgment call with no diff to preview it against.
-
-## Write
-
-- Write the file at the confirmed path, creating the folder when it is absent.
-- Run `canon markdown audit <path>`.
-- Run `canon indexes regen canon/context`, so the domain appears in `canon/context/index.md` immediately rather than drifting until the next unrelated regen.
-
-## Response format
-
-### Preview
-
-**Domain:** `<domain>`
-**Placement:** `<path>`
-
-```markdown
-<drafted frontmatter and body>
-```
-
-### After confirmation
-
-```plaintext
-✅ Drafted: <path>
-```

package/claude/skills/draft-docs/REQUIREMENT.md

@@ -1,35 +0,0 @@
----
-name: draft-docs
-description: Why a brand-new docs/*.md page needs a placement decision and a confirm step, not the rewrite path docs-sync already owns
----
-
-# Docs draft requirement
-
-## Gap
-
-Without this skill, a session drafting documentation for a surface that has no page yet either invents structure from memory or reaches for `docs-sync`, which has nothing to diff a nonexistent page against and reports the topic as unrelated to any change. Either way the page ships with no read of `standards/docs.md` and no catalog placement decided against the folder's actual shelves.
-
-## Must
-
-- Read `standards/docs.md` before drafting, since the frontmatter contract and the four reader questions are what make the page arguable against a sibling
-- Decide placement from the existing catalog rather than guessing a folder, reusing a `category` value verbatim when one fits and defaulting to the `docs/` root when none does
-- Confirm the resolved path and the full content with the user before writing, since placement is a judgment call with no diff to preview it against
-- Run `canon indexes regen` on the containing folder after writing, so the folder's `index.md` picks up the new page immediately rather than drifting until the next unrelated regen
-
-## Must not
-
-- Rewrite an existing page. A topic already covered by a page refuses toward `docs-sync`.
-- Hand-edit an `index.md`. It regenerates from sibling frontmatter, and a hand edit is overwritten on the next regen.
-- Build a hand-drawn diagram-and-capture authoring loop. `standards/docs.md`'s Mermaid-fence permission is the only path to a diagram this skill takes.
-
-## Guards
-
-- No topic given: stop and ask what surface the page should cover.
-- The derived slug already resolves through `canon docs <slug>`: stop and point at `docs-sync` instead. This catches an exact-name collision only.
-- A page in the catalog already covers the topic under a different name: stop the same way, checked against the titles and descriptions Placement already reads.
-
-## Out of scope
-
-- Rewriting or syncing an existing `docs/*.md` section against a diff since main: `docs-sync`
-- The context entries, requirements, architecture, wireframes, and task board: `context-fold`
-- Drafting a standard or a governance rule: `create-standard`, `create-rule`

package/claude/skills/draft-docs/SKILL.md

@@ -1,59 +0,0 @@
----
-name: draft-docs
-description: Drafts a brand-new `docs/*.md` page against the docs standard, decides its placement in the existing catalog, confirms with the user, then writes. Use when asked to "add a docs page for X", "write a new doc for X", "document X under docs/", or "create a docs page for X" where no existing page covers the topic. Do NOT use to rewrite or sync an existing `docs/*.md` section against a diff, which is `docs-sync`.
----
-
-# Docs draft
-
-Drafts one brand-new `docs/*.md` page end to end: read the standard, decide where the page belongs in the existing catalog, confirm the draft with the user, then write.
-
-Read these files in parallel:
-
-- `${CLAUDE_SKILL_DIR}/../../standards/docs.md`: the reader a page serves, its frontmatter, structure, and what it links out to rather than restates
-- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: punctuation and formatting for all generated text
-- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-
-## Guards
-
-- If no topic is given, stop: `❌ No topic given. Name the surface this page should cover.`
-- Derive a kebab-case slug from the topic and run `canon docs <slug>`. A resolved page means the topic is already covered under that exact name. Stop: `❌ <slug> already resolves to an existing page. Run canon:docs-sync instead.` This is a name match rather than a topic match. Placement below checks the wider case.
-
-## Placement
-
-- Read `docs/index.md` and its sub-catalogs for the closest existing `category`. <!-- canon-allow-reference: illustrates the target project's own docs/ tree, not a citation of this repository's own corpus -->
-- Check every page title and description this read surfaces against the topic. The Guards check above only catches an exact-slug collision, and a page already covering the same subject under a different slug still resolves here at no extra cost, since this read already runs. Stop the same way on a match: `❌ <path> already covers this topic under a different name. Run canon:docs-sync instead.`
-- Reuse a matching `category` value verbatim. A near-miss spelling opens a second shelf holding one page, per the docs standard.
-- Default to the `docs/` root with no `category` when nothing fits. A subfolder earns itself only once a shelf of pages already sits there, per the standard's splitting rule.
-
-## Draft
-
-- Draft `title`, `description`, and `category` (where one applies), then the page body, against `${CLAUDE_SKILL_DIR}/../../standards/docs.md`.
-- Write for a reader with no source open. The standard's four questions are the test: what the surface is, what to run or write, what it refuses, and where to go for the adjacent surface.
-
-## Confirm
-
-- Show the resolved path and the full drafted content before writing.
-- Confirm both with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since placement here is a judgment call with no diff to preview it against.
-
-## Write
-
-- Write the file at the confirmed path, creating the folder when it is absent.
-- Run `canon markdown audit <path>`.
-- Run `canon indexes regen <folder>` on the containing folder, so its `index.md` picks up the new page.
-
-## Response format
-
-### Preview
-
-**Topic:** `<topic>`
-**Placement:** `<path>` (category: `<category-or-root>`)
-
-```markdown
-<drafted frontmatter and body>
-```
-
-### After confirmation
-
-```plaintext
-✅ Drafted: <path>
-```

package/claude/skills/draft-readme/REQUIREMENT.md

@@ -1,38 +0,0 @@
----
-name: draft-readme
-description: Why a README needs a project-type read and a confirm step, not the rewrite path docs-sync already owns
----
-
-# Readme draft requirement
-
-## Gap
-
-Without this skill, a session drafting a README either copies the generic template from memory or reaches for `docs-sync`, which has nothing to diff a nonexistent page against and reports the topic as unrelated to any change. A scaffold-written stub meets the same dead end, since no diff touches it either. Either way the page ships with no read of `standards/readme.md`, no read of what the project actually is, and no badge chosen against its rendered value rather than its service name.
-
-A README whose real documentation lives in `canon/context/` or `docs/` was a second gap the standard itself carried until this build: nothing named a pointer page as complete, so a session drafting one either padded the page or read the required list as unsatisfied.
-
-## Must
-
-- Read `standards/readme.md` before drafting, since its `## Voice` section is scoped to a repository-root README and yields to `write-human`'s reference voice everywhere else
-- Detect every project type the standard's `## Content` list applies to, from the manifest and the tree, rather than drafting against the closest single type
-- Treat an existing README with no H1, or with headings that name only the scaffold that wrote it, as unedited generator output to draft over rather than a page to sync section by section
-- Read the header block's slots off the repository, being the mark, the claim, the live link, and the product screenshot, and skip the link and the screenshot for a project with no page, so every element traces to a file or field the project holds
-- Verify a candidate badge by the value it would render rather than by a fetch's status code, since a badge service answers 200 for a query it cannot satisfy
-- Confirm the resolved path, the detected types, the badge candidates, and the full content with the user before writing, since project-type detection and badge selection are judgment calls with no diff to preview them against
-
-## Must not
-
-- Rewrite an authored README. One carrying an H1 that names the project refuses toward `docs-sync`.
-- Offer to overwrite an authored README on the refusal path, or propose conforming it to what this skill would have drafted. A target project's own citations into its README are invisible from here, so the refusal reports rather than proposes.
-- Invent a screenshot or a mark the project does not hold, or write a placeholder path for one. An omitted slot is a correct page and an invented image is the failure.
-- Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an author typing its name has no answer at creation time, so a review pass some months in should read that back rather than take the assumption on faith.
-
-## Guards
-
-- The target already exists and is authored, carrying an H1 that names the project: stop and point at `docs-sync` instead.
-
-## Out of scope
-
-- Rewriting or syncing an existing authored `README.md` against a diff since main: `docs-sync`
-- The consumer-facing reference under `docs/`: `draft-docs`
-- Product scope and goals, and every other surface `standards/readme.md` already scopes out of its own governance

package/claude/skills/draft-readme/SKILL.md

@@ -1,73 +0,0 @@
----
-name: draft-readme
-description: Drafts a project's README.md against the readme standard, detecting project type and badge candidates, and confirming with the user before write. Use when asked to "write a README", "draft a README for this project", "add a README", or "create a README.md" where none exists yet or the existing one is unedited scaffold output. Do NOT use to rewrite or resync an existing authored README against a diff, which is `docs-sync`.
----
-
-# Readme draft
-
-Drafts a project's `README.md` end to end: read the standard, detect the project's shape, confirm the draft with the user, then write.
-
-Read these files in parallel:
-
-- `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: voice, structure, required and optional sections, badge selection, and what to link out to rather than carry. Voice is claimed here for a repository-root README, and `write-human` yields it there while keeping rhythm, density, and the machine-tell catalog everywhere, root README included.
-- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: punctuation and formatting for all generated text
-- The `write-human` skill: rhythm, density, and sentence construction for all generated text
-
-## Guards
-
-- Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README instead, which keeps the reference voice per the standard's `## Voice` section rather than the root voice below.
-- Read the target if it exists.
-  - It carries an H1 naming the project: it is authored. Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.`
-  - It carries no H1, or its only headings restate the tool that scaffolded it rather than the project: it is unedited generator output. Continue, drafting over it rather than syncing its sections.
-  - It does not exist: continue.
-- A hand-authored README opening with a badge block, or a title in some other form the H1 test misses, falls into the no-H1 branch the same as a scaffold page. The Confirm step below is what catches that case before the write happens, so treat it as load-bearing rather than a courtesy: never skip it on the reasoning that the guard already decided.
-
-## Detect
-
-- Read the project's manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent) for a `bin` field or CLI entry point, an installable package name, and its declared dependencies.
-- Check for a `claude/skills/` or `.claude/skills/` folder, a `plugin.json`, or a marketplace manifest, each naming an agent-facing or marketplace-distributed surface.
-- A project is often several of these at once. Note every type that applies rather than stopping at the first match, since the Draft step covers each one the project actually is.
-- Check for a page. A dependency on a site framework or a site config file in the manifest or the tree marks a project as having one. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
-- A monorepo can carry a page in one package and a CLI in another, so both signals may fire. Report each rather than picking one.
-- Look for the mark and the screenshot among images the project already commits: scan the existing README for image references, then the asset and public folders.
-
-## Draft
-
-- Draft the page against `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: H1, a 2-3 sentence description in plain text, then the required sections, then whichever optional sections and per-type content the Detect step found.
-- Open the page with the standard's header block, filling each slot from what Detect found: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot.
-- Fill the screenshot slot only with an image the project already commits, referenced with alt text naming what it depicts. This skill cannot capture one. Omit the slot when no such image exists and say so in the preview. Never write a placeholder path.
-- Omit the link and the screenshot for a project with no page, and the mark for a project with none, without a note in the drafted page. A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link.
-- Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
-- Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
-- State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.
-- Pin a status badge to the branch the standard names and confirm the workflow actually triggers on that branch before offering it. Zero badges is a correct answer when nothing passes the test.
-
-## Confirm
-
-- Show the resolved path, the detected project types, the header slots filled or skipped with the reason for each, the badge candidates and what backs each one, and the full drafted content before writing.
-- The skill can confirm that an image file exists and is referenced, and it cannot verify the picture shows the product. Ask the user to look at it in the preview.
-- Confirm with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since project-type detection and badge selection are judgment calls with no diff to preview them against.
-
-## Write
-
-- Write the file at the confirmed path, creating the folder when it is absent.
-- Run `canon markdown audit <path>`.
-
-## Response format
-
-### Preview
-
-**Target:** `<path>` (root | nested)
-**Detected:** `<project types>`
-**Header:** `<each slot as filled (source) or skipped (reason)>`
-**Badges:** `<candidates, or none>`
-
-```markdown
-<drafted H1 and body>
-```
-
-### After confirmation
-
-```plaintext
-✅ Drafted: <path>
-```

package/claude/skills/draft-wiki/REQUIREMENT.md

@@ -1,42 +0,0 @@
----
-name: draft-wiki
-description: Why a brand-new wiki reference page needs both placement tests, a catalog collision check, and a sourced read before anything is written
----
-
-# Wiki draft requirement
-
-## Gap
-
-Without this skill, a session asked for a wiki page writes one from training knowledge, which is the single thing the wiki standard forbids outright, and nothing in the resulting file shows that it happened. It also files the page by where the request came from rather than by who owns the subject, so material about the project itself lands in the wiki and material about a third-party tool acquires a folder the standard never sanctioned.
-
-The standard can state all of this and still be read by nothing, which is the condition this skill was written into in the toolkit. A page written under that condition conforms by the author's memory rather than by a read, and it ships looking identical to one that was checked.
-
-## Must
-
-- Read the wiki standard before drafting, since the placement tests and the sourcing rule are the two things a session gets wrong from memory
-- Run both placement tests and refuse on either, since a page passing one and failing the other is still non-conforming
-- Check the subject against the catalog by title and description, not by slug alone, since a subject can be covered under a name the slug does not guess
-- Build the draft on a fetched read and stop when the fetch fails, since a page written from recall is indistinguishable from a checked one once it ships
-- Confirm the path, the source, and the content with the user before writing, since the standard forbids writing a wiki file unasked
-- Name the folder by resolving what the standard states rather than by carrying a path in the body, since the body ships to projects whose layout this repository does not set
-
-## Must not
-
-- Widen the folder split to admit a subject the second placement test rejects. That is a change to the standard, argued there.
-- Edit or refresh a page that already exists. A collision refuses toward editing the existing page rather than drafting a second one.
-- Substitute recall for a failed fetch, even for a subject the session believes it knows.
-
-## Guards
-
-- No subject given: stop and ask what subject the page should cover.
-- The wiki root does not resolve: say so and ask before creating it, since a project holding no wiki has never taken the placement rule.
-- The slug already resolves to a page: stop and point at editing that page.
-- The catalog already covers the subject under a different name: stop the same way, checked against the titles and descriptions the Collision step already reads.
-
-## Out of scope
-
-- Editing or refreshing a wiki page that already exists: a plain edit against the same standard
-- Drafting a `docs/*.md` page: `draft-docs`
-- Drafting a `canon/context/<domain>.md` entry: `draft-context`
-- Voice, rhythm, and sentence construction in the drafted page: the `write-human` skill
-- Punctuation, headings, and word choice in the drafted page: the markdown standard