@erclx/canon 4.119.0 → 4.121.0

package/src/markdown/scan.ts

@@ -55,20 +55,9 @@ export interface BodyLine {
   readonly text: string
   /** True on a fence delimiter and on every line between one pair. */
   readonly fenced: boolean
-  /**
-   * Which fenced block the line sits in, counted from one, and undefined
-   * outside one. Two blocks written with nothing between them are one
-   * contiguous run of fenced lines, so this is the only field telling them
-   * apart. Counting from one keeps the outside answer from reading as a block.
-   *
-   * The name carries the fence because `block` alone already names a run of
-   * `BodyLine` values in `src/markdown/structure.ts`, and one word meaning both
-   * an aggregate of lines and an index on each line reads as a bug.
-   */
-  readonly fenceBlock: number | undefined
 }
 
-export type BanKind = 'character' | 'word' | 'spelling'
+export type BanKind = 'character'
 
 export interface BanFinding {
   readonly line: number
@@ -80,30 +69,20 @@ export interface BanFinding {
 
 export interface BanSets {
   readonly characters: readonly string[]
-  readonly words: readonly string[]
-  readonly spellings: readonly string[]
 }
 
 /**
- * Marks which lines sit inside a fence without dropping them, and which block
- * each of those lines belongs to.
+ * Marks which lines sit inside a fence without dropping them.
  *
  * Each measure excludes a fence for its own reason and needs a different
  * response. The depth measure skips a fenced line so an example cannot break
  * the run around it, bullet folding treats one as a break so a bullet does not
  * absorb the block below it, and the ban scan ignores it outright. Returning
  * the mark rather than a filtered list is what lets one walk serve all three.
- *
- * The block index answers the consumer that has to decide per block rather
- * than per contiguous run, since two adjacent blocks are indistinguishable
- * through the mark alone. It is counted here because the walk already holds
- * the opening delimiter, and a consumer parsing its own would be the second
- * fence walker this repository consolidated away.
  */
 function markFences(texts: readonly string[], offset: number): BodyLine[] {
   const lines: BodyLine[] = []
   let fence: string | undefined
-  let fenceBlock = 0
 
   for (const [index, text] of texts.entries()) {
     const match = FENCE.exec(text.trim())
@@ -117,15 +96,9 @@ function markFences(texts: readonly string[], offset: number): BodyLine[] {
     } else if (match) {
       fenced = true
       fence = match[1]
-      fenceBlock += 1
     }
 
-    lines.push({
-      number: offset + index + 1,
-      text,
-      fenced,
-      fenceBlock: fenced ? fenceBlock : undefined,
-    })
+    lines.push({ number: offset + index + 1, text, fenced })
   }
 
   return lines
@@ -227,47 +200,12 @@ export function visibleText(text: string): string {
   return visible + drop(text.slice(read))
 }
 
-function escape(term: string): string {
-  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-/**
- * Bounds a banned word on a word character or a hyphen either side.
- *
- * `\b` sits after a hyphen, so a banned word ending a hyphenated compound
- * reports from inside it: `allows` came back out of `auto-allows`. A compound
- * is one word to a reader, and the ban is on the word rather than on a morpheme
- * of it. Stripping hyphens before matching was the alternative and it joins the
- * compound into a token neither half reaches.
- *
- * A spelling ban takes `wordBoundary` instead. This is not that rule with a
- * wider fence, since the two bans target different things.
- */
-function bannedWord(term: string): RegExp {
-  return new RegExp(`(?<![\\w-])${escape(term)}(?![\\w-])`, 'gi')
-}
-
 /**
- * Bounds a banned spelling on a word character alone, hyphens included.
+ * Finds every banned character outside a fence, a code span, and a link.
  *
- * A word ban targets the word, so a compound reading as one word is correct.
- * A spelling ban targets the orthography inside it, and a compound is exactly
- * where the orthography still sits: `behaviour-driven` carries the banned
- * spelling as plainly as `behaviour` does, and rejecting a hyphen here would
- * leave the usual spelling of that phrase unreported.
- */
-function bannedSpelling(term: string): RegExp {
-  return new RegExp(`\\b${escape(term)}\\b`, 'gi')
-}
-
-/**
- * Finds every banned term outside a fence, a code span, and a link.
- *
- * A word ban matches in either casing, since the standard states each in
- * lowercase and bans the word rather than a spelling of it. A closed set of
- * whole words separates the check from the pattern that produced most of the
- * intake's false positives: `exercises` and `promises` end in the banned
- * suffix and are not the banned words, and a closed set never reaches them.
+ * Characters are the whole set because a character is the one class a literal
+ * match settles. A word carries honest uses no match separates, which is why
+ * word choice is guidance a reader applies rather than a finding this reports.
  */
 export function scanBans(
   lines: readonly BodyLine[],
@@ -275,19 +213,6 @@ export function scanBans(
 ): BanFinding[] {
   const found: BanFinding[] = []
 
-  const patterns: { kind: BanKind; term: string; pattern: RegExp }[] = [
-    ...bans.words.map((term) => ({
-      kind: 'word' as const,
-      term,
-      pattern: bannedWord(term),
-    })),
-    ...bans.spellings.map((term) => ({
-      kind: 'spelling' as const,
-      term,
-      pattern: bannedSpelling(term),
-    })),
-  ]
-
   for (const line of lines) {
     if (line.fenced) continue
     const text = maskDisplayed(line.text)
@@ -299,12 +224,6 @@ export function scanBans(
         column = text.indexOf(term, column + term.length)
       }
     }
-
-    for (const { kind, term, pattern } of patterns) {
-      for (const match of text.matchAll(pattern)) {
-        found.push({ line: line.number, column: match.index, kind, term })
-      }
-    }
   }
 
   return found.sort((a, b) => a.line - b.line || a.column - b.column)

package/src/pr/evidence.ts

@@ -7,6 +7,9 @@ const MARKER_PREFIX = '<!-- pr-evidence:'
 /** How the first line of a body names the branch's preview deployment. */
 const PREVIEW_PREFIX = '**Preview:**'
 
+/** How the opening block names the branch's server on the operator's own machine, under any hosted preview line. */
+export const LOCAL_PREFIX = '**Local preview:**'
+
 /** The heading the checklist sits under, printed outside the delimiters so a carried checklist never doubles it. */
 const CHECKLIST_HEADING = '## What to look at'
 
@@ -128,6 +131,9 @@ export function evidenceMarker(head: string): string {
  *
  * A checklist closes the body, below the comparison it annotates, so one
  * comment carries the preview address, the screenshots, and what to look at.
+ *
+ * A local address sits under the hosted one, never above it, so the hosted
+ * line keeps the first-line position `findEvidencePreview` reads.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -136,9 +142,13 @@ export function renderEvidenceBody(
   head: string,
   preview?: string,
   checklist?: string,
+  local?: string,
 ): string {
-  const opening =
-    preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`, '']
+  const addresses = [
+    ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
+    ...(local === undefined ? [] : [`${LOCAL_PREFIX} ${local}`]),
+  ]
+  const opening = addresses.length === 0 ? [] : [...addresses, '']
   const closing =
     checklist === undefined
       ? []
@@ -223,6 +233,36 @@ export function findEvidencePreview(
   return first.slice(PREVIEW_PREFIX.length).trim() || undefined
 }
 
+/**
+ * Where the local address line sits in a body, searched only through the
+ * opening block above the first blank line, so a line quoted further down in
+ * a checklist is never taken for it. -1 when the block carries none.
+ */
+export function findLocalLineIndex(body: string): number {
+  const lines = body.split('\n')
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = (lines[index] ?? '').trim()
+    if (line === '') return -1
+    if (line.startsWith(LOCAL_PREFIX)) return index
+  }
+  return -1
+}
+
+/**
+ * The local address the marked comment already carries, carried forward on a
+ * re-render the way the hosted preview is.
+ */
+export function findEvidenceLocal(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  if (marked === undefined) return undefined
+  const index = findLocalLineIndex(marked.body)
+  if (index === -1) return undefined
+  const line = marked.body.split('\n')[index]?.trim() ?? ''
+  return line.slice(LOCAL_PREFIX.length).trim() || undefined
+}
+
 /**
  * The checklist the marked comment already carries, read back out of its
  * delimiters. The handoff file is deleted once posted, so every later render

package/src/pr/local.ts

@@ -0,0 +1,125 @@
+import { findLocalLineIndex } from '@/pr/evidence'
+
+/**
+ * The folder linked worktrees sit under. A listener there belongs to another
+ * branch even though its cwd sits inside the main checkout's toplevel.
+ */
+const LINKED_WORKTREES = '.claude/worktrees'
+
+/** The state `/proc/net/tcp` writes for a socket in LISTEN. */
+const PROC_LISTEN_STATE = '0A'
+
+export type LocalRefusal = 'no-server' | 'no-listener-reader'
+
+export interface Listener {
+  readonly port: number
+  readonly pid: number
+}
+
+/** The machine reads a detection makes, injected so it can be driven without binding a socket. */
+export interface LocalRunner {
+  /** Every TCP socket in LISTEN with its owning pid, or undefined when this machine offers no way to read them. */
+  listListeners(): Promise<readonly Listener[] | undefined>
+  cwdOf(pid: number): Promise<string | undefined>
+  /** Whether the port serves an HTML page at its root inside the runner's timeout. */
+  probe(port: number): Promise<boolean>
+}
+
+export type LocalResult =
+  | { readonly kind: 'found'; readonly port: number; readonly url: string }
+  | { readonly kind: 'refused'; readonly reason: LocalRefusal }
+
+function isInside(path: string, root: string): boolean {
+  return path === root || path.startsWith(`${root}/`)
+}
+
+/**
+ * Whether a process running in `cwd` serves this worktree. A tool that
+ * changes into a subfolder before listening still counts, while a sibling
+ * worktree nested under the main checkout's `.claude/worktrees/` does not.
+ */
+function belongsTo(cwd: string, worktreeRoot: string): boolean {
+  return (
+    isInside(cwd, worktreeRoot) &&
+    !isInside(cwd, `${worktreeRoot}/${LINKED_WORKTREES}`)
+  )
+}
+
+/**
+ * Finds the server this worktree is running: the lowest port whose listening
+ * process runs inside the worktree and answers an HTTP probe. A port rather
+ * than a process is the unit, since one dev server often holds a second
+ * socket for its reload channel, and the lower one is the page by convention.
+ */
+export async function findLocalServer(
+  worktreeRoot: string,
+  runner: LocalRunner,
+): Promise<LocalResult> {
+  const listeners = await runner.listListeners()
+  if (listeners === undefined) {
+    return { kind: 'refused', reason: 'no-listener-reader' }
+  }
+
+  const cwdByPid = new Map<number, string | undefined>()
+  const ports = new Set<number>()
+  for (const { pid, port } of listeners) {
+    if (!cwdByPid.has(pid)) cwdByPid.set(pid, await runner.cwdOf(pid))
+    const cwd = cwdByPid.get(pid)
+    if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
+  }
+
+  for (const port of [...ports].sort((a, b) => a - b)) {
+    if (await runner.probe(port)) {
+      return { kind: 'found', port, url: `http://localhost:${port}` }
+    }
+  }
+  return { kind: 'refused', reason: 'no-server' }
+}
+
+/** Reads `lsof -nP -iTCP -sTCP:LISTEN -Fpn` output, where a `p` line opens a process and each `n` line names one of its sockets. */
+export function parseLsofListeners(text: string): Listener[] {
+  const listeners: Listener[] = []
+  let pid: number | undefined
+  for (const line of text.split('\n')) {
+    if (line.startsWith('p')) pid = Number(line.slice(1))
+    if (!line.startsWith('n') || pid === undefined) continue
+    const port = Number(line.slice(line.lastIndexOf(':') + 1))
+    if (Number.isInteger(port) && port > 0) listeners.push({ pid, port })
+  }
+  return listeners
+}
+
+export interface ProcSocket {
+  readonly port: number
+  readonly inode: string
+}
+
+/** Reads `/proc/net/tcp` or `tcp6`, keeping each listening socket's port and inode for matching against `/proc/<pid>/fd`. */
+export function parseProcNetTcp(text: string): ProcSocket[] {
+  const sockets: ProcSocket[] = []
+  for (const line of text.split('\n').slice(1)) {
+    const fields = line.trim().split(/\s+/)
+    const local = fields[1]
+    const state = fields[3]
+    const inode = fields[9]
+    if (local === undefined || inode === undefined) continue
+    if (state !== PROC_LISTEN_STATE) continue
+    const port = Number.parseInt(local.slice(local.lastIndexOf(':') + 1), 16)
+    if (Number.isInteger(port) && port > 0) sockets.push({ port, inode })
+  }
+  return sockets
+}
+
+/**
+ * Replaces the local address line of a marked body with `note`, leaving
+ * every other byte in place so the trailing marker, the checklist delimiters,
+ * and any ticked box survive. Undefined when the body carries no such line,
+ * which is also what a second strip of the same body returns.
+ */
+export function stripLocalLine(body: string, note: string): string | undefined {
+  const index = findLocalLineIndex(body)
+  if (index === -1) return undefined
+  const lines = body.split('\n')
+  lines[index] = note
+  return lines.join('\n')
+}

package/standards/docs.md

@@ -19,7 +19,7 @@ Does not govern:
 - Per-domain internal narrative written for a reader with the source open: `context.md`
 - The drawing inside a Mermaid fence: `mermaid.md`
 - Voice, rhythm, and sentence construction: the `write-human` skill
-- Spelling, banned words, punctuation, and formatting: `markdown.md`
+- Punctuation and formatting: `markdown.md`
 
 ## What a working docs page looks like
 

package/standards/index.md

@@ -19,7 +19,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
-- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Mermaid reference](mermaid.md): Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
@@ -30,6 +30,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+- [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Snippet reference](snippets.md): Snippet reference and authoring conventions

package/standards/markdown.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 ---
 
 # Markdown reference
@@ -9,11 +9,11 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the closed-set word and spelling bans, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
+Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the spelling convention, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
 
 The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
 
-The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
+The split with the voice guidance is what reads the rule rather than what the rule covers. The character bans ship as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Word choice, cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
 
 Does not govern:
 
@@ -71,9 +71,7 @@ Does not govern:
 
 ## Language
 
-- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
-- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
-- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
+- Use American English spelling
 - Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
 - Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
 - Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
@@ -84,7 +82,7 @@ Does not govern:
 - Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
 - Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
 
-The word bans and the character bans sit under one file because one command reads both. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this section states them for a reader rather than for the parser.
+One command reads the character bans under `## Punctuation`. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this file states them for a reader rather than for the parser. The spelling line above states a convention and ships no set, so a project's spell checker is what enforces it.
 
 ## Frontmatter descriptions
 

package/standards/pr.md

@@ -16,7 +16,7 @@ Does not govern:
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
 - Whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on: `publish.md`
 - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
-- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
+- Punctuation and formatting in pull request prose: `markdown.md`
 
 ## Title
 

package/standards/publish.md

@@ -26,7 +26,7 @@ Scope every check below by destination. Text published to a remote takes all of
 
 ## Banned characters
 
-`markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
+`markdown.md` holds the character bans. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
 
 Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
 

package/standards/readme.md

@@ -5,7 +5,7 @@ description: Readme voice, structure, and content conventions
 
 # Readme reference
 
-Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the spelling rules, banned words, punctuation, and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as does the word-choice guidance that travels with them, and so do the punctuation and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no marketing words.
 
 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.
 
@@ -16,7 +16,7 @@ Governs every `README.md`: voice, heading structure, required and optional secti
 Does not govern:
 
 - Rhythm and sentence construction in README prose: the `write-human` skill, which yields the voice and keeps the rest
-- Spelling, banned words, punctuation, and formatting in README prose: `markdown.md`, which yields nothing
+- Punctuation and formatting in README prose: `markdown.md`, which yields nothing
 - Product scope and goals: `requirements.md`
 - The consumer-facing reference under `docs/`, whose reader has already committed and is operating the project: `docs.md`
 

package/standards/skill-requirement.md

@@ -0,0 +1,72 @@
+---
+title: Skill requirement reference
+description: Shape and content rules for the REQUIREMENT.md beside a skill
+---
+
+# Skill requirement reference
+
+Applies to the `REQUIREMENT.md` beside each `SKILL.md`. It states what the skill is for, so a proposed change can be argued against something and the corpus can be read to decide whether a skill should exist at all.
+
+## Scope
+
+Governs `skills/<name>/REQUIREMENT.md`: why it exists, what it must answer, and its sections.
+
+Does not govern:
+
+- The skill folder, `SKILL.md`, and the rule that every skill carries a requirement: `skill.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Punctuation, formatting, and word choice: `markdown.md`
+
+## What a working requirement looks like
+
+A requirement works when a proposed change to the skill can be settled by reading it alone, without re-deriving what the skill is for:
+
+- Does this change close a gap the file states?
+- Does a line already in the body trace to one of those gaps?
+- Does this behavior belong to this skill or to a sibling the file names?
+
+A requirement that leaves any of the three open is non-conforming regardless of whether it satisfies every shape rule below. The third question is what makes a requirement worth more than a restated description, because a boundary stated only in prose is never checked against the skill on the other side of it.
+
+## Purpose
+
+- Treat the file as the compressed statement of what the skill is for. A skill body is procedural by design, so its purpose sits spread across its steps, and a reader gets this file before opening the body whether or not the skill's scope is contested.
+- Read it before editing the skill. When a change closes no gap the requirement states, change the requirement first or drop the change.
+- Write the gaps from what the skill is for, then compare the body against them. A requirement derived from the body records the body's accidents as the requirement, and misinforms a reader who reads it in place of the body.
+
+## Content
+
+- State each gap as an observed failure, not an intent. "Without this skill a session invents its own filename" can be shown wrong. "This skill helps manage tasks" cannot fail, so it constrains nothing.
+- Trace everything under `## Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
+- Keep it high level. A requirement that outgrows one file has stopped being a requirement, and `references/` already holds detail.
+- Use `name` and `description` frontmatter, matching `SKILL.md` so the pair is consistent.
+
+## Template
+
+```markdown
+---
+name: <skill-name>
+description: <one line, distinct from the SKILL.md description>
+---
+
+# <Skill name> requirement
+
+## Gap
+
+Without this skill, a session <observed failure>, <observed failure>.
+
+## Must
+
+- <behavior that closes a named gap>
+
+## Must not
+
+- <behavior that would be wrong even though it closes a gap>
+
+## Guards
+
+- <the refusal condition and its message>
+
+## Out of scope
+
+- <the adjacent thing this deliberately does not cover, and what covers it>
+```