@erclx/aitk 0.22.1 → 0.24.0

package/src/sandbox/census.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { collectCoverage, type CoverageReport } from '@/sandbox/coverage'
+
+/**
+ * Holds the exemption declarations, beside the scenario categories rather than
+ * inside one. `listScenarios` in `coverage.ts` walks directories only, so a file
+ * at that level joins no category and never reads as a scenario.
+ */
+const EXEMPT_FILE = 'exempt.toml'
+
+export type SkillVerdict = 'asserted' | 'should-be-asserted' | 'exempt'
+
+export interface SkillCensusEntry {
+  readonly skill: string
+  readonly verdict: SkillVerdict
+  /**
+   * Every `<category>:<command>` pairing to this skill, empty when none does.
+   * Plural because the mapping is many-to-one: two scenarios can drive one
+   * skill, and naming only the first would credit its arms to the wrong file.
+   */
+  readonly scenarios: readonly string[]
+  /**
+   * Each armed arm as `<category>:<command>/<arm>`. Qualified rather than bare,
+   * because a skill two scenarios drive can hold two arms of the same name and
+   * a bare list renders them as one label twice. Deduplicating instead would
+   * read as one arm where two assert, which understates in the one direction
+   * this report exists to keep honest.
+   */
+  readonly armed: readonly string[]
+  /** Why no arm asserts this skill. Present only on `exempt`. */
+  readonly reason?: string
+}
+
+export interface CensusReport {
+  readonly skills: readonly SkillCensusEntry[]
+  readonly totalSkills: number
+  readonly asserted: number
+  readonly shouldBeAsserted: number
+  readonly exempt: number
+  /** Exemptions naming a skill the tree does not carry. */
+  readonly staleExemptions: readonly string[]
+  /**
+   * Exemptions on a skill an arm now asserts. The claim is wrong in the one
+   * direction a verdict decays, and the entry outranks nothing, so dropping it
+   * silently leaves committed data nobody is told to delete.
+   */
+  readonly supersededExemptions: readonly string[]
+}
+
+function directories(path: string): string[] {
+  if (!existsSync(path)) return []
+
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/**
+ * Every skill the plugin ships, which is the census denominator. Reads the
+ * authoring root rather than `.claude/skills/`, since the latter holds
+ * toolkit-internal skills that reach no target and would inflate the count.
+ */
+export function listSkills(root: string): string[] {
+  return directories(join(root, 'claude', 'skills'))
+}
+
+/**
+ * Maps a scenario to the skill it drives, trying two spellings in order.
+ *
+ * `<category>-<command>` is the rule `.claude/context/sandbox.md` states, and it
+ * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
+ * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
+ * `claude-setup-init` that does not exist. Stating one spelling and shipping two
+ * is what let the audit report a paired skill as unpaired.
+ *
+ * Returns undefined for a scenario driving no skill at all, which is every
+ * `infra/` and `tooling/` scenario. Those exercise a CLI domain rather than a
+ * skill and belong to the scenario count, not to this one.
+ */
+export function skillForScenario(
+  category: string,
+  command: string,
+  skills: ReadonlySet<string>,
+): string | undefined {
+  const prefixed = `${category}-${command}`
+  if (skills.has(prefixed)) return prefixed
+  if (skills.has(command)) return command
+
+  return undefined
+}
+
+/**
+ * Reads the exemption declarations, keyed by skill with a `reason` each.
+ *
+ * The reason cannot live in the arm's `manual` array, which is where `#723` put
+ * prose a checker could not assert. `resolveVerdict` fails any declaration
+ * carrying zero mechanical assertions, so an `expect.toml` holding only an
+ * exempt reason goes red at the moment it is written. An exempt skill has no
+ * assertion to pair the prose with, which is what makes it exempt, so the two
+ * cases cannot share a home.
+ *
+ * Throws on a malformed file and on a table carrying no usable `reason`, rather
+ * than reporting a smaller set. Both losses are invisible downstream: the skill
+ * reclassifies to should-be-asserted and rejoins a work queue someone already
+ * ruled it out of, with nothing naming the entry that stopped counting. This is
+ * the stray-key rule `contentArray` applies in `expect.ts` for the same reason,
+ * where the declaration is well-formed and silently lost a key it appears to
+ * carry. `runCoverage` catches both and frames them.
+ */
+export function parseExemptions(source: string): Map<string, string> {
+  const parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  const exemptions = new Map<string, string>()
+
+  for (const [skill, value] of Object.entries(parsed)) {
+    if (typeof value !== 'object' || value === null) {
+      throw new Error(
+        `exemption ${skill} is not a table. Write [${skill}] with a reason below it.`,
+      )
+    }
+
+    const reason = (value as Record<string, unknown>).reason
+    if (typeof reason !== 'string' || reason === '') {
+      throw new Error(
+        `exemption ${skill} declares no reason. An exemption without one cannot be checked or overturned.`,
+      )
+    }
+
+    exemptions.set(skill, reason)
+  }
+
+  return exemptions
+}
+
+function readExemptions(root: string): Map<string, string> {
+  const path = join(root, 'scripts', 'sandbox', EXEMPT_FILE)
+  if (!existsSync(path)) return new Map()
+
+  return parseExemptions(readFileSync(path, 'utf8'))
+}
+
+/**
+ * Gives every shipped skill an asserted, should-be-asserted, or exempt verdict
+ * against declared expectations rather than against a scenario existing.
+ *
+ * A paired scenario is not an asserted skill. A scenario with no `expect.toml`
+ * provisions a state and prints a human-readable `Expect:` line, so a run over
+ * it exits zero having proved nothing. Counting pairs would report coverage the
+ * suite does not have, which is the measure this report exists to replace.
+ *
+ * An armed arm outranks an exemption. A skill listed exempt that acquired an arm
+ * is asserted in fact, and reporting the stale claim instead would hide the one
+ * direction the verdict decays in.
+ */
+export function collectCensus(
+  root: string,
+  coverage: CoverageReport = collectCoverage(root),
+): CensusReport {
+  const skills = listSkills(root)
+  const known = new Set(skills)
+  const exemptions = readExemptions(root)
+
+  const pairings = new Map<string, { scenarios: string[]; armed: string[] }>()
+  for (const scenario of coverage.scenarios) {
+    const skill = skillForScenario(scenario.category, scenario.command, known)
+    if (skill === undefined) continue
+
+    // Accumulate rather than assign. Dropping a second scenario would report a
+    // skill unarmed while an arm under the other spelling asserts it.
+    const pair = `${scenario.category}:${scenario.command}`
+    const existing = pairings.get(skill) ?? { scenarios: [], armed: [] }
+    existing.scenarios.push(pair)
+    existing.armed.push(...scenario.armed.map((arm) => `${pair}/${arm}`))
+    pairings.set(skill, existing)
+  }
+
+  const entries = skills.map((skill): SkillCensusEntry => {
+    const pairing = pairings.get(skill)
+    const scenarios = pairing?.scenarios ?? []
+    const armed = pairing?.armed ?? []
+    const reason = exemptions.get(skill)
+
+    if (armed.length > 0) {
+      return { skill, verdict: 'asserted', scenarios, armed }
+    }
+
+    if (reason !== undefined) {
+      return { skill, verdict: 'exempt', scenarios, armed, reason }
+    }
+
+    return { skill, verdict: 'should-be-asserted', scenarios, armed }
+  })
+
+  // An exemption outranked by an arm is as wrong as one naming no skill, and it
+  // is the case the armed-wins rule creates rather than one the tree arrives
+  // with. Reading `entries` rather than recomputing keeps the two in step, so a
+  // change to the precedence cannot leave the report contradicting the verdict.
+  const assertedSkills = new Set(
+    entries.filter((e) => e.verdict === 'asserted').map((e) => e.skill),
+  )
+
+  return {
+    skills: entries,
+    totalSkills: entries.length,
+    asserted: assertedSkills.size,
+    shouldBeAsserted: entries.filter((e) => e.verdict === 'should-be-asserted')
+      .length,
+    exempt: entries.filter((e) => e.verdict === 'exempt').length,
+    staleExemptions: [...exemptions.keys()]
+      .filter((skill) => !known.has(skill))
+      .sort(),
+    supersededExemptions: [...exemptions.keys()]
+      .filter((skill) => assertedSkills.has(skill))
+      .sort(),
+  }
+}
+
+/**
+ * Whole percent, floored, over skills rather than scenarios. Floored for the
+ * reason `coveragePercent` is: the number exists to look worse than a wall of
+ * green does.
+ */
+export function assertedPercent(report: CensusReport): number {
+  if (report.totalSkills === 0) return 0
+
+  return Math.floor((report.asserted / report.totalSkills) * 100)
+}

package/standards/architecture.md

@@ -7,6 +7,16 @@ description: Shape and content rules for .claude/ARCHITECTURE.md
 
 Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
 
+## Scope
+
+Governs the system-shape document at `.claude/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
+
+Does not govern:
+
+- Per-domain structure and narrative: `context.md`
+- Setup commands and install instructions: `readme.md`
+- Product scope, goals, and non-goals: `requirements.md`
+
 ## What goes in
 
 - A high-level overview of how the system is structured and why
@@ -15,8 +25,6 @@ Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisio
 
 ## What does not go in
 
-- Per-domain structure and narrative. That belongs in `.claude/context/<domain>.md`, one file per domain.
-- Setup commands and install instructions. Those live in the README.
 - How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
 

package/standards/bundled/branch.md

@@ -1,11 +1,22 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
+consumers: git-branch, git-split, git-pr
 ---
 
 # Branch reference
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

package/standards/bundled/commit.md

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

package/standards/bundled/issue.md

@@ -6,6 +6,16 @@ consumers: git-issue
 
 # Issue reference
 
+## Scope
+
+Governs a tracker issue: its title, its labels, and the sections its body carries.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in issue text: `versioning.md`
+- Voice, punctuation, and banned words in issue prose: `prose.md`
+
 ## Title
 
 - Format: `<type>: <subject>`

package/standards/bundled/pr.md

@@ -1,11 +1,22 @@
 ---
 title: Pull request reference
 description: Pull request title and body conventions
-consumers: git-split, git-pr, claude-standards-audit
+consumers: git-split, git-pr
 ---
 
 # Pull request reference
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

package/standards/bundled/roadmap.md

@@ -10,6 +10,17 @@ Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.
 
 The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
 
+## Scope
+
+Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
+
+Does not govern:
+
+- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
+- Task files, outcomes, and board state: `tasks.md`
+- Phase-label format and semver discipline: `versioning.md`
+- Rationale for a technical choice: `architecture.md`
+
 ## What goes in
 
 - One row per version, ordered top to bottom by sequence
@@ -20,9 +31,8 @@ The roadmap is one scannable table. That is what keeps it distinct from `.claude
 
 ## What does not go in
 
-- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Task breakdown, checkboxes, or per-feature file lists
 - Implementation detail, API names, or component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Sentence-long cells. Keep each cell terse so the table stays scannable.
 
 ## Format

package/standards/bundled/snippets.md

@@ -6,6 +6,15 @@ consumers: create-standard
 
 # Snippet reference
 
+## Scope
+
+Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+
+Does not govern:
+
+- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
+- Voice, punctuation, and formatting in snippet prose: `prose.md`
+
 ## What a snippet is
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.

package/standards/context.md

@@ -7,6 +7,17 @@ description: Shape and content rules for .claude/context/<domain>.md entries
 
 Applies to per-domain narrative entries under `.claude/context/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`.
 
+## Scope
+
+Governs per-domain narrative entries under `.claude/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
+
+Does not govern:
+
+- Cross-domain decisions and system-wide risks: `architecture.md`
+- Product scope, goals, and non-goals: `requirements.md`
+- Path-scoped coding rules: `rule.md`
+- Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+
 ## Organizing principle
 
 Weight the entry toward what cannot be re-derived from the repo. That single rule sorts every section below.

package/standards/design.md

@@ -7,6 +7,15 @@ description: Shape and content rules for .claude/DESIGN.md
 
 Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
 
+## Scope
+
+Governs the visual-intent document at `.claude/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
+
+Does not govern:
+
+- Screen layout, on-screen copy, and interaction intent: `wireframes.md`
+- Per-domain implementation narrative: `context.md`
+
 ## What goes in
 
 - Tokens described as intent ("mid gray, muted text"), not computed values. Exact values live in code.
@@ -17,7 +26,6 @@ Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind
 ## What does not go in
 
 - CSS classes, computed values, component filenames, and prop names. Those live in code.
-- UX copy and interaction flows. Those live in the wireframes.
 - Anything that needs updating every time the code is refactored
 
 ## Format

package/standards/diagrams.md

@@ -9,6 +9,17 @@ Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, whic
 
 A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
 
+## Scope
+
+Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield `prose.md` grants a surface whose own standard sets one.
+
+Does not govern:
+
+- Punctuation, formatting, and language in explanation prose and node labels: `prose.md`, whose bans the yield does not lift
+- The mechanism behind any component a diagram draws: `context.md`
+- UI layout, on-screen copy, and interaction intent: `wireframes.md`
+- The decision record a components diagram is drawn from: `architecture.md`
+
 ## What a working entry looks like
 
 An entry works when a reader who has not opened the repository can answer its question:
@@ -82,7 +93,7 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 - Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
 - The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
 
-This section states the voice for the surface, which is what claims the yield `standards/prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force, and the standards-audit hook enforces them on every write.
+This section states the voice for the surface, which is what claims the yield `prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force.
 
 ## Verification
 
@@ -109,5 +120,5 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
 - The `claude-docs` sweep watches two things and writes frontmatter only. It appends `stale` when a path an entry cites leaves the tree, and it stubs a kind when a diff adds the source signal that kind is drawn from. Diagram bodies and explanation paragraphs are off limits to it, because a change that removes a module does not carry the new correct shape of the picture.
 - That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
-- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
+- The explanation paragraphs around a Mermaid block are prose and follow `prose.md`. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/prose.md

@@ -7,6 +7,17 @@ description: Voice, structure, formatting, and language rules for reference mark
 
 Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. Punctuation, formatting, and language rules below stay in force on every surface, including the surfaces no automated check reaches, which is what the scan below is for.
 
+## Scope
+
+Governs voice, punctuation, formatting, and word choice wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and yields on voice alone where that standard states one.
+
+Does not govern:
+
+- What sections a document has, or what belongs in each: the standard for that document type
+- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
+- Phase-label and semver discipline: `versioning.md`
+- Code style and language conventions, which are governance rules rather than a standard
+
 ## Voice
 
 - Write for a developer who is scanning, not studying. Every sentence should be understandable on first read.

package/standards/readme.md

@@ -9,6 +9,15 @@ Applies to every `README.md`. The `## Voice` section states the voice for a repo
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
+## Scope
+
+Governs every `README.md`: voice, heading structure, required and optional sections, badge selection, and what the page links out to instead of carrying.
+
+Does not govern:
+
+- Punctuation, formatting, spelling, and banned words in README prose: `prose.md`, which yields the voice and keeps the rest
+- Product scope and goals: `requirements.md`
+
 ## Voice
 
 Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice in `prose.md`, since its reader has already committed and arrived looking for a fact.

package/standards/requirements.md

@@ -7,6 +7,16 @@ description: Shape and content rules for .claude/REQUIREMENTS.md
 
 Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
 
+## Scope
+
+Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
+
+Does not govern:
+
+- Rationale for a technical choice: `architecture.md`
+- Sequencing the scope into ordered versions: `roadmap.md`
+- Per-domain structure and narrative: `context.md`
+
 ## What goes in
 
 - The problem being solved and for whom
@@ -19,7 +29,6 @@ Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, n
 ## What does not go in
 
 - Implementation details, API names, or internal component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Anything that describes how a feature is built rather than what it does
 
 ## Sections

package/standards/rule.md

@@ -9,6 +9,16 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start. A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
 
+## Scope
+
+Governs governance rules under `.claude/rules/`: their location, numbering, frontmatter, and body shape.
+
+Does not govern:
+
+- Authoring conventions for a document type, which are standards rather than rules. A rule points at the standard that owns one and never restates it.
+- Skill folders and skill frontmatter: `skill.md`
+- Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
+
 ## Location
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`

package/standards/skill.md

@@ -9,6 +9,17 @@ description: Claude skill structure and authoring rules
 
 Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs. Each skill body contains actionable rules for its domain. Full reference docs are the fallback for edge cases and deeper context. Skills use progressive disclosure: Claude reads only frontmatter at session start (~100 tokens each), matches a query against descriptions, then loads the full skill body.
 
+## Scope
+
+Governs a skill folder as one artifact: `SKILL.md`, its optional sibling `REQUIREMENT.md`, and the bundled `references/`, `scripts/`, and `assets/` beside them.
+
+Does not govern:
+
+- Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
+- Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
+- Voice, punctuation, and formatting in a skill body: `prose.md`
+- The domain conventions a skill cites, each of which belongs to the standard that owns it
+
 ## Skill types
 
 Pick the type before writing. It decides the body shape.

package/standards/standard.md

@@ -9,22 +9,42 @@ Applies to each authored standard in the folder. Skip for `index.md`, which is g
 
 ## Overview
 
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+A standard is a target-facing authoring convention for one document type, or for one attribute carried across every document. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+
+## Scope
+
+Governs what an authored standard contains: its stated jurisdiction, success criterion, frontmatter, structure, and rule phrasing.
+
+Does not govern:
+
+- The voice, punctuation, and formatting a standard is written in: `prose.md`
+- The shape of any artifact a standard governs, which is that standard's own subject
 
 ## What a working standard looks like
 
 A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
 
-- Which single document type does this govern, and where does that document live?
+- Which single document type or attribute does this govern, and where does it apply?
 - Can an author who has seen no example produce a conforming document from this file alone?
 - Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
 - What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
 
 A standard failing these questions is non-conforming even when it satisfies every shape rule below.
 
-## Scope
+## Scoping rules
+
+### Declaring scope
+
+- Govern one document type per standard, or one attribute across every document. Split unrelated conventions into separate files.
+- Open with a `## Scope` section stating what the standard governs and what it does not, placed above the shape rules. A standard that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever standard sits nearest.
+- Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to. Name a sibling standard by bare filename, since standards install as siblings, and name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
+- Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
+- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one standard alone is never checked against the standard on the other side of it, which is how two files come to claim the same rule or neither does.
+- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another standard owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
+- Stay silent on a section the standard holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
+
+### Staying inside it
 
-- Govern one document type per standard. Split unrelated conventions into separate files.
 - Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
 - State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
 - Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.

package/standards/tasks.md

@@ -9,6 +9,17 @@ Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of
 
 The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
 
+## Scope
+
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, and archiving.
+
+Does not govern:
+
+- Phase-label format and which surfaces a label may appear on: `versioning.md`
+- Sequencing across versions and why the order is what it is: `roadmap.md`
+- Architectural reasoning that outlives a task: `architecture.md`
+- When a project opens a task at all, which is project policy rather than a shape rule
+
 ## Layout
 
 ```plaintext

package/standards/versioning.md

@@ -7,6 +7,17 @@ description: Phase label vs semver discipline across tasks, PRs, reviews, issues
 
 Two namespaces, kept separate.
 
+## Scope
+
+Governs the two version namespaces, phase labels and semver tags, and which surfaces each may appear on. It is an attribute standard rather than a document-type one, so it applies wherever either namespace is written.
+
+Does not govern:
+
+- The format of a phase label, which is project-specific by the rule below
+- Task filenames and board layout: `tasks.md`
+- Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
+- Voice, punctuation, and formatting in any text carrying a label: `prose.md`
+
 ## Phase labels
 
 Internal coordination vocabulary used in the task board and chat.