@erclx/canon 4.125.0 → 4.126.0

package/README.md

@@ -96,7 +96,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
-- [Target projects](docs/target-projects.md): scaffold, add a domain later, sync upstream drift
+- [Target projects](docs/target/target-projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [Docs index](docs/index.md): every reference doc in this repo
 
@@ -152,7 +152,7 @@ canon init
 
 Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
 
-For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
+For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/target-projects.md).
 
 ### Internal narrative
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.125.0",
+  "version": "4.126.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/index.md

@@ -7,14 +7,6 @@ subtitle: One-line reference for each doc in this folder.
 
 One-line reference for each doc in this folder.
 
-## Agent surface
-
-- [Target migrations](target-migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
-- [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
-- [Target scenarios](target-scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
-- [Target sync](target-sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once
-
-## Sub-catalogs
-
 - [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.
+- [Target](target/index.md): Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
 - [Workflow](workflow/index.md): How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.

package/docs/target/index.md

@@ -0,0 +1,16 @@
+---
+title: Target
+subtitle: Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
+category: Agent surface
+---
+
+# Target
+
+Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
+
+## Agent surface
+
+- [Target migrations](target-migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
+- [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
+- [Target scenarios](target-scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
+- [Target sync](target-sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once

package/docs/{target-projects.md → target/target-projects.md}

@@ -8,7 +8,7 @@ category: Agent surface
 
 How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
 
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `canon/context/<domain>.md`.
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](../agents/index.md). For per-domain mechanics, see each `canon/context/<domain>.md`.
 
 ## Getting the skills
 
@@ -74,7 +74,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `canon:design-extract` to draft `canon/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
 3. Optionally invoke `canon:draft-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
-4. Start the feature loop. See [AI workflow](workflow/ai-workflow.md) for the per-feature sequence.
+4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
 
 A machine without a renderer still gets the diagrams and is told which check was skipped.
 
@@ -135,8 +135,8 @@ When the toolkit updates, a target pulls changes per domain. A project scaffolde
 
 ## Related
 
-- [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
+- [agents](../agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [target migrations](target-migrations.md), [target sync](target-sync.md), [target scenarios](target-scenarios.md): the one-time moves, the recurring sync, and worked setups
-- [AI workflow](workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../canon/context/tooling/index.md), [governance](../canon/context/governance/index.md), [claude plugin](../canon/context/claude-plugin/index.md), [indexes](../canon/context/indexes.md), [snippets](../canon/context/snippets.md), [standards](../canon/context/standards/index.md): per-domain mechanics
-- [sandbox](../canon/context/sandbox/index.md): scenario catalog for verifying domain flows
+- [AI workflow](../workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
+- [tooling](../../canon/context/tooling/index.md), [governance](../../canon/context/governance/index.md), [claude plugin](../../canon/context/claude-plugin/index.md), [indexes](../../canon/context/indexes.md), [snippets](../../canon/context/snippets.md), [standards](../../canon/context/standards/index.md): per-domain mechanics
+- [sandbox](../../canon/context/sandbox/index.md): scenario catalog for verifying domain flows

package/docs/{target-sync.md → target/target-sync.md}

@@ -84,7 +84,7 @@ Use a targeted entry point when only one surface moved upstream. Use the catch-a
 
 ## Verify a sync
 
-Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../canon/context/sandbox/index.md) for the scenario catalog and routing patterns.
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../../canon/context/sandbox/index.md) for the scenario catalog and routing patterns.
 
 ## Running sync from an agent session
 

package/docs/workflow/ai-workflow.md

@@ -44,7 +44,7 @@ Run `canon init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and
 
 ### Bootstrap a new project
 
-See [target projects](../target-projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
+See [target projects](../target/target-projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
 
 ### New feature
 

package/docs/workflow/skill-map.md

@@ -6,7 +6,7 @@ category: Workflow
 
 # Skill map
 
-Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
 
 This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.125.0",
+  "version": "4.126.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/gate/measures.ts

@@ -312,10 +312,9 @@ export const skillProvenance: Measure = async (ctx) => {
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *
- * Report-only for now: a document past the ceiling warns and the stage still
- * passes, since the corpus carried dozens past it when the stage landed. The
- * flip to a failure is a separate change once the count reads zero, and it
- * replaces the warn path rather than sitting beside it.
+ * A document past the ceiling fails the stage. The failure names every one with
+ * its height rather than the first, so a contributor sees the whole set in one
+ * pass, and an exempt document is counted and never named.
  *
  * Read in-process rather than through `canon markdown audit`, whose exit code
  * stays bans and dead links only. The plan and groundwork skills run that audit
@@ -353,15 +352,12 @@ export const documentCeiling: Measure = async (ctx) => {
     }
   }
 
+  const where = over
+    .map((finding) => `${finding.rel} ${finding.renderedLines} rendered lines`)
+    .join(', ')
   return {
-    emissions: [
-      ...over.map((finding) =>
-        warn(`${finding.rel}  ${finding.renderedLines} rendered lines`),
-      ),
-      info(
-        `${plural(over.length, 'document')} past the ${ceiling}-line ceiling, ${exempt} exempt. Reported only, so the push is not held.`,
-      ),
-    ],
+    emissions: [],
+    failure: `${plural(over.length, 'document')} past the ${ceiling}-line ceiling: ${where}. Split each at a seam, or for a verbatim record add a \`<!-- canon-length-exempt: <reason> -->\` line naming why.`,
   }
 }
 

package/src/gate/stages.ts

@@ -338,7 +338,7 @@ export const STAGES: readonly Stage[] = [
     // Only the citation half of the audit gates. Its length, depth, table, and
     // index findings are judgment thresholds, and failing a push on one would
     // make the stage something to route around. The one length reading that
-    // will gate is the whole-document ceiling, which the Document ceiling stage
+    // gates is the whole-document ceiling, which the Document ceiling stage
     // below owns rather than this audit.
     id: 'context-citations',
     label: 'Context citations',
@@ -360,8 +360,8 @@ export const STAGES: readonly Stage[] = [
     checks: [{ kind: 'measure', measure: architectureRecord }],
   },
   {
-    // Unscoped, since any branch can grow any document. It warns and passes
-    // until the corpus sits under the ceiling, then flips to a failure.
+    // Unscoped, since any branch can grow any document. A document past the
+    // ceiling fails the push.
     id: 'document-ceiling',
     label: 'Document ceiling',
     checks: [{ kind: 'measure', measure: documentCeiling }],

package/src/init/steps.ts

@@ -5,7 +5,7 @@ import type { DomainStep } from '@/init/run'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target-migrations.md`'s backup section in its
+ * States the same fact as `docs/target/target-migrations.md`'s backup section in its
  * own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =