@erclx/canon 5.19.0 → 5.21.0

package/src/slides/convert/walk.ts

@@ -1,3 +1,5 @@
+import type { ChartRecord } from '@/slides/convert/chart'
+import type { ThemeReading } from '@/slides/convert/master'
 import type {
   BoxStyle,
   ElementRecord,
@@ -9,10 +11,34 @@ import type {
   TextRun,
 } from '@/slides/convert/shapes'
 
+/** How one slide treats a band the deck master draws. */
+export type BandOverride =
+  | { readonly kind: 'master' }
+  | { readonly kind: 'off' }
+  | {
+      readonly kind: 'override'
+      readonly left?: string
+      readonly center?: string
+      readonly right?: string
+    }
+
+/** What a slide declares about itself on `<body>` and in its notes. */
+export interface SlideMeta {
+  readonly notes?: string
+  readonly section?: string
+  readonly isHidden: boolean
+  readonly header: BandOverride
+  readonly footer: BandOverride
+  /** The `--color-text` the slide's `<body>` computes, as hex. */
+  readonly textToken?: string
+}
+
 /** What one laid-out slide hands back across `page.evaluate`. */
 export interface WalkedSlide {
   readonly background: Rgba
   readonly records: ElementRecord[]
+  readonly charts: ChartRecord[]
+  readonly meta: SlideMeta
 }
 
 /** Set on every walked element, so a screenshot finds the one a record names. */
@@ -27,7 +53,8 @@ export const ID_ATTRIBUTE = 'data-canon-id'
  * Text gathers along the inline flow. A block holding text takes every run its
  * inline descendants carry, so `<strong>` inside `<p>` is one shape with two
  * runs, while a block-level child is walked on its own. Images, SVGs, and
- * tables consume their whole subtree.
+ * tables consume their whole subtree. Speaker notes in `<aside class="notes">`
+ * and a chart's `<figure data-chart>` are read whole and never drawn as shapes.
  *
  * Each walked element is tagged with `idAttribute` set to its record id.
  */
@@ -293,10 +320,41 @@ export function walkSlide(idAttribute: string): WalkedSlide {
 
   const SKIPPED = new Set(['script', 'style', 'template', 'noscript', 'link'])
 
+  const cellText = (element: Element): string =>
+    (element.textContent ?? '').replace(/\s+/g, ' ').trim()
+
+  /** One line per block, so a paragraph break survives and no tag does. */
+  const notesText = (element: Element): string => {
+    const clone = element.cloneNode(true)
+    if (!(clone instanceof Element)) return ''
+    for (const br of Array.from(clone.querySelectorAll('br'))) {
+      br.replaceWith('\n')
+    }
+    for (const block of Array.from(
+      clone.querySelectorAll('p, li, div, blockquote, h1, h2, h3, h4, h5, h6'),
+    )) {
+      block.append('\n')
+    }
+    return (clone.textContent ?? '')
+      .split('\n')
+      .map((line) => line.replace(/\s+/g, ' ').trim())
+      .filter(Boolean)
+      .join('\n')
+  }
+
+  const notes: string[] = []
+  const charts: ChartRecord[] = []
+
   for (const element of Array.from(document.body.querySelectorAll('*'))) {
     if (consumed.has(element)) continue
     const tag = element.tagName.toLowerCase()
     if (SKIPPED.has(tag)) continue
+    if (tag === 'aside' && element.classList.contains('notes')) {
+      consumeSubtree(element)
+      const text = notesText(element)
+      if (text) notes.push(text)
+      continue
+    }
     if (!element.checkVisibility({ visibilityProperty: true })) continue
 
     const id = records.length + 1
@@ -313,6 +371,27 @@ export function walkSlide(idAttribute: string): WalkedSlide {
     ids.set(element, id)
     element.setAttribute(idAttribute, String(id))
 
+    if (tag === 'figure' && element.hasAttribute('data-chart')) {
+      consumeSubtree(element)
+      records.push({ ...base, kind: 'box' })
+      const table = element.querySelector('table')
+      const caption = element.querySelector('figcaption')
+      const title = caption ? cellText(caption) : ''
+      charts.push({
+        selector: base.selector,
+        box: bounds,
+        type: element.getAttribute('data-chart') ?? '',
+        hasLabels: element.hasAttribute('data-labels'),
+        ...(title ? { title } : {}),
+        rows: table
+          ? Array.from(table.rows).map((row) =>
+              Array.from(row.cells).map(cellText),
+            )
+          : [],
+      })
+      continue
+    }
+
     if (element instanceof HTMLImageElement) {
       records.push({
         ...base,
@@ -440,5 +519,111 @@ export function walkSlide(idAttribute: string): WalkedSlide {
         ? htmlGround
         : { hex: 'FFFFFF', alpha: 1 }
 
-  return { background, records }
+  const body = document.body
+  const band = (kind: 'header' | 'footer'): BandOverride => {
+    if (body.getAttribute(`data-${kind}`) === 'off') return { kind: 'off' }
+    const slots: { left?: string; center?: string; right?: string } = {}
+    for (const slot of ['left', 'center', 'right'] as const) {
+      const value = body.getAttribute(`data-${kind}-${slot}`)
+      if (value !== null) slots[slot] = value
+    }
+    return Object.keys(slots).length > 0
+      ? { kind: 'override', ...slots }
+      : { kind: 'master' }
+  }
+  const section = body.getAttribute('data-section')?.trim()
+  const textValue = getComputedStyle(body)
+    .getPropertyValue('--color-text')
+    .trim()
+  const meta: SlideMeta = {
+    ...(textValue ? { textToken: rgba(textValue).hex } : {}),
+    ...(notes.length > 0 ? { notes: notes.join('\n\n') } : {}),
+    ...(section ? { section } : {}),
+    isHidden:
+      body.hasAttribute('data-hidden') &&
+      body.getAttribute('data-hidden') !== 'false',
+    header: band('header'),
+    footer: band('footer'),
+  }
+
+  return { background, records, charts, meta }
+}
+
+/**
+ * Runs inside the laid-out page and reads the colors and face the deck master
+ * takes. Tokens come from `<html>`'s computed style, so a slide that switches
+ * theme on its own `<body>`, such as a dark cover, leaves the master on the
+ * project's root theme. The body supplies the fallback colors and the face.
+ * Serialized to source like `walkSlide`, so its helpers sit in its own body.
+ */
+export function readTheme(): ThemeReading {
+  const canvas = document.createElement('canvas')
+  canvas.width = 1
+  canvas.height = 1
+  const context = canvas.getContext('2d', { willReadFrequently: true })
+  const hex = (value: string): string | undefined => {
+    if (!context || !value || value === 'transparent') return undefined
+    context.clearRect(0, 0, 1, 1)
+    context.fillStyle = '#000000'
+    context.fillStyle = value
+    context.fillRect(0, 0, 1, 1)
+    const [r = 0, g = 0, b = 0, a = 0] = context.getImageData(0, 0, 1, 1).data
+    if (a === 0) return undefined
+    return [r, g, b]
+      .map((channel) => channel.toString(16).padStart(2, '0'))
+      .join('')
+      .toUpperCase()
+  }
+
+  const style = getComputedStyle(document.body)
+  const rootStyle = getComputedStyle(document.documentElement)
+  const token = (name: string): string | undefined => {
+    const value = rootStyle.getPropertyValue(name).trim()
+    return value ? hex(value) : undefined
+  }
+
+  const names: string[] = []
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList
+    try {
+      rules = sheet.cssRules
+    } catch {
+      continue
+    }
+    for (const rule of Array.from(rules)) {
+      if (!(rule instanceof CSSStyleRule)) continue
+      for (const name of Array.from(rule.style)) {
+        if (name.startsWith('--color-') && !names.includes(name)) {
+          names.push(name)
+        }
+      }
+    }
+  }
+
+  const tokens: {
+    background?: string
+    text?: string
+    muted?: string
+    accent?: string
+  } = {}
+  for (const role of ['background', 'text', 'muted', 'accent'] as const) {
+    const value = token(`--color-${role}`)
+    if (value) tokens[role] = value
+  }
+
+  return {
+    tokens,
+    body: {
+      background:
+        hex(style.backgroundColor) ??
+        hex(getComputedStyle(document.documentElement).backgroundColor) ??
+        'FFFFFF',
+      color: hex(style.color) ?? '000000',
+    },
+    fontFamily: style.fontFamily,
+    roles: names.flatMap((name) => {
+      const value = token(name)
+      return value ? [{ name, hex: value }] : []
+    }),
+  }
 }

package/src/tasks/record.ts

@@ -512,12 +512,18 @@ export async function recordPlan(
  * line, so the merge of an earlier slice cannot archive the task in the window
  * before this branch's own number is recorded. A rerun that ticks nothing adds
  * no marker, since its branch has already recorded or is already listed.
+ *
+ * `branchPulls` holds the pull request numbers the branch's own head carries.
+ * One already on the task's `Pull request:` line means the branch recorded its
+ * number, so a marker would outlive the branch with nothing left to clear it.
+ * An absent or empty list keeps the marker, which is the first slice's case.
  */
 export async function closeOutcomes(
   root: string,
   selector: RecordSelector,
   positions: readonly number[],
   branch?: string,
+  branchPulls: readonly number[] = [],
 ): Promise<CloseOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
@@ -541,8 +547,12 @@ export async function closeOutcomes(
     )
   }
 
+  const recorded = readPullRequest(result.text).some((number) =>
+    branchPulls.includes(number),
+  )
+
   const text =
-    result.closed.length > 0 && branch
+    result.closed.length > 0 && branch && !recorded
       ? writePendingBranch(result.text, branch).text
       : result.text
 

package/src/tasks/validate.ts

@@ -6,6 +6,7 @@ import {
   declinedDir,
   isReservedStem,
   readOutcomes,
+  readPendingBranches,
   readPlanTargets,
   readPullRequest,
   resolveLivePlan,
@@ -1065,6 +1066,10 @@ function nothing(): CitedResult {
  * about, and a task naming none leaves the row untested rather than settled,
  * because the only local signal left is the checkbox that produced the defect.
  *
+ * A task still carrying a pending branch is untested whatever its recorded
+ * pull request says, since a slice is in flight that has recorded no number yet
+ * and the landed one may belong to an earlier slice.
+ *
  * The outcome list comes off `readOutcomes` rather than a pattern of its own,
  * so this check cannot disagree with the archive and outcome verbs about which
  * checkboxes are outcomes and which sit inside a block a task displays.
@@ -1114,6 +1119,15 @@ async function checkCitedTask(
   const { open, closed } = readOutcomes(text)
   if (open.length > 0 || closed.length === 0) return nothing()
 
+  const pending = readPendingBranches(text)
+  if (pending.length > 0) {
+    return untestedRow(
+      group,
+      subject,
+      `waits on ${cited}, which closed every outcome but holds a pending branch (${pending.join(', ')}) that has yet to record its pull request.`,
+    )
+  }
+
   // The last number is the newest slice, and an earlier one closed without
   // merging never lands, so only the last says whether the work reached trunk.
   const pullRequest = readPullRequest(text).at(-1)

package/standards/architecture.md

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

package/standards/context.md

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

package/standards/design.md

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

package/standards/diagrams.md

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

package/standards/groundwork-spikes.md

@@ -0,0 +1,66 @@
+---
+title: Groundwork spikes reference
+description: What each spike in a track's 08-spikes.md records, the sample rule, and the three folders that hold what a spike produced
+---
+
+# Groundwork spikes reference
+
+Applies to `08-spikes.md` inside a groundwork track at `.canon/groundwork/<nn>-<slug>/`, and to the folders beside it that hold what a spike produced. It records evidence by experiment, beside the evidence by measurement `01-current-state.md` holds.
+
+## Scope
+
+Governs `08-spikes.md`, what each spike in it carries, how a spike is sized, and the `evidence/`, `scripts/`, and `clones/` folders in a track.
+
+Does not govern:
+
+- The track's folder layout, its other files, frontmatter, and numbering: `groundwork.md`
+- Running a spike, which belongs to the surface driving the track
+
+## What a working spike record looks like
+
+A spike record works when a later reader can re-run each spike and trust what it settled:
+
+- Which open question did each spike answer, and did it close it?
+- Can the method be re-run from the file, against the fixture it names?
+- What did it cost, and what does the result not prove?
+
+## Spikes
+
+The file is optional, since measuring what is already there settles most questions.
+
+Each spike carries four things:
+
+- The open question it answers, named by file and number. A spike attached to no question is a runaway.
+- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
+- The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
+- The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
+
+Start a spike against a sample bounded on input size, duration, and spend, and scale up only once it shows the method works. Record the sample's bounds beside the figure for the full input.
+
+## What a spike produced
+
+A file a reader opens to verify how a result was produced or what it showed lives inside the track, and bulk input such as a large fixture stays outside it. Three unnumbered subfolders carry the first kind, since a reader reaches them from the citing claim rather than in read order:
+
+- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
+- `scripts/`: the arm scripts and harnesses a spike ran, which a reader opens to check the method.
+- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
+
+Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
+
+Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
+
+Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.
+
+## Template
+
+```markdown
+# Spikes
+
+## <nn>. <what the spike tests>
+
+- Question: <file and number of the open question>
+- Method: <fixture and where it lived, exact command, repetition count>
+- Result: <what it showed, and which question it closes>
+- Cost: <measured cost>, <sample bounds beside the full-input figure>
+- Caveats: <what the result does not prove>
+```

package/standards/groundwork.md

@@ -1,6 +1,10 @@
 ---
 title: Groundwork reference
 description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+paths:
+  - '.canon/groundwork/**'
+rule:
+  - 'Follow the groundwork spikes standard for `08-spikes.md` and the folders holding what a spike produced. Read it with `canon standards groundwork-spikes`.'
 ---
 
 # Groundwork reference
@@ -15,6 +19,7 @@ Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout
 
 Does not govern:
 
+- `08-spikes.md`, what each spike records, and the folders holding what a spike produced: `groundwork-spikes.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The feature plan a closed track feeds, and the contract its answer slots keep: `plan.md`
 - The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
@@ -110,31 +115,6 @@ The dropped list is what stops a future session re-proposing something already r
 
 Written to survive a compaction that loses the conversation. It repeats facts held elsewhere in the folder rather than pointing at them. That duplication is correct here and wrong everywhere else.
 
-## 08-spikes.md
-
-Evidence by experiment, beside the evidence by measurement `01-current-state.md` holds. Optional, since measuring what is already there settles most questions.
-
-Each spike carries four things:
-
-- The open question it answers, named by file and number. A spike attached to no question is a runaway.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
-- The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
-- The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
-
-Start a spike against a sample bounded on input size, duration, and spend, and scale up only once it shows the method works. Record the sample's bounds beside the figure for the full input.
-
-A file a reader opens to verify how a result was produced or what it showed lives inside the track, and bulk input such as a large fixture stays outside it. Three unnumbered subfolders carry the first kind, since a reader reaches them from the citing claim rather than in read order:
-
-- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
-- `scripts/`: the arm scripts and harnesses a spike ran, which a reader opens to check the method.
-- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
-
-Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
-
-Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
-
-Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.
-
 ## Open questions
 
 Every open question carries a lean, wherever it appears. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.

package/standards/index.md

@@ -17,12 +17,14 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+- [Groundwork spikes reference](groundwork-spikes.md): What each spike in a track's 08-spikes.md records, the sample rule, and the three folders that hold what a spike produced
 - [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, 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
+- [Plan lifecycle reference](plan-lifecycle.md): When a feature plan is written, where it lives, how it changes mid-flight, and its move to the archive
+- [Plan reference](plan.md): Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
@@ -30,11 +32,13 @@ 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 path reference](skill-paths.md): Which root a file a skill body names resolves against, and how a body cites a standard
 - [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
+- [Claude skill reference](skill.md): Skill structure and authoring rules for Claude Code
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
+- [Task decline reference](tasks-decline.md): Where a task decided against moves, the Declined line it carries, and what happens to its plan and board row
 - [Tasks reference](tasks.md): Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags

package/standards/intake.md

@@ -1,6 +1,8 @@
 ---
 title: Intake reference
 description: Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
+paths:
+  - '.canon/intake/**'
 ---
 
 # Intake reference

package/standards/markdown.md

@@ -1,6 +1,12 @@
 ---
 title: Markdown reference
 description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
+paths:
+  - '**/*.md'
+rule:
+  - 'Read it before a substantial markdown edit. Do not work the banned characters from memory.'
+  - 'Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.'
+  - 'Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.'
 ---
 
 # Markdown reference

package/standards/memory.md

@@ -1,6 +1,8 @@
 ---
 title: Memory reference
 description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+paths:
+  - '.canon/memory/**'
 ---
 
 # Memory reference

package/standards/mermaid.md

@@ -1,6 +1,12 @@
 ---
 title: Mermaid reference
 description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
+paths:
+  - '**/*.md'
+rule:
+  - 'Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.'
+  - 'Read it before drafting the fence. Do not work the layout or the budgets from memory.'
+  - 'Which diagram a document carries and what question it answers is a separate topic. The diagrams standard routes it.'
 ---
 
 # Mermaid reference

package/standards/plan-lifecycle.md

@@ -0,0 +1,36 @@
+---
+title: Plan lifecycle reference
+description: When a feature plan is written, where it lives, how it changes mid-flight, and its move to the archive
+---
+
+# Plan lifecycle reference
+
+Applies to a feature plan at `.canon/plans/feature-<slug>.md` from the session that writes it to the archive. The folder is gitignored, so nothing but this lifecycle keeps a plan's rejected alternatives readable after the work ships.
+
+This standard governs when a plan moves and changes rather than what the file holds, so it carries no template. The plan's own template is in `plan.md`.
+
+## Scope
+
+Governs when a feature plan is written, where it lives across working trees, how it is amended, and its move to `.canon/plans/archive/`.
+
+Does not govern:
+
+- The filename, the required sections, and the suggested-and-answer contract: `plan.md`
+- The task file a plan is linked from, and how it is archived: `tasks.md`
+
+## What a working lifecycle looks like
+
+A plan's lifecycle works when a later reader can still answer, from the file alone:
+
+- What did the work set out to do, and which alternative did it reject?
+- Which answer to each question is current, without reconciling two passages?
+
+A plan lost to deletion, or carrying two answers to one question, fails both.
+
+## Lifecycle
+
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
+- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.

package/standards/plan.md

@@ -1,20 +1,30 @@
 ---
 title: Plan reference
-description: Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+description: Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
+paths:
+  - '.canon/plans/**'
+rule:
+  - 'Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.'
+  - 'Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.'
+  - "Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`."
+  - 'Move a shipped plan to `.canon/plans/archive/`. Never delete one.'
+  - 'Amend a plan in place when a decision changes. Do not append a second passage narrating the change.'
+  - 'Follow the plan lifecycle standard for when a plan is written, how it is amended, and its move to the archive. Read it with `canon standards plan-lifecycle`.'
 ---
 
 # Plan reference
 
 Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
 
-The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step below is a move rather than a cleanup.
+The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step is a move rather than a cleanup.
 
 ## Scope
 
-Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, and the suggested-and-answer contract.
 
 Does not govern:
 
+- When a plan is written, how it is amended, and its move to the archive: `plan-lifecycle.md`
 - One question measured in depth before anyone can plan against it: `groundwork.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
@@ -135,14 +145,6 @@ The plan is archived at ship, so the same deviation takes one line in the open t
 
 This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there.
 
-## Lifecycle
-
-- Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
-- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
-- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
-- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
-
 ## Template
 
 ```markdown

package/standards/readme.md

@@ -1,6 +1,8 @@
 ---
 title: Readme reference
 description: Readme voice, structure, and content conventions
+paths:
+  - '**/README.md'
 ---
 
 # Readme reference