@erclx/aitk 3.8.0 → 3.9.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/create-skill/REQUIREMENT.md

@@ -11,9 +11,12 @@ Without this skill, a new skill lands in the wrong shape and the wrong place. A
 
 A skill born without its requirement is the second failure, and it surfaces much later. Coverage of the corpus is what the operator reads to decide whether a skill should exist, so every skill created without the sibling decays that reading, and the sweep that closes the gap has to reconstruct what the skill was for from the body it already shipped.
 
+A third failure is a folder created for a moment a rule, a verb, or an existing skill already reaches, or for a procedure no session would get wrong from first principles. Nothing caught that before the folder existed, so the corpus grew by a skill an inward audit later had to argue for removing, with only a commit body recording the argument.
+
 ## Must
 
 - Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
+- Answer, in writing, whether a rule, a verb, or an existing skill already reaches this moment, and whether the body carries a procedure a session would get wrong from first principles. A folder that fails either belongs to the surface that already covers it, not to a new skill.
 - Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
 - Confirm the name and both files with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
 - Write to the conventional skills path, so discovery finds it without configuration
@@ -23,6 +26,7 @@ A skill born without its requirement is the second failure, and it surfaces much
 - Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
 - Write either file before the user has seen it
 - Derive the requirement from the drafted body, which records the draft's overfitting as the requirement
+- Gate creation on whether anything will invoke the new skill beyond the author typing its name. That question has no answer yet.
 
 ## Guards
 
@@ -31,4 +35,4 @@ A skill born without its requirement is the second failure, and it surfaces much
 ## Out of scope
 
 - Editing an existing skill, which the authoring standard and the skill's own requirement govern
-- Judging whether the skill is warranted. A skill nobody needed is an audit finding, not a creation-time refusal.
+- Whether anything ends up invoking the new skill: the usage census in `.claude/context/claude-plugin/skill-strategy.md`, read once the skill has run

package/claude/skills/create-skill/SKILL.md

@@ -18,9 +18,15 @@ Read these files in parallel:
 
 ## Steps
 
-1. Draft the full `SKILL.md` from the user's description
-2. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
-3. Confirm the skill name and both files with the user before writing
-4. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
+1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles:
+   - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
+   - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
+   - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
+2. Draft the full `SKILL.md` from the user's description
+3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
+4. Confirm the skill name and both files with the user before writing
+5. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
+
+The two-question check has a shipped precedent. Pull request `#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Sixteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Seventeen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
 The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
 
-Thirteen of the sixteen read a tree on this disk. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
+Fourteen of the seventeen read a tree on this disk, the one added by `restated.md` among them, since it reads three such trees against each other. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 

package/docs/agents/commands.md

@@ -50,6 +50,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk 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`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
+| `aitk gov restated`        | Report every instruction the always-loaded file shares with the seed or a shipped skill body, classed and with its anchors named (`--json`)    |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
 | `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
 | `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                  |

package/docs/agents/index.md

@@ -24,6 +24,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Restated instructions](restated.md): Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain

package/docs/agents/restated.md

@@ -0,0 +1,78 @@
+---
+title: Restated instructions
+description: Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
+---
+
+# Restated instructions
+
+`aitk gov restated` reports every instruction the always-loaded file states that a second surface states too. It answers a question nothing else here could: one rule was found written in three places, and it was found by accident when a shipped skill deleted a file the rule said to keep.
+
+```bash
+aitk gov restated
+aitk gov restated --json
+aitk gov restated --root ../my-app
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | Tree to read, defaulting to the current directory          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## The corpus it reads
+
+Three surfaces, and they are not read symmetrically. Every top-level bullet in `CLAUDE.md` is a subject, and the other two are searched:
+
+- `tooling/claude/seeds/CLAUDE.md`, read as bullets, since the seed carries the same shape as the file it is authored from
+- `claude/skills/*/SKILL.md`, read as every prose line and bullet, since the motivating case was stated in a body as a paragraph rather than a list item
+
+Frontmatter, headings, tables, and fenced blocks are read past. A heading names a section instead of stating a rule, a fenced block is an example whose words belong to the prose around it, and a body's `description` restates that skill's own purpose, so sweeping it would match every subject naming its domain.
+
+A rule stated in two skill bodies and never in `CLAUDE.md` is outside this reading. The bullets there are the subjects, and a subject is what the search runs from.
+
+## How a match is decided
+
+Matching is recall-first and keyed on shared distinctive tokens rather than on a phrase two surfaces spell the same way. The case this exists for was one rule written three different ways, so a near-exact matcher would ship a cheap report blind to the defect it was built for.
+
+A token is distinctive when it appears in at most 20 of the corpus's statements, which is under one percent of them. `.claude/plans/` sits at 14 and is the anchor the motivating case turns on, while `file` sits at 371 and would match most of the tree.
+
+A backticked token counts double. An author marking a span as code named an identifier rather than describing one, so `.claude/plans/archive/` says more about what a statement governs than any two prose words do. Two statements are one rule when their shared anchors reach a weight of 3.
+
+Every record names the anchors its match rested on, so a reader can weigh a finding instead of taking it.
+
+## The three classes
+
+- **Mirror.** Both files sit on a declared path pair whose duplication is deliberate. `CLAUDE.md` and the seed are the one pair, since the seed is authored from it and `claude-seed-sync` exists to reconcile the two. Excluding by pair rather than by content is the point: the duplication is a location fact this repository already records, and a content test would rediscover it on every run.
+- **Repetition.** Two surfaces state one rule and neither is declared a copy of the other.
+- **Contradiction.** The prohibition falls on one surface alone, on a match strong enough to read that as a disagreement. This is a polarity reading rather than a judgment about meaning, so weigh each against the surfaces it names.
+
+The contradiction floor sits above the match floor deliberately. A thin match says two statements touch the same subject, which is not enough to claim one forbids what the other prescribes, so a weak pair reports as a repetition and the loudest class is reserved for a pair sharing real identity.
+
+Two further rules decide where a prohibition counts, and both came out of false positives rather than from reasoning ahead of the corpus.
+
+Polarity is read off the clause the anchors landed in, and off the densest such clause rather than every one carrying an anchor. A statement states one rule across several clauses, so a union answers true whenever any clause anywhere carries a marker, which is the whole statement again under another name.
+
+The marker also has to open its clause, because an instruction leads with its verb. `Never delete a task file` prohibits where `a fallback never fires` reports, and no test reading the marker anywhere in the clause tells those apart. What that costs is a prohibition written mid-clause, which now reads as description and lands the pair in the repetition class, so both surfaces still reach the report and only the label is weaker.
+
+A mirror that disagrees stays a finding. The exclusion reaches a repetition alone, because the two files on a declared pair are meant to agree.
+
+## Which surface is authoritative
+
+Each restatement names where a later edit starts.
+
+- `claude-md` for a seed match, since the always-loaded file is authored first and the seed carries it to a target
+- `skill-body` where the subject names that skill, which is the content-ownership rule that behavior triggered only when editing one domain belongs to that domain's skill
+- `unknown` everywhere else, which is a first-class answer rather than a gap
+
+The ownership table assigns a cross-domain rule and a domain-triggered one, and reaches nothing stated in a skill body the always-loaded file never names. Guessing there would put a reader on a surface nobody decided.
+
+## Exit codes
+
+Exit codes are `0` when no instruction is restated outside a declared mirror, `1` for a refusal, and `2` for at least one restatement outside one. Mirrors move no exit code.
+
+Nothing wires this into `bun run check` or into a hook. A restatement is legitimate more often than not, and gating a measure whose ordinary result is a finding is what teaches contributors to route around the stage. `aitk gov test-order` and `aitk labels audit` are the siblings.
+
+Both refusals are absences rather than breaks. A target holds neither the seed nor a shipped skills tree, so `aitk audits run` reads `no-instructions` and `no-surfaces` as a corpus that is not there rather than a verb that failed.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `counts` rather than the exit when a skill consumes this.

package/governance/rules/claude/570-skill.md

@@ -12,6 +12,8 @@ paths:
 ## Before editing
 
 - Read the skill's sibling `REQUIREMENT.md` when one exists. If the change closes no gap it states, change the requirement first or drop the change.
+- Confirm `create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
+- Report it rather than proceeding silently when `create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
 
 ## After editing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/audits/catalog.ts

@@ -1,5 +1,6 @@
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { AuditRefusal } from '@/deps/audit'
+import type { RestatedRefusal } from '@/gov/restated'
 import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
 import type { ScanRefusal } from '@/secrets/scan'
@@ -356,6 +357,33 @@ function labelCoverageCounts(
   return allOf({ uncovered: lengthOf(root.uncovered) })
 }
 
+/**
+ * Reads the two classes that are findings, leaving the declared mirrors out.
+ *
+ * A mirror is an authoring root and its consumed copy, which duplicate on
+ * purpose, so folding them in would report a corpus getting worse every time a
+ * seed is kept in step with the file it is authored from. Same reasoning the
+ * label audit drops its declined rows on.
+ *
+ * The reach count is left out for a different reason. It counts how many
+ * surfaces an instruction reached rather than whether anything is wrong, and it
+ * moves in lockstep with the two retained here, so a baseline carrying it would
+ * report one movement twice.
+ */
+function restatedCounts(record: unknown): Record<string, number> | undefined {
+  const counts = asObject(asObject(record)?.counts)
+  if (counts === undefined) return undefined
+
+  return allOf({
+    contradictions:
+      typeof counts.contradictions === 'number'
+        ? counts.contradictions
+        : undefined,
+    repetitions:
+      typeof counts.repetitions === 'number' ? counts.repetitions : undefined,
+  })
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -548,6 +576,27 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-map'] satisfies LabelAuditRefusal[],
     counts: labelCoverageCounts,
   },
+  {
+    id: 'restated',
+    label: 'Restated instructions',
+    argv: ['gov', 'restated', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // a rule stated on two surfaces should be stated on one is a judgment the
+    // person owning the surface takes, and most restatements here are correct,
+    // so a push failing on one would fail on the ordinary case.
+    gatingExits: [],
+    corpus: 'tracked',
+    // Both reasons the sweep refuses for, and each is an absence rather than a
+    // break. A target holds neither the seed nor a shipped skills tree, so
+    // without the allowance every project installing this CLI reports the verb
+    // unmeasured on every run and never changes, which is the permanent signal
+    // the per-machine allowance exists against. Same shape as the reach verb.
+    absentReasons: [
+      'no-instructions',
+      'no-surfaces',
+    ] satisfies RestatedRefusal[],
+    counts: restatedCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/cli.ts

@@ -85,6 +85,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk sandbox git:commit`,
     `${GREY}│${NC}    aitk gov install react`,
     `${GREY}│${NC}    aitk gov sync ../my-app`,
+    `${GREY}│${NC}    aitk gov restated --json`,
     `${GREY}│${NC}    aitk standards markdown`,
     `${GREY}│${NC}    aitk snippets install base ../my-app`,
     `${GREY}│${NC}    aitk snippets sync ../my-app`,

package/src/commands/gov.ts

@@ -14,6 +14,15 @@ import {
   mergeExtraRules,
   resolveRules,
 } from '@/gov/stacks'
+import {
+  INSTRUCTIONS_REL,
+  type RestatedEntry,
+  type RestatedRefusal,
+  type RestatedReport,
+  readRestated,
+  SEED_REL,
+  SHIPPED_SKILLS_REL,
+} from '@/gov/restated'
 import {
   readSuperseded,
   SUPERSEDED_MARKER,
@@ -68,6 +77,17 @@ interface SupersededOptions {
   readonly json?: boolean
 }
 
+interface RestatedOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the sweep produced no reading. */
+const RESTATED_REFUSALS: Record<RestatedRefusal, string> = {
+  'no-instructions': `No ${INSTRUCTIONS_REL} here, or it carries no bullet, so there is no instruction corpus to sweep.`,
+  'no-surfaces': `Neither ${SEED_REL} nor ${SHIPPED_SKILLS_REL}/ is here, so no second surface exists to match against.`,
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -245,6 +265,146 @@ export function register(program: Command): void {
         process.exitCode = await runSuperseded(superseded, replacement, opts)
       },
     )
+
+  gov
+    .command('restated')
+    .description(
+      'Report every instruction the always-loaded file states that a second surface states too',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Matches every bullet in ${INSTRUCTIONS_REL} against ${SEED_REL}`,
+        `and every ${SHIPPED_SKILLS_REL}/*/SKILL.md body. Matching is recall-first,`,
+        'keyed on distinctive tokens two statements share rather than on a phrase',
+        'they spell the same way, because the case this exists for was one rule',
+        'written three different ways.',
+        '',
+        'What it separates:',
+        '  mirror         a declared authoring-to-consumed pair, where repeating is the design',
+        '  repetition     two surfaces state one rule and neither is declared a copy',
+        '  contradiction  the prohibition falls on one surface alone, on a strong match',
+        '',
+        'The contradiction class is a polarity reading rather than a judgment',
+        'about meaning, so weigh each against the surfaces it names.',
+        '',
+        'What it does not measure:',
+        '  a rule stated in two skill bodies and never in the always-loaded file,',
+        '  since the bullets there are the subjects and the bodies are searched',
+        '',
+        'Exit codes:',
+        '  0  no instruction is restated outside a declared mirror',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one instruction is restated outside a declared mirror',
+        '',
+        'Examples:',
+        '  aitk gov restated',
+        '  aitk gov restated --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: RestatedOptions) => {
+      process.exitCode = runRestated(opts)
+    })
+}
+
+/**
+ * Reports and never gates, matching the two sweeps above. A restatement is
+ * legitimate more often than not, so failing a push on one would fail on the
+ * ordinary case and teach contributors to route around the stage.
+ */
+function runRestated(opts: RestatedOptions): number {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = readRestated(root)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('aitk gov restated')
+    logStep('Refused')
+    logWarn(RESTATED_REFUSALS[report.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: RESTATED_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportRestated(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...report })}\n`)
+  }
+
+  const findings = report.counts.contradictions + report.counts.repetitions
+  return findings > 0 ? 2 : 0
+}
+
+function describeEntry(entry: RestatedEntry): string[] {
+  const lines = [`${entry.subject.file}:${entry.subject.line}`]
+
+  for (const surface of entry.surfaces) {
+    lines.push(
+      `  [${surface.restatement}] ${surface.file}:${surface.line} via ${surface.anchors.join(', ')}`,
+    )
+  }
+
+  return lines
+}
+
+function reportRestated(
+  report: Extract<RestatedReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov restated')
+
+  // A count of what matched reads as a verdict on the repository unless the run
+  // also says how wide the corpus behind it was.
+  logStep('Corpus')
+  logInfo(
+    `${report.corpus.instructions} instruction(s) against ${report.corpus.candidates} statement(s) from the seed and ${report.corpus.bodies} shipped body/bodies in ${root}`,
+  )
+  logInfo(
+    `matched on ${report.matcher.anchors} weighted anchor(s), dropping any token in more than ${report.matcher.common} statements`,
+  )
+
+  // Named rather than counted. A polarity split is the only class claiming a
+  // defect, and a reader weighing one has to reach both surfaces.
+  logStep(
+    report.counts.contradictions === 0 ? 'No contradiction' : 'Contradictions',
+  )
+  if (report.counts.contradictions === 0) {
+    logInfo('no restatement puts a prohibition on one surface alone')
+  } else {
+    for (const entry of report.restatements) {
+      const carries = entry.surfaces.some(
+        (surface) => surface.restatement === 'contradiction',
+      )
+      if (!carries) continue
+      for (const line of describeEntry(entry)) logWarn(line)
+    }
+  }
+
+  logStep('Restated')
+  logInfo(
+    `${report.counts.repetitions} repetition(s) outside a declared mirror, and ${report.counts.mirrors} on one`,
+  )
+  logInfo(
+    `${report.counts.threeSurface} instruction(s) reach three surfaces or more`,
+  )
+
+  outro()
 }
 
 /**

package/src/gov/restated.ts

@@ -0,0 +1,688 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The always-loaded file whose bullets are the subjects this sweep matches. */
+export const INSTRUCTIONS_REL = 'CLAUDE.md'
+
+/** The seed a target receives, authored from the file above. */
+export const SEED_REL = join('tooling', 'claude', 'seeds', 'CLAUDE.md')
+
+/** The shipped plugin bodies, which is where a rule restated in prose lands. */
+export const SHIPPED_SKILLS_REL = join('claude', 'skills')
+
+/**
+ * Path pairs whose duplication is deliberate and already recorded.
+ *
+ * The seed is authored from the always-loaded file and `claude-seed-sync`
+ * exists to reconcile the two, so a bullet appearing in both is the design
+ * rather than a defect. Excluding by pair rather than by content is what the
+ * plan settled on: the duplication is a location fact this repository already
+ * records, and a content test would have to rediscover it on every run.
+ *
+ * The exclusion reaches a repetition alone. A mirror that disagrees is the one
+ * shape the pairing cannot absorb, since the two files are meant to agree, so
+ * a polarity split on a declared pair stays a finding.
+ */
+const MIRRORS: readonly (readonly [string, string])[] = [
+  [INSTRUCTIONS_REL, SEED_REL],
+]
+
+/**
+ * A token appearing in more than this many statements carries no signal.
+ *
+ * Under one percent of the 2750 statements this repository offers. Tuned
+ * against that corpus rather than reasoned to, which is what the plan asked of
+ * the first run: `.claude/plans/` sits at 14 and is the anchor the motivating
+ * case turns on, while `file` sits at 371 and matches most of the tree.
+ */
+export const COMMON_CEILING = 20
+
+/** Weight two statements must share before they are read as one rule. */
+export const ANCHOR_FLOOR = 3
+
+/**
+ * What a backticked token is worth against a plain word.
+ *
+ * An author marking a span as code named an identifier rather than describing
+ * one, so `.claude/plans/archive/` says more about what a statement governs
+ * than any two prose words do. Weighting it is what lets the floor rise high
+ * enough to drop a coincidental word pair without losing a rule two surfaces
+ * spelled entirely differently around one shared path.
+ */
+const SPAN_WEIGHT = 2
+
+/**
+ * Weight a match needs before a polarity split is called a contradiction.
+ *
+ * Above the match floor on purpose. A thin match says two statements touch the
+ * same subject, which is not enough to claim one forbids what the other
+ * prescribes, so a weak pair reports as a repetition and the loudest class is
+ * reserved for a pair sharing real identity.
+ */
+export const CONTRADICTION_FLOOR = 5
+
+/**
+ * Words carrying no subject, dropped before anchors are counted.
+ *
+ * Short rather than exhaustive. The document-frequency ceiling above removes
+ * the rest on its own, and a hand-written list long enough to do that job
+ * would be a second corpus nobody maintains.
+ */
+const STOPWORDS = new Set([
+  'about',
+  'after',
+  'against',
+  'already',
+  'also',
+  'and',
+  'any',
+  'are',
+  'because',
+  'been',
+  'before',
+  'being',
+  'both',
+  'but',
+  'can',
+  'each',
+  'either',
+  'else',
+  'every',
+  'for',
+  'from',
+  'has',
+  'have',
+  'her',
+  'here',
+  'his',
+  'how',
+  'into',
+  'its',
+  'itself',
+  'more',
+  'most',
+  'much',
+  'must',
+  'once',
+  'one',
+  'only',
+  'other',
+  'our',
+  'out',
+  'over',
+  'own',
+  'per',
+  'rather',
+  'same',
+  'she',
+  'should',
+  'since',
+  'some',
+  'such',
+  'than',
+  'that',
+  'the',
+  'their',
+  'them',
+  'then',
+  'there',
+  'these',
+  'they',
+  'this',
+  'those',
+  'through',
+  'too',
+  'under',
+  'until',
+  'upon',
+  'very',
+  'was',
+  'were',
+  'what',
+  'when',
+  'where',
+  'which',
+  'while',
+  'who',
+  'whose',
+  'why',
+  'will',
+  'with',
+  'would',
+  'you',
+  'your',
+])
+
+/**
+ * Markers reading as a prohibition, which is the one polarity signal available
+ * without understanding the sentence.
+ *
+ * Deliberately narrow. `no` and `not` are excluded because both appear inside
+ * ordinary qualifying clauses, and widening the set turns most of the corpus
+ * into a suspected contradiction.
+ */
+const PROHIBITIONS = ['never', 'do not', "don't", 'avoid', 'refuse']
+
+export type RestatedRefusal = 'no-instructions' | 'no-surfaces'
+
+export type Restatement = 'mirror' | 'repetition' | 'contradiction'
+
+/** Which surface a restatement was found on, before any class is assigned. */
+export type SurfaceKind = 'seed' | 'skill'
+
+/**
+ * Which surface a later edit starts from.
+ *
+ * `unknown` is a first-class answer rather than a gap. The content-ownership
+ * table assigns a cross-domain rule and a domain-triggered one, and reaches
+ * nothing stated in a skill body the always-loaded file never names, so
+ * guessing there would put a reader on a surface nobody decided.
+ */
+export type Authority = 'claude-md' | 'skill-body' | 'unknown'
+
+export interface Statement {
+  /** Repository-relative, so a record reads the same from any working root. */
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly text: string
+}
+
+export interface Surface extends Statement {
+  readonly kind: SurfaceKind
+  readonly restatement: Restatement
+  /** The distinctive tokens this match rested on, so a finding is auditable. */
+  readonly anchors: readonly string[]
+  /** Those anchors scored, with a backticked one counting double. */
+  readonly weight: number
+  readonly authority: Authority
+  /** Why the class and the authority read the way they do. */
+  readonly reason: string
+}
+
+export interface RestatedEntry {
+  readonly subject: Statement
+  readonly surfaces: readonly Surface[]
+}
+
+export interface RestatedCounts {
+  readonly contradictions: number
+  readonly repetitions: number
+  readonly mirrors: number
+  /** Subjects carried by two further surfaces, which is the title's count. */
+  readonly threeSurface: number
+}
+
+export type RestatedReport =
+  | {
+      readonly kind: 'measured'
+      readonly corpus: {
+        readonly instructions: number
+        readonly seed: number
+        readonly bodies: number
+        /** Statements the two further surfaces offered, which bounds recall. */
+        readonly candidates: number
+      }
+      readonly matcher: {
+        readonly anchors: number
+        readonly common: number
+        readonly contradiction: number
+      }
+      readonly restatements: readonly RestatedEntry[]
+      readonly counts: RestatedCounts
+    }
+  | { readonly kind: 'unreadable'; readonly reason: RestatedRefusal }
+
+interface Candidate extends Statement {
+  readonly kind: SurfaceKind
+  /** The skill folder this statement sits in, present on a body alone. */
+  readonly skill?: string
+}
+
+export interface Analysis {
+  readonly tokens: ReadonlySet<string>
+  /** The subset an author backticked, which weighs more than a plain word. */
+  readonly spans: ReadonlySet<string>
+}
+
+/** A statement paired with the tokens it carries. */
+interface Indexed<T extends Statement> {
+  readonly statement: T
+  readonly analysis: Analysis
+}
+
+/**
+ * Splits text into the tokens an anchor can be drawn from.
+ *
+ * A code span keeps its inner text whole, since `.claude/plans/archive/` is the
+ * strongest anchor this corpus offers and splitting it on the punctuation would
+ * leave three words every second bullet also carries.
+ */
+export function analyze(text: string): Analysis {
+  const spans: string[] = []
+  const withoutSpans = text.replace(/`([^`]+)`/g, (_match, inner: string) => {
+    spans.push(inner.toLowerCase())
+    return ' '
+  })
+
+  const words = withoutSpans
+    .toLowerCase()
+    .replace(/\[([^\]]*)\]\(([^)]*)\)/g, '$1 $2')
+    .split(/[^a-z0-9/._<>-]+/)
+    .map((word) => word.replace(/^[-._/]+|[-._/,;:]+$/g, ''))
+
+  const keep = (token: string): boolean =>
+    token.length >= 3 && !STOPWORDS.has(token)
+
+  return {
+    tokens: new Set([...spans, ...words].filter(keep)),
+    spans: new Set(spans.filter(keep)),
+  }
+}
+
+/**
+ * Whether a clause instructs against something, rather than merely describing
+ * something that does not happen.
+ *
+ * The marker has to open the clause. A prohibition is an instruction, and an
+ * instruction leads with its verb, so `Never delete a task file` prohibits
+ * where `a fallback never fires` reports. Reading the marker anywhere in the
+ * clause cannot separate those two, and this corpus writes both: the third
+ * false contradiction found here was `so a || fallback never fires` against a
+ * seed clause saying the same thing in other words.
+ *
+ * What it costs is a prohibition written mid-clause, as in `edit with the tool,
+ * never a stream editor`, which now reads as description. That miss lands the
+ * pair in the repetition class rather than dropping it, so both surfaces still
+ * reach the report and only the label is weaker.
+ */
+function prohibits(text: string): boolean {
+  const opening = text
+    .toLowerCase()
+    .replace(/^[^a-z]*/, '')
+    .replace(/^(and|but|so|then|also|however)[\s,]+/, '')
+
+  return PROHIBITIONS.some((marker) => opening.startsWith(marker))
+}
+
+/**
+ * The clauses a statement's polarity is read against.
+ *
+ * The trailing span is kept, where `splitSentences` in `src/markdown/structure.ts`
+ * drops one no punctuation closes. A bullet routinely ends without a period and
+ * its last clause is routinely the one carrying the prohibition, so dropping it
+ * would lose exactly the half this reads. The two contracts differ, which is why
+ * this is a second splitter rather than a shared one.
+ */
+function clauses(text: string): string[] {
+  return text
+    .split(/(?<=[.!?])\s+/)
+    .map((clause) => clause.trim())
+    .filter((clause) => clause !== '')
+}
+
+/**
+ * The clause a match landed in, which is where a prohibition has to sit before
+ * it says anything about the rule the two statements share.
+ *
+ * The densest clause rather than every clause carrying an anchor. A statement
+ * states one rule across several clauses, and a union answers true whenever any
+ * clause anywhere carries a marker, which is the whole statement again under
+ * another name.
+ *
+ * Both contradictions this repository reported were that defect. The
+ * always-loaded file splits the stream-editor rule across two bullets and the
+ * seed folds them into one, so the subject was the exception half alone while
+ * the seed's bullet carried the `never` from a clause the anchors never
+ * touched, and the two agreed completely.
+ */
+function anchoredClause(text: string, anchors: ReadonlySet<string>): string {
+  const parts = clauses(text)
+  if (parts.length <= 1) return text
+
+  let best = text
+  let bestHits = 0
+
+  for (const part of parts) {
+    const tokens = analyze(part).tokens
+    let hits = 0
+    for (const anchor of anchors) if (tokens.has(anchor)) hits += 1
+
+    if (hits > bestHits) {
+      bestHits = hits
+      best = part
+    }
+  }
+
+  // No clause carries an anchor, which a boundary landing inside a code span
+  // can produce. Reading the whole statement is what this did before the clause
+  // scope, so it degrades to that rather than to no polarity at all.
+  return bestHits === 0 ? text : best
+}
+
+function isMirrorPair(subject: string, surface: string): boolean {
+  return MIRRORS.some(
+    ([left, right]) =>
+      (subject === left && surface === right) ||
+      (subject === right && surface === left),
+  )
+}
+
+/**
+ * Bullets at the top level of a markdown file, which is the unit an instruction
+ * takes in the always-loaded file and in the seed.
+ */
+function readBullets(root: string, relative: string): Statement[] {
+  const full = join(root, relative)
+  if (!existsSync(full)) return []
+
+  const statements: Statement[] = []
+  let fenced = false
+
+  readFileSync(full, 'utf8')
+    .split('\n')
+    .forEach((line, index) => {
+      if (line.trimStart().startsWith('```')) {
+        fenced = !fenced
+        return
+      }
+      if (fenced || !line.startsWith('- ')) return
+
+      statements.push({
+        file: relative.replaceAll('\\', '/'),
+        line: index + 1,
+        text: line.slice(2).trim(),
+      })
+    })
+
+  return statements
+}
+
+/**
+ * Every prose line and bullet in a shipped body.
+ *
+ * Wider than the bullet rule above because the motivating case was stated in a
+ * body as a paragraph, so a bullet-only read would miss the one instance this
+ * sweep exists for. Headings, tables, and fenced blocks are read past: a
+ * heading names a section rather than stating a rule, and a fenced block is an
+ * example whose words are the surrounding prose's by construction.
+ */
+function readBodyLines(root: string, skillsRoot: string): Candidate[] {
+  const candidates: Candidate[] = []
+
+  const files = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({
+      cwd: skillsRoot,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  for (const file of files) {
+    const posix = file.replaceAll('\\', '/')
+    const skill = posix.split('/')[0]
+    const relative = `${SHIPPED_SKILLS_REL.replaceAll('\\', '/')}/${posix}`
+
+    const lines = readFileSync(join(root, relative), 'utf8').split('\n')
+    let fenced = false
+    let frontmatter = lines[0]?.trim() === '---'
+
+    for (const [index, line] of lines.entries()) {
+      const trimmed = line.trim()
+
+      // Frontmatter is metadata rather than instruction, and every body's
+      // `description` restates that skill's own purpose, so sweeping it makes
+      // each skill match any subject naming its domain.
+      if (frontmatter) {
+        if (index > 0 && trimmed === '---') frontmatter = false
+        continue
+      }
+
+      if (trimmed.startsWith('```')) {
+        fenced = !fenced
+        continue
+      }
+      if (fenced || trimmed === '') continue
+      if (trimmed.startsWith('#') || trimmed.startsWith('|')) continue
+      if (trimmed.startsWith('---')) continue
+
+      candidates.push({
+        file: relative,
+        line: index + 1,
+        text: trimmed.replace(/^[-*>]\s+/, ''),
+        kind: 'skill',
+        skill,
+      })
+    }
+  }
+
+  return candidates
+}
+
+/** How many statements each token appears in, which is what rarity is read off. */
+function documentFrequency(
+  groups: readonly (readonly Indexed<Statement>[])[],
+): Map<string, number> {
+  const frequency = new Map<string, number>()
+
+  for (const group of groups) {
+    for (const entry of group) {
+      for (const token of entry.analysis.tokens) {
+        frequency.set(token, (frequency.get(token) ?? 0) + 1)
+      }
+    }
+  }
+
+  return frequency
+}
+
+function index<T extends Statement>(statement: T): Indexed<T> {
+  return { statement, analysis: analyze(statement.text) }
+}
+
+/**
+ * Which surface a later edit starts from, and why.
+ *
+ * A skill body earns authority only where the subject names that skill, which
+ * is the content-ownership table's rule that behavior triggered when editing
+ * domain X belongs to X's skill. Everything else the table does not reach is
+ * reported as unknown.
+ */
+function authorityFor(
+  subject: Statement,
+  candidate: Candidate,
+): { authority: Authority; reason: string } {
+  if (candidate.kind === 'seed') {
+    return {
+      authority: 'claude-md',
+      reason: `${INSTRUCTIONS_REL} is authored first and the seed carries it to a target, so an edit starts there and reaches the seed through claude-seed-sync`,
+    }
+  }
+
+  if (
+    candidate.skill !== undefined &&
+    subject.text.toLowerCase().includes(candidate.skill.toLowerCase())
+  ) {
+    return {
+      authority: 'skill-body',
+      reason: `the subject names ${candidate.skill}, and behavior triggered only when editing one domain belongs to that domain's skill`,
+    }
+  }
+
+  return {
+    authority: 'unknown',
+    reason:
+      'the content-ownership table assigns a cross-domain rule and a domain-triggered one, and reaches neither from here',
+  }
+}
+
+function classify(
+  subject: Statement,
+  candidate: Candidate,
+  weight: number,
+  anchors: ReadonlySet<string>,
+): { restatement: Restatement; reason: string } {
+  const split =
+    prohibits(anchoredClause(subject.text, anchors)) !==
+    prohibits(anchoredClause(candidate.text, anchors))
+
+  if (split && weight >= CONTRADICTION_FLOOR) {
+    return {
+      restatement: 'contradiction',
+      reason:
+        'the clause each surface was matched on states this as a prohibition on one side alone, which is a polarity reading rather than a judgment about meaning',
+    }
+  }
+
+  if (isMirrorPair(subject.file, candidate.file)) {
+    return {
+      restatement: 'mirror',
+      reason:
+        'both files sit on a declared mirror pair, where repeating the rule is the design',
+    }
+  }
+
+  return {
+    restatement: 'repetition',
+    reason: split
+      ? 'the matched clause carries a prohibition on one surface alone, on a match too thin to read that as a disagreement'
+      : 'two surfaces state one rule and neither is declared a copy of the other',
+  }
+}
+
+/**
+ * Every instruction in the always-loaded file that a second surface also states.
+ *
+ * Matching is recall-first, keyed on distinctive tokens two statements share
+ * rather than on a phrase they spell the same way. The motivating case was one
+ * rule written three different ways, so a near-exact matcher would miss the
+ * defect the sweep exists for, and a recall-first reading can be narrowed from
+ * real output where the reverse cannot.
+ *
+ * It reports and never gates. A restatement is legitimate more often than not,
+ * so a push failing on one would fail on the ordinary case.
+ */
+export function readRestated(root: string): RestatedReport {
+  const instructions = readBullets(root, INSTRUCTIONS_REL)
+  if (instructions.length === 0) {
+    return { kind: 'unreadable', reason: 'no-instructions' }
+  }
+
+  const seed: Candidate[] = readBullets(root, SEED_REL).map((statement) => ({
+    ...statement,
+    kind: 'seed' as const,
+  }))
+
+  const skillsRoot = join(root, SHIPPED_SKILLS_REL)
+  const bodies = existsSync(skillsRoot) ? readBodyLines(root, skillsRoot) : []
+
+  const bodyFiles = new Set(bodies.map((candidate) => candidate.file)).size
+  if (seed.length === 0 && bodies.length === 0) {
+    return { kind: 'unreadable', reason: 'no-surfaces' }
+  }
+
+  const subjects = instructions.map(index)
+  const candidates = [...seed, ...bodies].map(index)
+  const frequency = documentFrequency([subjects, candidates])
+
+  const distinctive = (analysis: Analysis): Set<string> =>
+    new Set(
+      [...analysis.tokens].filter(
+        (token) => (frequency.get(token) ?? 0) <= COMMON_CEILING,
+      ),
+    )
+
+  // Every candidate's rare set is invariant across the subject loop, so it is
+  // built once here rather than per pair. The corpora multiply out to hundreds
+  // of thousands of pairings, and rebuilding a set inside that is the shape
+  // `.claude/rules/core/040-performance.md` names.
+  const rareCandidates = candidates.map((candidate) => ({
+    ...candidate,
+    rare: distinctive(candidate.analysis),
+  }))
+
+  const restatements: RestatedEntry[] = []
+  let contradictions = 0
+  let repetitions = 0
+  let mirrors = 0
+  let threeSurface = 0
+
+  for (const subject of subjects) {
+    const rare = distinctive(subject.analysis)
+    const surfaces: Surface[] = []
+
+    for (const candidate of rareCandidates) {
+      const shared = [...candidate.rare]
+        .filter((token) => rare.has(token))
+        .sort()
+
+      const weight = shared.reduce(
+        (total, token) =>
+          total +
+          (subject.analysis.spans.has(token) &&
+          candidate.analysis.spans.has(token)
+            ? SPAN_WEIGHT
+            : 1),
+        0,
+      )
+
+      if (weight < ANCHOR_FLOOR) continue
+
+      const { restatement, reason } = classify(
+        subject.statement,
+        candidate.statement,
+        weight,
+        new Set(shared),
+      )
+      const { authority, reason: why } = authorityFor(
+        subject.statement,
+        candidate.statement,
+      )
+
+      surfaces.push({
+        file: candidate.statement.file,
+        line: candidate.statement.line,
+        text: candidate.statement.text,
+        kind: candidate.statement.kind,
+        restatement,
+        anchors: shared,
+        weight,
+        authority,
+        reason: `${reason}; ${why}`,
+      })
+    }
+
+    if (surfaces.length === 0) continue
+
+    for (const surface of surfaces) {
+      if (surface.restatement === 'contradiction') contradictions += 1
+      else if (surface.restatement === 'mirror') mirrors += 1
+      else repetitions += 1
+    }
+
+    // Every surface counts here, a declared mirror included. The motivating
+    // case was the always-loaded file, the seed, and a body, so dropping the
+    // mirror would read that exact shape as a rule stated twice. The mirror
+    // exclusion is a rule about which class is a finding, not about how far an
+    // instruction reached.
+    if (surfaces.length >= 2) threeSurface += 1
+
+    restatements.push({ subject: subject.statement, surfaces })
+  }
+
+  return {
+    kind: 'measured',
+    corpus: {
+      instructions: instructions.length,
+      seed: seed.length,
+      bodies: bodyFiles,
+      candidates: candidates.length,
+    },
+    matcher: {
+      anchors: ANCHOR_FLOOR,
+      common: COMMON_CEILING,
+      contradiction: CONTRADICTION_FLOOR,
+    },
+    restatements,
+    counts: { contradictions, repetitions, mirrors, threeSurface },
+  }
+}

package/standards/skill.md

@@ -21,6 +21,7 @@ Does not govern:
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
 - The domain conventions a skill cites, each of which belongs to the standard that owns it
+- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the clause in `570-skill.md`
 
 ## Changing a skill