@erclx/canon 5.5.0 → 5.7.0

package/src/claude/skills-audit.ts

@@ -12,16 +12,40 @@ export const DESCRIPTION_LIMIT = 1024
 /** The two headings the requirement template declares, matched at any level. */
 export const REQUIREMENT_SECTIONS: readonly string[] = ['Gap', 'Must']
 
+/** The one tree that ships to a target, and the only one the practice list names. */
+export const SHIPPED_CORPUS = join('claude', 'skills')
+
 /**
  * Both trees the standard governs. `claude/skills/` ships to a target and
  * `.claude/skills/` stays here, and every rule measured below applies to each,
  * so a corpus reading one of them reports a pass over half the subject.
  */
 export const CORPORA: readonly string[] = [
-  join('claude', 'skills'),
+  SHIPPED_CORPUS,
   join('.claude', 'skills'),
 ]
 
+/**
+ * The practice skills `standards/skill-practice.md` describes, keyed by corpus-relative
+ * folder rather than by name, so a target's own `.claude/skills/` folder that
+ * shares a name is never swept in. The list lives here rather than in a skill's
+ * frontmatter because a skill declaring its own kind could exempt itself.
+ */
+export const PRACTICE_SKILLS: readonly string[] = [
+  join(SHIPPED_CORPUS, 'codebase-layout'),
+  join(SHIPPED_CORPUS, 'test-craft'),
+]
+
+/** The closing H2s a practice skill carries, matched exactly outside fences. */
+export const PRACTICE_SECTIONS: readonly string[] = [
+  'Excuses and rebuttals',
+  'Red flags',
+  'Before handing over',
+]
+
+/** The source ledger every practice skill carries beside its body. */
+export const PRACTICE_LEDGER = join('references', 'adopted.md')
+
 /**
  * The one reason this audit refuses. A project carrying neither corpus is the
  * ordinary state of a target that has not adopted either skills convention,
@@ -34,6 +58,8 @@ const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 const HEADING = /^#{1,6}\s+(.+?)\s*$/
 
+const SECTION = /^##\s+(.+?)\s*$/
+
 /**
  * An ISO date, read as provenance wherever a reader is told it. The context
  * audit's detector clears a date after "measured" or "verified", and a skill
@@ -69,6 +95,7 @@ export interface SkillsAudit {
   readonly longDescription: readonly SkillFinding[]
   readonly requirementSections: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
+  readonly practiceShape: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -79,6 +106,9 @@ interface SkillSource {
   readonly description: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
+  /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
+  readonly sections: readonly string[]
+  readonly hasLedger: boolean
   /**
    * `SKILL.md` and every reference below the folder, keyed by the path a
    * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
@@ -134,6 +164,13 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     datedProvenance: sources.flatMap((source) =>
       source.bodies.flatMap(dateFindings),
     ),
+    practiceShape: [
+      ...missingPracticeSkills(
+        present.some((corpus) => corpus.rel === SHIPPED_CORPUS),
+        sources,
+      ),
+      ...sources.flatMap(practiceFindings),
+    ],
   }
 }
 
@@ -190,6 +227,11 @@ async function readSkill(
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
+    sections: bodyLines(body)
+      .filter((line) => !line.fenced)
+      .map((line) => SECTION.exec(line.text)?.[1])
+      .filter((text): text is string => text !== undefined),
+    hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
     bodies: [
       { rel: join(skillRel, 'SKILL.md'), text: body },
       ...references.map((path, index) => ({
@@ -252,6 +294,44 @@ function sectionFindings(source: SkillSource): SkillFinding[] {
   ]
 }
 
+/**
+ * A listed folder the shipped corpus does not hold, such as a renamed skill or
+ * a misspelled append, would otherwise read as a pass. Silent where the
+ * shipped corpus is absent, since a target carries none of the listed skills.
+ */
+function missingPracticeSkills(
+  hasShippedCorpus: boolean,
+  sources: readonly SkillSource[],
+): SkillFinding[] {
+  if (!hasShippedCorpus) return []
+  const found = new Set(sources.map((source) => source.rel))
+  return PRACTICE_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
+    rel,
+    detail: 'missing skill: no folder under the shipped corpus',
+  }))
+}
+
+/**
+ * Matches each section as an exact H2, so a heading carrying trailing text or
+ * sitting at another level reads as missing rather than as a near match the
+ * standard never names.
+ */
+function practiceFindings(source: SkillSource): SkillFinding[] {
+  if (!PRACTICE_SKILLS.includes(source.rel)) return []
+
+  const sections = PRACTICE_SECTIONS.filter(
+    (section) => !source.sections.includes(section),
+  ).map((section) => ({
+    rel: source.rel,
+    detail: `missing section: ${section}`,
+  }))
+  const ledger = source.hasLedger
+    ? []
+    : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
+
+  return [...sections, ...ledger]
+}
+
 /**
  * A date inside a fence or a code span is example data a reader is shown, such
  * as a sample frontmatter block, so only prose outside both is read.

package/src/commands/claude.ts

@@ -26,7 +26,11 @@ import {
   auditSkills,
   CORPORA,
   DESCRIPTION_LIMIT,
+  PRACTICE_LEDGER,
+  PRACTICE_SECTIONS,
+  PRACTICE_SKILLS,
   REQUIREMENT_SECTIONS,
+  SHIPPED_CORPUS,
   type SkillFinding,
   type SkillsAudit,
   type SkillsAuditRefusal,
@@ -1398,6 +1402,7 @@ async function runSkillsAudit(
     reportFolder(report)
     reportRequirementShape(report)
     reportProvenance(report)
+    reportPracticeShape(report)
     reportUnmeasured()
     outro()
   }
@@ -1420,11 +1425,14 @@ async function runSkillsAudit(
           folderName: report.folderName,
           requirementSections: report.requirementSections,
           datedProvenance: report.datedProvenance,
+          practiceShape: report.practiceShape,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
           corpora: CORPORA,
+          practiceSkills: PRACTICE_SKILLS,
+          practiceSections: PRACTICE_SECTIONS,
         },
       })}\n`,
     )
@@ -1615,6 +1623,31 @@ function reportProvenance(report: SkillsAudit): void {
   reportFindings(report.datedProvenance)
 }
 
+/**
+ * Reports without failing the run for the reason provenance does. The list
+ * names shipped folders alone, which the step says so a target reading a pass
+ * knows its own skills were never in scope.
+ */
+function reportPracticeShape(report: SkillsAudit): void {
+  logStep('Practice shape')
+  logInfo(
+    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and carries ${PRACTICE_LEDGER}.`,
+  )
+  logInfo(
+    `The list is kept here and names ${plural(PRACTICE_SKILLS.length, 'shipped skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
+  )
+
+  if (report.practiceShape.length === 0) {
+    logInfo('Every listed practice skill carries its shape.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.practiceShape.length, 'missing part')} across the listed practice skills`,
+  )
+  reportFindings(report.practiceShape)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard

package/src/gate/measures.ts

@@ -13,7 +13,12 @@ import {
   measureArchitecture,
   missingRevisit,
 } from '@/context/architecture'
-import { auditSkills } from '@/claude/skills-audit'
+import {
+  auditSkills,
+  PRACTICE_LEDGER,
+  PRACTICE_SKILLS,
+  SHIPPED_CORPUS,
+} from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
@@ -314,6 +319,43 @@ export const skillProvenance: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every listed practice skill against the closing sections and the ledger
+ * `standards/skill-practice.md` requires of one.
+ *
+ * Read in-process for the reason `skillProvenance` is, so the verb keeps its
+ * missing-requirement-only exit. The list names shipped folders alone, so a
+ * tree without `claude/skills/` reports unmeasured rather than a vacuous pass.
+ */
+export const skillPracticeShape: Measure = async (ctx) => {
+  const report = await auditSkills(ctx.root)
+  if (!report.corpora.some((corpus) => corpus.rel === SHIPPED_CORPUS)) {
+    return {
+      emissions: [],
+      unmeasured: `no skill corpus at ${SHIPPED_CORPUS} resolved, so no practice skill was read.`,
+    }
+  }
+
+  const found = report.practiceShape
+  if (found.length > 0) {
+    const where = found
+      .map((finding) => `${finding.rel} ${finding.detail}`)
+      .join(', ')
+    return {
+      emissions: [],
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named, or the ledger at ${PRACTICE_LEDGER}.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info(
+        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section and a ledger`,
+      ),
+    ],
+  }
+}
+
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *

package/src/gate/stages.ts

@@ -14,6 +14,7 @@ import {
   seedStandards,
   rawFieldFileReference,
   shippedReferences,
+  skillPracticeShape,
   skillProvenance,
   standardCriteria,
   unreferencedRules,
@@ -486,6 +487,14 @@ export const STAGES: readonly Stage[] = [
     label: 'Skill provenance',
     checks: [{ kind: 'measure', measure: skillProvenance }],
   },
+  {
+    // The audit verb only reports a listed practice skill missing a closing
+    // section or its ledger, so a target is told without failing. The list
+    // names this repository's shipped skills, so the stage fails here alone.
+    id: 'skill-practice-shape',
+    label: 'Skill practice shape',
+    checks: [{ kind: 'measure', measure: skillPracticeShape }],
+  },
   {
     id: 'standard-criteria',
     label: 'Standard success criteria',

package/standards/index.md

@@ -31,6 +31,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
+- [Practice skill reference](skill-practice.md): Closing sections and source ledger for a skill carrying engineering practice
 - [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

package/standards/skill-practice.md

@@ -0,0 +1,51 @@
+---
+title: Practice skill reference
+description: Closing sections and source ledger for a skill carrying engineering practice
+---
+
+# Practice skill reference
+
+Applies to a practice skill, one carrying engineering judgment a session applies while it works, where the failure is skipping the practice or cutting it short rather than not knowing it. Its body takes the reference shape, and this file fixes how it closes and what it cites.
+
+## Scope
+
+Governs the closing sections of a practice skill's `skills/<name>/SKILL.md` and the source ledger at `skills/<name>/references/adopted.md` beside it.
+
+Does not govern:
+
+- The skill folder, its frontmatter, the body rules, and the choice between skill types: `skill.md`
+- The `REQUIREMENT.md` beside the body: `skill-requirement.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Punctuation, formatting, and word choice: `markdown.md`
+
+## What a working practice skill looks like
+
+A practice skill works when a session about to cut the practice short meets the answer before it does:
+
+- Does every excuse row name a reason a session has actually given to skip the practice?
+- Can a session spot each red flag in its own work while it is still working?
+- Can a session run every line of the closing checklist against what it produced, and get a yes or a no?
+- Can a reader open each source the ledger names and find the version the body states?
+
+A practice skill failing any of these is non-conforming even when every heading below is present.
+
+## Closing sections
+
+- Follow every concern group with three H2s in this order: `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`. A section naming what the skill delegates comes after the three, and nothing else does.
+- Spell each heading exactly. An H3, or a heading carrying more words such as `## Red flags that mean start over`, reads as missing.
+- Write `## Excuses and rebuttals` as a two-column table pairing a reason a session gives to skip or shortcut the practice with the answer to it. Never write a row rebutting an objection nobody raised, since that row is ceremony. Revisit when a practice skill's table is observed failing to stop an excuse it names.
+- Write `## Red flags` as bullets naming signs a session can observe in its own work mid-task, never a restatement of a rule above.
+- Write `## Before handing over` as the exit checklist, each line a check against what the session produced.
+
+## Source ledger
+
+- Carry `references/adopted.md` in every practice skill, recording each external source the body draws on.
+- Link each source, or pin it to a commit, so a reader can open the version the body adopted.
+- State what was adopted, what was declined, and why for each, so a later session extends the position rather than re-deriving it.
+- Draw first from the default shelf, [Software Engineering at Google](https://abseil.io/resources/swe-book/html/toc.html) and [Google's engineering practices](https://google.github.io/eng-practices/), and record a source from elsewhere the same way.
+
+## Which skills are practice skills
+
+- `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
+- Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
+- The list names this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/standards/skill.md

@@ -16,6 +16,7 @@ Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings
 Does not govern:
 
 - What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
+- A practice skill's closing sections and ledger: `skill-practice.md`
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
@@ -45,6 +46,7 @@ Pick the type before writing. It decides the body shape.
 
 - Reference: conventions, patterns, and domain knowledge Claude applies inline. The body is rule bullets grouped by concern.
 - Task: step-by-step workflows Claude executes as actions. The body is numbered steps plus the rules constraining them.
+- Practice: judgment a session may skip, shaped by `skill-practice.md`.
 
 A task skill takes the template below. A reference skill takes the same frontmatter and replaces `## Steps` and `## Rules` with one H2 per concern group, each holding constraint bullets.
 
@@ -105,7 +107,7 @@ allowed-tools: <tools required>
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
-- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences. Revisit when removing a line of general knowledge from a skill is shown to change what the agent does.
+- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it. Revisit when a run shows the model ignoring a principle named only as a handle.
 
 ### Progressive disclosure
 

package/tooling/web/seeds/.cspell/tech-stack.txt

@@ -16,5 +16,6 @@ serviceworker
 sidepanel
 tabindex
 toplevel
+viewports
 vitest
 xlink