@erclx/canon 4.73.0 → 4.75.0

package/src/transcripts/fetch.ts

@@ -1,4 +1,5 @@
 import {
+  existsSync,
   mkdirSync,
   mkdtempSync,
   readdirSync,
@@ -81,13 +82,42 @@ interface WriteOptions {
   readonly fetchedAt: string
 }
 
+const INDEX_FILE = 'index.md'
+
+/**
+ * Writes a minimal index.md stub if the output directory carries none yet,
+ * so `canon indexes regen` has frontmatter to render entries against. Left
+ * alone once present, since a project may have customized it.
+ */
+function ensureIndex(outDir: string): void {
+  const indexPath = join(outDir, INDEX_FILE)
+  if (existsSync(indexPath)) return
+
+  const content = [
+    '---',
+    'title: Transcripts',
+    'subtitle: YouTube transcripts fetched by canon transcripts, one file per video.',
+    '---',
+    '',
+    '# Transcripts',
+    '',
+    'YouTube transcripts fetched by canon transcripts, one file per video.',
+    '',
+    'This folder is machine-written. Run canon indexes regen here to refresh its entries.',
+    '',
+  ].join('\n')
+
+  writeFileSync(indexPath, content)
+}
+
 export function writeTranscript(
   metadata: VideoMetadata,
   subPath: string | null,
   { outDir, keepTimestamps, fetchedAt }: WriteOptions,
 ): string {
   mkdirSync(outDir, { recursive: true })
-  const slug = `${slugify(metadata.title)}--${metadata.videoId}`
+  ensureIndex(outDir)
+  const slug = `${fetchedAt}--${slugify(metadata.title)}--${metadata.videoId}`
   const target = join(outDir, `${slug}.md`)
 
   const hasTranscript = subPath !== null

package/standards/architecture.md

@@ -27,6 +27,7 @@ Does not govern:
 
 - 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.
+- A measurement paragraph specific to one domain's own mechanism. Route it to that domain's `.claude/context/<domain>.md` entry instead. The choice and its rejected alternative stay here whatever their reach, since reach is what makes a decision cross-domain, not how many domains its supporting measurement happens to touch.
 
 ## Sections
 

package/standards/figures.md

@@ -0,0 +1,51 @@
+---
+title: Figure reference
+description: 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
+---
+
+# Figure reference
+
+Applies to every hand-drawn figure, wherever it is authored. A figure sits inside a document some other standard shapes, so this file reaches the figure and stops at its closing `</figure>` tag.
+
+## Scope
+
+Governs a hand-drawn figure wherever one is authored, naming no path because an attribute standard governs a fragment rather than a document type: when it earns its place, the render-first policy routing a graph-shaped subject through Mermaid, the wrapping and caption every figure carries, and its color and accessibility rules. It carries no template, since a figure has no document shape of its own and sits inside one another standard sets.
+
+Does not govern:
+
+- Direction, layout, node and edge budgets, labels, and render verification for the Mermaid path: `mermaid.md`
+- The toolkit's own architecture-diagram surface at `.canon/diagrams/`, which shares no code, font, or visual language with this convention: `diagrams.md`
+- Language, word choice, punctuation, and formatting in the caption or surrounding prose: `markdown.md`
+- Voice, rhythm, and sentence construction in that prose: the `write-human` skill
+- Which document types may carry a figure, and what else they require: that document type's own standard
+
+## What a working figure looks like
+
+A figure works when a reader who cannot see it still gets what it was for, and one who can see it gets nothing a well-placed sentence could not carry:
+
+- Does the subject clear the bar: a relationship, a boundary, a path, or a before-and-after that prose or a list cannot carry as well?
+- Does the caption name what to take from the figure rather than what it shows?
+- Does the figure still read after every color and font it depends on is stripped to its fallback?
+
+A figure failing these is non-conforming even when it satisfies every shape rule below.
+
+## When a figure earns its place
+
+- Draw a figure only when a relationship, a boundary, a path, or a before-and-after is the point of the passage rather than decoration for it. Most passages do not clear that bar.
+- Leave the point in prose or a list when it already carries there. A figure reaching for every passage repeats the failure restraint already guards against elsewhere in the document.
+
+## The render-first policy
+
+- Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
+- Reserve freehand inline SVG, plain shapes and lines authored directly in the markup, for a subject that is not graph-shaped. A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent one drawn by hand, so the hatch stays open rather than forcing every figure through the renderer.
+- State this as a render-first policy rather than a ban on a tool-exported drawing. Routing a graph-shaped figure through Mermaid is itself running it through an external tool, so a rule banning any diagram "exported from a diagramming tool" would forbid the path this policy requires.
+
+## Wrapping and captioning
+
+- Wrap a figure in a `<figure>` element holding its drawing and a `<figcaption>` that names what to take from the figure rather than what it shows.
+- Let the figure run wider than the surrounding prose column. A figure cramped to the reading measure loses the labels it needs.
+
+## Color and accessibility
+
+- Color every fill and stroke through a custom property the surrounding document's own stylesheet defines, never a literal hex value. The figure then re-colors itself on the same switch that re-colors the page.
+- Give the drawing an accessible name: `role="img"` with `aria-label` for one short line, or `aria-labelledby` pointing at a `<title>` element inside it for a longer one.

package/standards/groundwork.md

@@ -25,7 +25,8 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
-- Take the ordinal from the highest one already present across both `.canon/groundwork/` and `.canon/intake/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one already present across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/index.md

@@ -14,6 +14,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [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 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

package/standards/intake.md

@@ -25,7 +25,8 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
-- Take the ordinal from the highest one already present across both `.canon/intake/` and `.canon/groundwork/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
+- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest one already present across both `.canon/intake/` and `.canon/groundwork/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/plan.md

@@ -38,6 +38,7 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
 - Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
+- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. `canon tasks plan-branch` derives one branch from one plan filename, so every batch sharing a file has nothing left to open a pull request against once an earlier batch merges under that name. State a batch's dependency on the ones before it in its own `**Constraints:**`.
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
 - Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
 

package/standards/skill.md

@@ -156,7 +156,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 
 - `name` (required): kebab-case, matches folder name, no spaces or capitals
 - `description` (required): what it does + when to use it, under 1024 chars, no XML tags
-- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger
+- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger. The field marks that boundary, not a style preference.
 - `allowed-tools`: restrict tool access when the skill is active
 - `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)
 

package/tooling/base/configs/.husky/post-merge

@@ -59,3 +59,30 @@ done
 printf '\n📋 %s archive candidate(s) on the board:\n%s\n' "$count" "$closed"
 printf 'Outcomes are marked on the branch, so each still needs its work confirmed\n'
 printf 'on main. Run /task-board, which checks that and sweeps the plan first.\n\n'
+
+# The gitignored record folders live on one disk and nowhere else, and a merge
+# is the event that changes them most. This runs on every merge rather than
+# only on one that closes a task, since a review report and a memory entry
+# both land on runs that archive nothing.
+#
+# Sits last so a slow or unreachable remote delays no candidate announcement,
+# and inside an `if` so a push failing offline, or a machine that never ran
+# the one-time setup, still leaves this hook exiting zero. Guarded by its own
+# `command -v canon` check, since this file carries none above it.
+if command -v canon >/dev/null 2>&1; then
+  if backup=$(canon records push --root "$root" --json 2>/dev/null); then
+    changed=$(printf '%s' "$backup" | sed -n 's/.*"changed":\([0-9][0-9]*\).*/\1/p')
+    if [ -n "$changed" ] && [ "$changed" != "0" ]; then
+      printf '\n🗄️  Backed up %s record path(s).\n\n' "$changed"
+    fi
+  else
+    reason=$(printf '%s' "$backup" | sed -n 's/.*"reason":"\([^"]*\)".*/\1/p')
+
+    # No records history on this machine, which is every checkout that never
+    # ran the one-time setup. Nothing to report.
+    if [ "$reason" != "no-repository" ]; then
+      printf '\n🗄️  Records not backed up: %s\n' "${reason:-unknown}"
+      printf 'Run canon records push when the remote is reachable.\n\n'
+    fi
+  fi
+fi

package/tooling/claude/seeds/.claude/hooks/tasks-index.sh

@@ -34,11 +34,12 @@ case "$file_path" in
 esac
 
 # The board index covers the live folder alone. A shell pattern's wildcard
-# crosses a separator, so the guard above matches an archived task as well and
-# a regen fired on one would rebuild the index the archive was taken out of.
+# crosses a separator, so the guard above matches an archived or declined task
+# as well, and a regen fired on one would rebuild the index that task was
+# taken out of.
 case "$file_path" in
-*/.claude/tasks/index.md | */.claude/tasks/archive/*) exit 0 ;;
-*/.canon/tasks/index.md | */.canon/tasks/archive/*) exit 0 ;;
+*/.claude/tasks/index.md | */.claude/tasks/archive/* | */.claude/tasks/declined/*) exit 0 ;;
+*/.canon/tasks/index.md | */.canon/tasks/archive/* | */.canon/tasks/declined/*) exit 0 ;;
 esac
 
 # The walk-up boundary has to come from the path, not from the session. Shared