@pilotspace/add 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [Unreleased]
+
+## [1.10.0] — 2026-06-25
+
+Component-aware major — ADD now models every codebase as a **graph of components**,
+each owning a source root, its own green bar, and the contracts it produces or
+consumes, so **one milestone can ship a vertical slice across components** in a
+monorepo or across repos. Bundles the closed `component-aware-add` major plus the
+`docs-site` (the book as a live MkDocs site) and `loop-steering` milestones, and the
+ccsk `--rule-file` mode. Every new gate is **opt-in or grandfathered** — a project
+that declares no components is byte-identical to 1.9.0.
+
+### Added
+- **Component registry (`component-aware-add`)** — declare parts of a multi-part
+  codebase in `.add/components.toml` under `[component.<name>]` (a `root` + a
+  `green-bar`). A task binds to one with a `component:` header line, which anchors its
+  §5 Scope to that component's root. Declared, never inferred; zero components ⇒
+  byte-identical to today.
+- **Per-component verify** — a bound task is held to ITS component's green-bar at the
+  verify gate (the cite-gate refuses `component_green_bar_uncited`), so two tasks in
+  one milestone can pass on two different toolchains (e.g. `pytest` and `vitest`). The
+  engine still never runs a suite — the AI runs it, the gate checks the right bar was
+  cited.
+- **Cross-component contracts (`produces:` / `consumes:`)** — declare `[contract.<id>]`
+  (producer + consumers). A producer's §3 freeze writes an immutable snapshot at
+  `.add/contracts/<id>.json`; a consumer pins its hash; a changed re-freeze flags every
+  consumer stale. A missing/malformed snapshot HARD-STOPS — never build against a
+  guessed shape.
+- **One milestone, full-stack slice** — a `consumes:` task is HELD from entering §3
+  (`producer_contract_unfrozen`) until its producer's contract is frozen, so a BE→FE
+  vertical slice ships in one milestone, ordered by the frozen contract.
+- **Multi-repo federation (`add.py federate pull <id>`)** — a consumer repo declares
+  `[federation.<id>]` (a `source` path + optional `pin`) and pulls a byte-for-byte copy
+  of a producer repo's published snapshot into its local `.add/contracts/`, where the
+  rest of ADD treats mono- and multi-repo identically. Fail-loud: unknown id /
+  unreadable source / invalid snapshot / version mismatch each HARD-STOPS and lands
+  nothing.
+- **Component pillar docs** — a new book chapter `17 · Components`, a skill guide
+  (`components.md`), and glossary terms (Component · Cross-component contract ·
+  Federation) teach the whole loop.
+- **The book as a live site (`docs-site`)** — the AIDD book ships to GitHub Pages as a
+  MkDocs-Material site (`mkdocs.yml` + `requirements-docs.txt`, build-time only — the
+  published packages stay zero-dependency); `mkdocs build --strict` fails the deploy on
+  a broken intra-book link.
+- **Rule-file mode for ccsk projects (`--rule-file`)** — when a project keeps its
+  workflow rules under `.claude/rules/` (the ccsk convention, detected by a `.ccsk/`
+  dir), ADD relocates CLAUDE.md's block to `.claude/rules/add-workflows.md` and leaves a
+  single reference bullet, instead of inlining. Triggers three ways (the explicit
+  `--rule-file` flag, a `.ccsk/` directory, or a rule file already present),
+  **CLAUDE-only**, migrates a prior inline block out (`.bak` on change), idempotent and
+  fail-soft. Mirrored across all three installers (engine `add.py`, pip `_installer.py`,
+  npm `cli.js`).
+
+### Changed
+- **Guided dynamic loop (`loop-steering`)** — `status` and `guide` now STEER into the
+  build→verify loop at the loop juncture rather than only reporting it, so an agent is
+  pointed at the next loop step instead of having to infer it.
+
+### Compatibility
+- Python 3.11+ is required to USE the component pillar (it parses `components.toml` with
+  the stdlib `tomllib`); on 3.10 the engine runs unchanged but a declared
+  `components.toml` fails loud (`components_malformed`). The published packages remain
+  zero-dependency.
+
 ## [1.9.0] — 2026-06-24
 
 Lean-pass major — make ADD's own surface (skill · flow · engine) the most-effective

package/bin/cli.js

@@ -39,7 +39,7 @@ function parseArgs(argv) {
   // defaults the stage and infers the name from the folder, so the manual-init
   // hint only echoes flags the user actually chose (shortest true command).
   const args = { _: [], force: false, check: false, noSkill: false, stage: null, name: null,
-                 yes: false, nonInteractive: false, global: false, globalData: false };
+                 yes: false, nonInteractive: false, global: false, globalData: false, ruleFile: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
@@ -58,6 +58,9 @@ function parseArgs(argv) {
     // already provides the `add` skill, so a plugin bootstrap uses this to materialize
     // .add/tooling/ + .add/docs/ into the project without a duplicate .claude/skills/add.
     else if (a === "--no-skill") args.noSkill = true;
+    // --rule-file: write the ADD block to .claude/rules/add-workflows.md + reference it from
+    // CLAUDE.md instead of inlining (auto-on for ccsk projects with a .ccsk/ dir).
+    else if (a === "--rule-file") args.ruleFile = true;
     else if (a === "--stage" || a === "--name") {
       const v = argv[++i];
       // fail loudly on a trailing/abutting flag — never silently drop a value
@@ -249,6 +252,126 @@ function writeAgentPointer(target, profile) {
   }
 }
 
+// --- rule-file mode: ccsk-style relocation of the CLAUDE.md block ---------------------
+// Mirror of add.py / _installer.py rule-file logic (twins by duplication). For ccsk projects
+// (.ccsk/ dir) or an explicit --rule-file, the ADD pointer goes to .claude/rules/add-workflows.md
+// and CLAUDE.md keeps only a reference bullet. CLAUDE-only — AGENTS.md/.clinerules stay inline.
+const RULES_FILE_REL = path.join(".claude", "rules", "add-workflows.md");
+const WORKFLOW_HEADINGS = ["Rules & Workflows", "Workflows", "Rules"];
+const RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md";
+
+// True when the ADD block belongs in .claude/rules/add-workflows.md instead of inline.
+// Re-derived from disk: explicit flag, a ccsk project (.ccsk/), or a rule file already present.
+function ruleFileMode(root, flag) {
+  if (flag) return true;
+  try {
+    if (fs.existsSync(path.join(root, ".ccsk")) &&
+        fs.statSync(path.join(root, ".ccsk")).isDirectory()) return true;
+    if (fs.existsSync(path.join(root, RULES_FILE_REL))) return true;
+  } catch (_e) { /* fail-soft */ }
+  return false;
+}
+
+// Remove an inline ADD:BEGIN..END region (migration), collapsing the gap. An unterminated
+// BEGIN is left as-is rather than eating the rest of the file.
+function stripInlineBlock(text) {
+  const begin = text.indexOf(GUIDE_BEGIN);
+  if (begin === -1) return text;
+  let end = text.indexOf(GUIDE_END, begin);
+  if (end === -1) return text;
+  end += GUIDE_END.length;
+  const head = text.slice(0, begin).replace(/\n+$/, "");
+  const tail = text.slice(end).replace(/^\n+/, "");
+  if (head && tail) return head + "\n\n" + tail;
+  return head || tail;
+}
+
+// Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a fresh
+// '## Workflows' section. Caller guarantees the bullet is absent.
+function insertRuleReference(text) {
+  const lines = text.split("\n");
+  let headingIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,6})\s+(.*?)\s*$/);
+    if (m && WORKFLOW_HEADINGS.some((h) => m[2].trim().toLowerCase() === h.toLowerCase())) {
+      headingIdx = i;
+      break;
+    }
+  }
+  if (headingIdx === -1) {
+    const body = text.replace(/\n+$/, "");
+    const sep = body ? "\n\n" : "";
+    return body + sep + "## Workflows\n\n" + RULE_REF_LINE + "\n";
+  }
+  const level = lines[headingIdx].match(/^(#{1,6})/)[1].length;
+  let end = lines.length;
+  for (let j = headingIdx + 1; j < lines.length; j++) {
+    const m = lines[j].match(/^(#{1,6})\s+/);
+    if (m && m[1].length <= level) { end = j; break; }
+  }
+  let insertAt = headingIdx + 1;
+  for (let j = headingIdx + 1; j < end; j++) {
+    if (lines[j].trim()) insertAt = j + 1;
+  }
+  lines.splice(insertAt, 0, RULE_REF_LINE);
+  return lines.join("\n");
+}
+
+// Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating any prior
+// inline ADD block out. created|updated|unchanged|skipped; .bak on change; fail-soft.
+function ensureClaudeReference(claudeMd) {
+  try {
+    const existed = fs.existsSync(claudeMd);
+    const current = existed ? fs.readFileSync(claudeMd, "utf8") : "";
+    let next = stripInlineBlock(current);
+    if (next.indexOf("add-workflows.md") === -1) next = insertRuleReference(next);
+    if (!next.endsWith("\n")) next += "\n";
+    if (next === current) return "unchanged";
+    if (existed) fs.writeFileSync(claudeMd + ".bak", current);
+    fs.writeFileSync(claudeMd, next);
+    return existed ? "updated" : "created";
+  } catch (e) {
+    warn("could not write CLAUDE.md — " + (e && e.message ? e.message : e) + "; skipped");
+    return "skipped";
+  }
+}
+
+// Rule-file variant of writeAgentPointer for the Claude profile: write the ADD pointer block to
+// .claude/rules/add-workflows.md and leave a reference in CLAUDE.md. Fail-soft.
+function writeRuleFilePointer(target, profile) {
+  const rulesPath = path.join(target, RULES_FILE_REL);
+  const block = agentPointerBlock(profile);
+  try {
+    if (fs.existsSync(rulesPath)) {
+      const current = fs.readFileSync(rulesPath, "utf8");
+      const begin = current.indexOf(GUIDE_BEGIN);
+      let next;
+      if (begin !== -1) {
+        const endIdx = current.indexOf(GUIDE_END, begin);
+        if (endIdx !== -1) {
+          next = current.slice(0, begin) + block + current.slice(endIdx + GUIDE_END.length);
+        } else {
+          next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
+        }
+      } else {
+        next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
+      }
+      if (next !== current) {
+        fs.writeFileSync(rulesPath + ".bak", current);
+        fs.writeFileSync(rulesPath, next);
+      }
+    } else {
+      fs.mkdirSync(path.dirname(rulesPath), { recursive: true });
+      fs.writeFileSync(rulesPath, block + "\n");
+    }
+  } catch (e) {
+    warn("could not write " + RULES_FILE_REL + " — " + (e && e.message ? e.message : e) + "; skipped");
+    return "skipped";
+  }
+  ensureClaudeReference(path.join(target, "CLAUDE.md"));
+  return "ok";
+}
+
 // --- interactive layer (clack on a real TTY; plain text everywhere else) -----
 // Designed-for-failure: any doubt (non-TTY, CI, --yes, a failed import, an
 // un-promptable stream) degrades to the EXACT plain-text path below. The clack
@@ -450,7 +573,16 @@ function dropFiles(args, target, profile, intent) {
   // Agent detection: write THE detected agent's integration file (a marker-delimited
   // pointer init's sync-guidelines later supersedes) + tailor the closing next-step.
   // Best-effort + fail-soft — never aborts the successful drop above.
-  writeAgentPointer(target, profile);
+  // Rule-file mode (ccsk projects / --rule-file) relocates the CLAUDE.md pointer to
+  // .claude/rules/add-workflows.md + a reference — CLAUDE-only; other agents stay inline.
+  if (profile.integration_file === "CLAUDE.md" && ruleFileMode(target, args.ruleFile)) {
+    if (fs.existsSync(path.join(target, ".ccsk"))) {
+      log("  ccsk detected — ADD rules go to .claude/rules/add-workflows.md");
+    }
+    writeRuleFilePointer(target, profile);
+  } else {
+    writeAgentPointer(target, profile);
+  }
 
   // Gemini CLI auto-loads GEMINI.md, not AGENTS.md — so for the gemini profile we ALSO merge
   // .gemini/settings.json (context.fileName) to load the AGENTS.md pointer. Fail-soft + idempotent.
@@ -847,4 +979,7 @@ module.exports = {
   scopeOptions: scopeOptions,
   writeIntentNote: writeIntentNote,
   writeGeminiSettings: writeGeminiSettings,
+  ruleFileMode: ruleFileMode,
+  ensureClaudeReference: ensureClaudeReference,
+  writeRuleFilePointer: writeRuleFilePointer,
 };

package/docs/16-releasing.md

@@ -1,6 +1,6 @@
 # 16 · Releasing
 
-[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [17 Components →](./17-components.md)
 
 ---
 
@@ -179,4 +179,4 @@ the risk, record the marker, and let a person make the outward call.
 
 ---
 
-[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [17 Components →](./17-components.md)

package/docs/17-components.md

@@ -0,0 +1,125 @@
+# 17 · Components — monorepo and multi-repo
+
+[← 16 Releasing](./16-releasing.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+
+---
+
+Most of this book treats a project as one codebase with one green bar. Real
+systems are rarely that tidy: a backend and a frontend, a shared library and two
+apps, or three services across three repos. ADD models all of these the same
+way — as a **graph of components**. A component owns a source root, its own
+green bar, and the contracts it produces or consumes. With that, **one milestone
+can ship a vertical slice across components** — a backend endpoint and the
+frontend that calls it — instead of splitting the slice across milestones.
+
+This pillar is **opt-in and additive**: a project that declares no components
+behaves exactly as the rest of the book describes. You reach for it only when a
+milestone genuinely spans more than one green bar.
+
+## Declare the components
+
+Components are **declared, never inferred** — ADD does not scan `apps/*` and
+guess. You name them in `.add/components.toml`:
+
+```toml
+[component.gateway]
+root      = "apps/gateway"
+green-bar = "pytest + pyright"
+
+[component.dashboard]
+root      = "apps/web"
+green-bar = "vitest + a11y"
+```
+
+Each component owns a **root** (the source subtree it governs) and a
+**green-bar** (the suite + checks that prove *that* component healthy). A task
+binds to a component with a `component:` header line; the component's root is
+then added to the task's §5 Scope automatically. A project with no
+`components.toml`, or a task with no `component:` line, is byte-identical to a
+single-component project.
+
+## Verify each task against its own green bar
+
+In a mixed milestone, a backend task and a frontend task pass on **different
+toolchains**. The verify gate enforces this per component: a task bound to
+`gateway` must cite its component's green-bar (`pytest + pyright`) in the §6
+Build-expectations evidence, or the gate refuses `component_green_bar_uncited`.
+The engine never *runs* the suite — that invariant holds here too. The AI runs
+the right suite for the bound component; the gate checks the **right bar was
+cited** in the evidence. Two tasks, one milestone, two green bars — each held to
+its own.
+
+## Freeze a contract between components
+
+When one component produces an interface another consumes, that boundary needs a
+**frozen, machine-checkable contract**. Declare it, name its producer and
+consumers:
+
+```toml
+[contract.gateway-api]
+producer  = "gateway"
+consumers = ["dashboard"]
+```
+
+A task declares its role with a header line — `produces: gateway-api` or
+`consumes: gateway-api`. When the **producer** task freezes its §3 and crosses
+contract→tests, the engine writes an immutable snapshot at
+`.add/contracts/gateway-api.json` (id, producer, version, frozen date, and a
+hash over the frozen §3 shape). When a **consumer** task crosses contract→tests,
+it **pins** that live hash. If the producer later re-freezes a *changed* shape,
+`add.py check` flags every consumer `contract_consumer_stale` — a §7 delta to
+re-pin against the new shape. A missing or malformed snapshot is a HARD-STOP, not
+a guess: the consumer never builds against a shape that was never frozen.
+
+## One milestone, a full-stack slice
+
+The reason to put a producer and a consumer in the *same* milestone is to ship a
+vertical slice — but the frontend must not commit to an endpoint the backend has
+not frozen yet. ADD enforces that ordering with a **hold**: a `consumes:` task
+cannot advance scenarios→contract (it cannot write its §3) while its producer's
+snapshot does not yet exist. The engine refuses `producer_contract_unfrozen` and
+the task stays at `scenarios`. Once the backend freezes its contract, the
+frontend proceeds and pins it. The slice is **ordered by the frozen contract**,
+all inside one milestone — the FE stays downstream of the BE endpoint, not split
+into a later milestone.
+
+## Across repositories: federation
+
+Components in separate repositories work the same way; only the
+**snapshot transport** differs. A consumer repo declares where a producer repo
+publishes its frozen contract:
+
+```toml
+[federation.gateway-api]
+source = "../gateway/.add/contracts/gateway-api.json"
+pin    = "v1"        # optional — the version this repo expects
+```
+
+`add.py federate pull gateway-api` reads that source, validates it (valid JSON,
+matching id, a hash, and — if `pin` is set — a matching version), and lands a
+**byte-for-byte copy** at the local `.add/contracts/gateway-api.json`. From
+there, the consuming repo's task holds and pins exactly as in a monorepo. The
+pull is **fail-loud by design**: an unknown id, an unreadable source, an invalid
+snapshot, or a version mismatch each HARD-STOPS and lands nothing — federation
+never builds an FE against a guessed or stale endpoint. The producer's snapshot
+is the published artifact; "publishing" is committing that file in the producer
+repo. Each repo keeps its own git-native `state.json`; federation transports only
+the immutable frozen shape, never shared mutable state.
+
+## What this pillar is not
+
+- **Not auto-discovery.** Components are declared in `components.toml`, not
+  inferred from the directory tree.
+- **Not a central server.** Federation copies an immutable snapshot between
+  repos; there is no shared service and no shared mutable state.
+- **Not a new approval.** The component machinery rides the existing six-step
+  flow and its single contract-freeze approval — it adds gates the engine
+  enforces, not human checkpoints.
+
+The whole pillar is structure, not policy: who *owns* a component and how
+autonomy is set per component is the identity/governance story (chapters 11–12),
+layered on top of this graph.
+
+---
+
+[← 16 Releasing](./16-releasing.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)

package/docs/appendix-c-glossary.md

@@ -16,6 +16,12 @@
 
 **Co-specification** — how a spec is made in ADD: the AI and the human **brainstorm the shape together** (diverge), the AI **drafts** it, and the human **validates with the AI's advice** (validate). The AI's decisive advice is the *lowest-confidence flag*. It replaces dictation-by-one-side — the human owns the decision, the AI owns surfacing what it does not yet know. See [03 Specify](./03-step-1-specify.md).
 
+**Component** — a declared part of a multi-part codebase that owns a source `root` and its own `green-bar` (suite + checks), named in `.add/components.toml` under `[component.<name>]`. A task binds to one with a `component:` header line, which adds that root to its §5 Scope and holds it to that component's green bar at verify. Declared, never inferred; a project with no components is byte-identical to a single-codebase project. See [17 Components](./17-components.md).
+
+**Cross-component contract** — the frozen, machine-checkable interface between a producer component and its consumers, declared under `[contract.<id>]` (producer + consumers). A task names its role with a `produces: <id>` or `consumes: <id>` header. On the producer's freeze the engine writes an immutable snapshot at `.add/contracts/<id>.json`; a consumer pins its hash and is flagged `contract_consumer_stale` if the producer later re-freezes a changed shape. Inside one milestone a `consumes:` task is HELD from writing its §3 until the producer's snapshot exists — the intra-milestone BE→FE ordering. See [17 Components](./17-components.md).
+
+**Federation (multi-repo)** — the transport that carries a frozen cross-component contract between separate repositories. A consumer repo declares `[federation.<id>]` with a `source` (and optional `pin`); `add.py federate pull <id>` validates the producer repo's published snapshot and lands a byte-for-byte copy locally, where it behaves exactly as in a monorepo. Fail-loud: an unknown id, unreadable source, invalid snapshot, or version mismatch HARD-STOPS and lands nothing. Each repo keeps its own git-native `state.json`; only the immutable snapshot crosses. See [17 Components](./17-components.md).
+
 **Disposable code** — the view that code is one regenerable implementation of the artifacts, not a durable asset to be preserved.
 
 **Evidence bundle** — the proof attached to a change (passing tests, clean security scan, no coverage loss) that justifies trusting it and may unlock more AI autonomy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -46,7 +46,7 @@
     "type": "git",
     "url": "git+https://github.com/pilotspace/ADD.git"
   },
-  "homepage": "https://github.com/pilotspace/ADD#readme",
+  "homepage": "https://pilotspace.github.io/ADD/",
   "bugs": {
     "url": "https://github.com/pilotspace/ADD/issues"
   }

package/skill/add/SKILL.md

@@ -130,6 +130,10 @@ once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `
   (security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
   (CHANGELOG + `RELEASES.md` ledger + milestone attribution). The engine records; the human runs the
   tag / publish / deploy. A release bundles ≥1 milestone and is orthogonal to stage.
+- **Monorepo / multi-repo** — a milestone spans more than one green bar (a BE + its FE, services across
+  repos) → the **component pillar**: declare components in `.add/components.toml`, gate each task on its
+  component's green-bar, freeze cross-component contracts (`produces:`/`consumes:`), hold the FE until the
+  BE freezes, and `federate pull` a contract across repos — `components.md`. Opt-in; no components = today.
 
 ## Non-negotiable rules (from the method)
 

package/skill/add/components.md

@@ -0,0 +1,54 @@
+# Components — monorepo and multi-repo slices
+
+Opt-in pillar for a milestone that spans **more than one green bar** — a backend
+and its frontend, a shared lib and two apps, services across repos. A project
+that declares no components is byte-identical to a single-codebase project. Reach
+for this only when one milestone genuinely crosses components. Full narrative:
+book chapter `17-components.md`.
+
+## Declare (never inferred)
+
+`.add/components.toml`:
+
+```toml
+[component.gateway]
+root      = "apps/gateway"
+green-bar = "pytest + pyright"
+[component.dashboard]
+root      = "apps/web"
+green-bar = "vitest + a11y"
+```
+
+A task binds with a `component: <name>` header line → that root joins its §5
+Scope, and verify holds it to that component's green-bar.
+
+## The loop
+
+1. **Per-component verify.** A bound task must CITE its component's green-bar in
+   the §6 Build-expectations evidence, or the gate refuses
+   `component_green_bar_uncited`. The engine never runs the suite — you run the
+   right one; the gate checks the right bar was cited.
+2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
+   (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
+   The producer's freeze (contract→tests) writes the immutable snapshot
+   `.add/contracts/<id>.json`; the consumer pins its hash. A changed re-freeze
+   flags consumers `contract_consumer_stale`; a missing/malformed snapshot
+   HARD-STOPS — never build against an unfrozen shape.
+3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
+   scenarios→contract (`producer_contract_unfrozen`) until the producer's
+   snapshot exists. The FE stays downstream of the frozen BE endpoint, in one
+   milestone.
+4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
+   (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
+   byte-for-byte copy of the producer repo's published snapshot locally, where it
+   behaves as in a monorepo. Fail-loud: unknown id / unreadable source / invalid
+   snapshot / version mismatch each HARD-STOPS and lands nothing.
+
+## Hold the line
+
+- **Declared, not inferred** — no scanning `apps/*`.
+- **No central server / no shared mutable state** — federation copies an
+  immutable snapshot; each repo keeps its own git-native `state.json`.
+- **No new approval** — these are engine-enforced gates on the existing six-step
+  flow, not extra human checkpoints. Ownership/autonomy per component is the
+  identity story (`streams.md`, governance), layered on this graph.

package/tooling/add.py

@@ -25,6 +25,11 @@ import urllib.request
 from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
+try:                       # component-aware-add registry parse (Python 3.11+ stdlib)
+    import tomllib
+except ModuleNotFoundError:   # < 3.11: the registry is unsupported → degrade to opt-out
+    tomllib = None
+
 # --- constants ---------------------------------------------------------------
 
 ROOT_DIRNAME = ".add"
@@ -116,6 +121,16 @@ GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md")
 _GUIDE_BEGIN = "<!-- ADD:BEGIN — managed by `add.py sync-guidelines`; do not edit inside -->"
 _GUIDE_END = "<!-- ADD:END -->"
 
+# Rule-file mode (ccsk-style projects): instead of inlining the block into CLAUDE.md,
+# write it to a dedicated rule file under .claude/rules/ and leave a one-line reference
+# in CLAUDE.md's Workflows section. .claude/rules/ is a CLAUDE-only convention, so this
+# mode only ever relocates CLAUDE.md — AGENTS.md/.clinerules keep the inline block.
+RULES_FILE_REL = Path(".claude") / "rules" / "add-workflows.md"
+# Headings (most→least specific) a project may already use to group rule/workflow links.
+# Match is case-insensitive on the heading TEXT, at any `#` level.
+WORKFLOW_HEADINGS = ("Rules & Workflows", "Workflows", "Rules")
+_RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md"
+
 # Minimal embedded fallback so the tool still works if templates/ is missing
 # (circuit breaker: never hard-fail just because a template file was deleted).
 _FALLBACK_TASK = """# TASK: {title}
@@ -215,6 +230,20 @@ def _atomic_write(path: Path, text: str) -> None:
             os.unlink(tmp)
 
 
+def _atomic_write_bytes(path: Path, data: bytes) -> None:
+    """Binary sibling of `_atomic_write` — lands `data` UNCHANGED (no newline translation), so a
+    byte-for-byte copy stays exact. Same temp-then-replace crash-safety."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
 def _atomic_write_many(writes: list[tuple[Path, str]]) -> None:
     """True all-or-nothing commit across N files — design-for-failure for a multi-file write.
 
@@ -655,6 +684,13 @@ def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None
     new = text
     for pat, repl in rules:
         new = re.sub(pat, repl, new, count=1)
+    # component-aware-add (per-component-verify): record WHICH green-bar a bound task gated
+    # against, right after the Outcome line. Unbound / no green_bar -> no line (byte-identical).
+    _bar = _task_green_bar(root, slug)
+    if _bar:
+        _line = f"component: {_task_component(root, slug)} · expected green-bar: {_bar}"
+        if _line not in new:
+            new = re.sub(r"(?m)^(Outcome:.*$)", lambda m: m.group(1) + "\n" + _line, new, count=1)
     if new != text:                              # no-op = no write (mtime stable)
         _atomic_write(f, new)
 
@@ -740,17 +776,131 @@ def _inject_block(path: Path) -> str:
     return "created"
 
 
-def _inject_guidelines(project_root: Path) -> list[tuple[str, str]]:
+def _rule_file_mode(project_root: Path, flag: bool = False) -> bool:
+    """True when the ADD block should live in .claude/rules/add-workflows.md (referenced
+    from CLAUDE.md) instead of inline. Re-derived from disk EACH phase — no persisted
+    state — so an explicit `--rule-file` at install carries into init via the rule file it
+    leaves behind. Three triggers: the explicit flag, a ccsk project (.ccsk/ sibling to
+    .claude/), or a rule file already written by a prior run. Pure + fail-soft."""
+    if flag:
+        return True
+    try:
+        if (project_root / ".ccsk").is_dir():
+            return True
+        if (project_root / RULES_FILE_REL).exists():
+            return True
+    except OSError:
+        pass
+    return False
+
+
+def _strip_inline_block(text: str) -> str:
+    """Remove an inline ADD:BEGIN..ADD:END region (migration to rule-file mode), collapsing
+    the blank-line gap it leaves behind. An unterminated BEGIN (no END) is left as-is rather
+    than eating the rest of the file (design-for-failure)."""
+    begin = text.find(_GUIDE_BEGIN)
+    if begin == -1:
+        return text
+    end = text.find(_GUIDE_END, begin)
+    if end == -1:
+        return text
+    end += len(_GUIDE_END)
+    head = text[:begin].rstrip("\n")
+    tail = text[end:].lstrip("\n")
+    if head and tail:
+        return head + "\n\n" + tail
+    return head or tail
+
+
+def _insert_rule_reference(text: str) -> str:
+    """Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a
+    fresh '## Workflows' section when none is found. Caller guarantees the bullet is absent."""
+    lines = text.split("\n")
+    heading_idx = -1
+    for i, line in enumerate(lines):
+        m = re.match(r"^(#{1,6})\s+(.*?)\s*$", line)
+        if m and any(m.group(2).strip().lower() == h.lower() for h in WORKFLOW_HEADINGS):
+            heading_idx = i
+            break
+    if heading_idx == -1:                       # no section — append a fresh one
+        body = text.rstrip("\n")
+        sep = "\n\n" if body else ""
+        return f"{body}{sep}## Workflows\n\n{_RULE_REF_LINE}\n"
+    level = len(re.match(r"^(#{1,6})", lines[heading_idx]).group(1))
+    end = len(lines)                            # section ends at next same/higher heading or EOF
+    for j in range(heading_idx + 1, len(lines)):
+        m = re.match(r"^(#{1,6})\s+", lines[j])
+        if m and len(m.group(1)) <= level:
+            end = j
+            break
+    insert_at = heading_idx + 1                 # after the last non-blank line in the section
+    for j in range(heading_idx + 1, end):
+        if lines[j].strip():
+            insert_at = j + 1
+    lines.insert(insert_at, _RULE_REF_LINE)
+    return "\n".join(lines)
+
+
+def _ensure_claude_reference(claude_md: Path) -> str:
+    """Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating
+    any prior inline ADD block out. Returns created|updated|unchanged.
+
+    - Strips a prior inline ADD:BEGIN..END block (rule-file mode supersedes inline).
+    - If a reference to add-workflows.md already exists -> no bullet change.
+    - Else inserts the bullet into the first matching section, or appends '## Workflows'.
+    .bak on change; idempotent. User content outside the touched region is preserved.
+    """
+    existed = claude_md.exists()
+    current = claude_md.read_text(encoding="utf-8") if existed else ""
+    new = _strip_inline_block(current)
+    if "add-workflows.md" not in new:
+        new = _insert_rule_reference(new)
+    if not new.endswith("\n"):
+        new += "\n"
+    if new == current:
+        return "unchanged"
+    if existed:
+        _atomic_write(Path(str(claude_md) + ".bak"), current)   # rollback path before mutate
+    _atomic_write(claude_md, new)
+    return "updated" if existed else "created"
+
+
+def _inject_guidelines(project_root: Path, rule_file: bool = False) -> list[tuple[str, str]]:
     """Inject the block into each guideline file under `project_root`.
 
     Symlink-dedup: targets resolving (os.path.realpath) to the same inode are
     written once, against the REAL file (never replacing the symlink with a
     regular file). Per-target OSError is isolated (warn+skip) so one unwritable
     file never aborts the run or `init`.
+
+    Rule-file mode (ccsk projects / `--rule-file`): CLAUDE.md's full block is relocated
+    to .claude/rules/add-workflows.md and CLAUDE.md keeps only a reference bullet. This is
+    CLAUDE-only — AGENTS.md (and any other guideline file) keeps the inline block.
     """
     results: list[tuple[str, str]] = []
     seen: set[str] = set()
+    mode = _rule_file_mode(project_root, rule_file)
     for name in GUIDELINE_FILES:
+        if name == "CLAUDE.md" and mode:
+            rules_path = project_root / RULES_FILE_REL
+            real = os.path.realpath(rules_path)
+            if real not in seen:
+                seen.add(real)
+                try:
+                    action = _inject_block(rules_path)
+                except (OSError, UnicodeDecodeError) as exc:
+                    print(f"add: warning: could not sync {RULES_FILE_REL} — {exc}; skipped",
+                          file=sys.stderr)
+                    action = "skipped"
+                results.append((str(RULES_FILE_REL), action))
+            try:
+                ref_action = _ensure_claude_reference(project_root / "CLAUDE.md")
+            except (OSError, UnicodeDecodeError) as exc:
+                print(f"add: warning: could not sync CLAUDE.md — {exc}; skipped",
+                      file=sys.stderr)
+                ref_action = "skipped"
+            results.append(("CLAUDE.md", ref_action))
+            continue
         target = project_root / name
         real = os.path.realpath(target)
         if real in seen:
@@ -841,7 +991,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         state["setup"] = {"locked": False, "locked_at": None, "locked_by": None, "layers": []}
     save_state(root, state)
     # zero-config: give any agent a stable pointer into the ADD runtime.
-    for name, action in _inject_guidelines(base):
+    for name, action in _inject_guidelines(base, getattr(args, "rule_file", False)):
         if action != "unchanged":
             print(f"{action:>9}  {name}")
     print(f"initialised ADD project '{state['project']}' (stage: {state['stage']}) at {root}")
@@ -857,7 +1007,7 @@ def cmd_init(args: argparse.Namespace) -> None:
 
 def cmd_sync_guidelines(args: argparse.Namespace) -> None:
     project_root = _require_root().parent
-    for name, action in _inject_guidelines(project_root):
+    for name, action in _inject_guidelines(project_root, getattr(args, "rule_file", False)):
         print(f"{action:>9}  {name}")
 
 
@@ -1061,6 +1211,19 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # into build/verify/observe/done is refused until `add.py lock`.
     if not _setup_locked(state) and nxt in ("build", "verify", "observe", "done"):
         _die("setup_unlocked: lock the foundation first — add.py lock")
+    # intra-milestone cross-component HOLD (cross-component-milestone): a consumer of a DECLARED
+    # contract may not enter §3 (scenarios->contract) until its producer froze — proven by the
+    # snapshot the producer's contract->tests crossing writes (task 3). This orders a BE→FE slice
+    # inside ONE milestone (the FE stays downstream of the frozen endpoint). Validate-before-write:
+    # the HARD-STOP precedes the phase bump, so the task stays at `scenarios`. Undeclared id / no
+    # `consumes:` header -> no hold (byte-identical; a typo'd id is a cmd_check registry finding).
+    if nxt == "contract":
+        _cid = _task_consumes(root, slug)
+        _cmap = _contracts(root)
+        if _cid and _cid in _cmap and not _contract_snapshot(root, _cid).exists():
+            _die(f"producer_contract_unfrozen: the producer '{_cmap[_cid].get('producer', '?')}' of "
+                 f"contract '{_cid}' must freeze its contract before you write §3 — wait for "
+                 f".add/contracts/{_cid}.json")
     # flag-first freeze guard (task unflagged-freeze): a FROZEN §3 may not cross
     # into build without a WELL-FORMED lowest-confidence flag. On pass, stamp the
     # verified marker so `audit` enforces the flag on THIS record only (open/new
@@ -1124,6 +1287,44 @@ def cmd_advance(args: argparse.Namespace) -> None:
                 side.unlink()
             except OSError:
                 pass
+    # cross-component contract artifact (cross-component-contract): the contract->tests crossing
+    # is the producer's freeze-approval moment. A `produces:` task WRITES the immutable snapshot;
+    # a `consumes:` task PINS the live hash — a missing/unreadable snapshot HARD-STOPS here (the
+    # phase stays at `contract`, nothing pinned), so a consumer never builds against a guessed
+    # shape. No role / no contracts ⇒ neither branch is taken (byte-identical).
+    if nxt == "tests":
+        _prod = _task_produces(root, slug)
+        if _prod:
+            raw3c = _raw_phase_bodies(root, slug).get(3, "")
+            vm = re.search(r"FROZEN @ (v\d+)", raw3c)
+            snap = {"id": _prod, "producer": (_contracts(root).get(_prod) or {}).get("producer", "?"),
+                    "task": slug, "version": vm.group(1) if vm else "?",
+                    "frozen": date.today().isoformat(), "hash": _contract_body_hash(raw3c)}
+            sp = _contract_snapshot(root, _prod)
+            cur_snap = None
+            if sp.exists():
+                try:
+                    cur_snap = json.loads(sp.read_text(encoding="utf-8"))
+                except (OSError, ValueError):
+                    cur_snap = None
+            # idempotent: re-write only when the shape-hash or version actually changed (so a
+            # no-op re-cross leaves the file — and its `frozen` date — byte-identical).
+            if not (cur_snap and cur_snap.get("hash") == snap["hash"]
+                    and cur_snap.get("version") == snap["version"]):
+                sp.parent.mkdir(parents=True, exist_ok=True)
+                _atomic_write(sp, json.dumps(snap, sort_keys=True))
+        _cons = _task_consumes(root, slug)
+        if _cons:
+            sp = _contract_snapshot(root, _cons)
+            try:
+                pinned = json.loads(sp.read_text(encoding="utf-8")).get("hash")
+            except (OSError, ValueError, AttributeError):
+                pinned = None
+            if not pinned:        # absent / unreadable / valid-JSON-but-no-hash all fail loud
+                _die(f"contract_snapshot_missing: no readable hashed .add/contracts/{_cons}.json — the "
+                     f"producer of '{_cons}' must freeze its contract first "
+                     "(never build against a guessed shape)")
+            state["tasks"][slug]["contract_pin"] = {"id": _cons, "hash": pinned}
     state["tasks"][slug]["phase"] = nxt
     state["tasks"][slug]["updated"] = _now()
     _sync_task_marker(root, slug, nxt)
@@ -1162,6 +1363,14 @@ _AUTONOMY_LEVELS = ("manual", "conservative", "auto")
 # and reads as UNSET.
 _AUTONOMY_LINE_RE = re.compile(r"(?:^|·)[ \t]*autonomy:[ \t]*([^\s<#|]+)", re.MULTILINE)
 
+# component-aware-add: a task binds to a registered component via a `component: <name>`
+# header token — the SAME anchored grammar as autonomy (line-start or the `·`-inline
+# slug-line form), and an unfilled `<name>` placeholder captures nothing (reads UNBOUND).
+_COMPONENT_LINE_RE = re.compile(r"(?:^|·)[ \t]*component:[ \t]*([^\s<#|]+)", re.MULTILINE)
+# cross-component-contract: a task's role in a cross-component seam — same anchored grammar.
+_PRODUCES_LINE_RE = re.compile(r"(?:^|·)[ \t]*produces:[ \t]*([^\s<#|]+)", re.MULTILINE)
+_CONSUMES_LINE_RE = re.compile(r"(?:^|·)[ \t]*consumes:[ \t]*([^\s<#|]+)", re.MULTILINE)
+
 
 def _autonomy_level(hdr: str):
     """The declared autonomy rung from a TASK.md header region (HTML comments
@@ -1260,6 +1469,18 @@ def cmd_gate(args: argparse.Namespace) -> None:
         # §5 scope gate (build-scope-lock): touched ⊆ declared, or a named refusal —
         # same placement discipline as the tripwire (before the waiver, never on HARD-STOP).
         _scope_guard(root, state, slug)
+        # per-component verify (component-aware-add): a component-bound task with a declared
+        # green_bar must CITE that bar in its §6 evidence before a completing outcome — the
+        # engine never runs the suite, it checks the right bar was recorded. Unbound / no
+        # green_bar -> _bar is None -> this is skipped (byte-identical). HARD-STOP never here.
+        _bar = _task_green_bar(root, slug)
+        # the cite must live in the user-authored Build-expectations evidence region (_cite_region,
+        # v3): excludes the §6 checklist boilerplate + the GATE RECORD template/stamp, works for both
+        # the standard and fast-lane §6 shapes. Unbound / no green_bar -> _bar None -> skipped.
+        if _bar and _bar not in _cite_region(_raw_phase_bodies(root, slug).get(6, "")):
+            _die(f"component_green_bar_uncited: task '{slug}' is bound to component "
+                 f"'{_task_component(root, slug)}'; its §6 Build-expectations must cite the "
+                 f"green-bar '{_bar}' — record the evidence that bar was met before PASS")
     if args.outcome == "RISK-ACCEPTED":
         # A waiver must be SIGNED: owner, ticket, expiry (glossary). Stored in state
         # so a later `check` can read/expire it. Refuse a partial waiver outright.
@@ -1279,6 +1500,9 @@ def cmd_gate(args: argparse.Namespace) -> None:
     save_state(root, state)
     _stamp_gate_record(root, state, slug, args.outcome)   # mirror the verdict into §6 (Finding C)
     print(f"task '{slug}' gate -> {args.outcome}")
+    _gbar = _task_green_bar(root, slug)                   # per-component-verify: surface the bound bar
+    if _gbar:
+        print(f"component: {_task_component(root, slug)} · expected green-bar: {_gbar}")
     # the engine-sourced next step (next-footer-engine): a completing gate hands off to the
     # state arm; HARD-STOP routes to "resolve HARD-STOP …" — converging the old bespoke line.
     print(_next_footer(root, state))
@@ -1575,6 +1799,38 @@ def cmd_stage(args: argparse.Namespace) -> None:
     print(_next_footer(root, state))
 
 
+def _done_resume(root: Path, state: dict, slug: str) -> tuple[str, str, str]:
+    """At a DONE task, what should the agent do NEXT? Classify from the task's
+    milestone exit-criteria tally (_exit_criteria) so the orient surfaces (status,
+    guide) STEER into the loop instead of always saying "start the next feature".
+
+    Returns (headline, next_step, chapter) where chapter is a docs/ filename:
+      LOOP-JUNCTURE  total>0 and met<total -> name the unmet goal, route to the loop
+      GOAL-MET       total>0 and met==total -> point at milestone-done
+      PLAIN          no criteria / no milestone / any read error -> today's "next feature"
+    PURE and fail-closed (design-for-failure): a missing milestone or unreadable
+    MILESTONE.md degrades to PLAIN — it never raises into a status/guide print path."""
+    PLAIN = ("this task is done",
+             "start the next feature -> add.py new-task <slug>",
+             "02-the-flow.md")
+    try:
+        ms = ((state.get("tasks") or {}).get(slug) or {}).get("milestone")
+        if not ms:
+            return PLAIN
+        met, total = _exit_criteria(root, ms)
+    except Exception:                       # noqa: BLE001 — never break orient output
+        return PLAIN
+    if total > 0 and met < total:
+        return (f"milestone '{ms}' goal not met ({met}/{total} exit criteria)",
+                "propose the next tasks from open deltas / the unscaffolded plan -> add.py deltas",
+                "09-the-loop.md")
+    if total > 0 and met == total:
+        return (f"milestone '{ms}' goal met ({met}/{total})",
+                f"close it -> add.py milestone-done {ms}",
+                "09-the-loop.md")
+    return PLAIN
+
+
 def cmd_status(args: argparse.Namespace) -> None:
     if getattr(args, "json", False):
         root, state = _load_state_for_json()
@@ -1769,8 +2025,16 @@ def cmd_status(args: argparse.Namespace) -> None:
     elif active and active in tasks:
         ph = tasks[active]["phase"]
         if ph == "done":
+            # loop-aware resume (loop-aware-orient): a done task is NOT always "start the
+            # next feature" — if its milestone goal is unmet we are at the loop juncture, so
+            # STEER into the loop; if met, point at the close. PLAIN stays byte-identical.
+            _hl, _nxt, _chap = _done_resume(root, state, active)
             print(f"\nresume  : task '{active}' is done ({tasks[active]['gate']}).")
-            print("          start the next feature: add.py new-task <slug>")
+            if _chap == "02-the-flow.md":
+                print("          start the next feature: add.py new-task <slug>")
+            else:
+                print(f"          {_hl} — {_nxt}")
+                print(f"          (the loop: .add/docs/{_chap})")
         else:
             print(f"\nresume  : task '{active}' is at phase '{ph}'.")
             print(f"          read .add/tasks/{active}/TASK.md and continue that phase.")
@@ -1820,6 +2084,10 @@ def cmd_guide(args: argparse.Namespace) -> None:
         phase = t.get("phase")
         owner = _phase_owner(phase)            # _die unmapped_phase before any stdout
         action, chapter = PHASE_GUIDE[phase]   # phase is mapped, so PHASE_GUIDE has it too
+        if phase == "done":                    # loop-aware-orient: steer the --json surface too
+            _hl, _nxt, _chap = _done_resume(json_root, state, slug)
+            if _chap != "02-the-flow.md":      # loop juncture / goal met; PLAIN stays unchanged
+                action, chapter = _nxt, _chap
         print(json.dumps({"task": slug, "phase": phase, "owner": owner,
                           "stop": owner != "ai", "next_step": action,
                           "chapter": f".add/docs/{chapter}", "gate": t.get("gate"),
@@ -1840,6 +2108,10 @@ def cmd_guide(args: argparse.Namespace) -> None:
     if entry is None:           # corrupted/hand-edited state.json — fail clean, not KeyError
         _die(f"task '{slug}' has unknown phase '{phase}' (state.json corrupted?)")
     action, chapter = entry
+    if phase == "done":                        # loop-aware-orient: steer at the loop juncture
+        _hl, _nxt, _chap = _done_resume(root, state, slug)
+        if _chap != "02-the-flow.md":          # loop juncture / goal met; PLAIN stays unchanged
+            action, chapter = _nxt, _chap
     # the guide names the driver too (task gate-owner-marker) — the SAME _driver_stop the
     # footer renders, on the next-step line. Computed AFTER the unknown-phase guard above,
     # so a bad phase fails clean and never reaches the marker (it invents no default).
@@ -1856,7 +2128,10 @@ def cmd_guide(args: argparse.Namespace) -> None:
     if phase == "verify":
         print("then   : add.py gate PASS | RISK-ACCEPTED | HARD-STOP")
     elif phase == "done":
-        print("then   : start the next feature -> add.py new-task <slug>")
+        if chapter != "02-the-flow.md":        # loop juncture / goal met -> the steered command
+            print(f"then   : {action}")
+        else:
+            print("then   : start the next feature -> add.py new-task <slug>")
     else:
         print("then   : add.py advance")
 
@@ -2292,6 +2567,41 @@ def _missing_captures(root: Path) -> list[str]:
             if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
 
 
+def cmd_federate(args: argparse.Namespace) -> None:
+    """Multi-repo federation: pull a producer repo's published, immutable contract snapshot into
+    this repo. Mono vs multi-repo differ ONLY in snapshot-transport — this lands the byte-copy at
+    the SAME local `.add/contracts/<id>.json` the monorepo path (tasks 3/4) already reads, so a
+    `consumes: <id>` task then holds/pins identically. Designed-for-failure: unknown / missing /
+    invalid / version-mismatched sources HARD-STOP and land NOTHING (never build blind)."""
+    root = find_root()
+    if root is None:
+        _die("no_project")
+    fid = args.id
+    fed = _federation(root)
+    if fid not in fed:
+        _die(f"federation_unknown: no [federation.{fid}] in components.toml — declare the producer "
+             f"repo's published snapshot source before pulling")
+    source = (root.parent / fed[fid]["source"])
+    try:
+        raw = source.read_bytes()       # bytes — the landed snapshot must be a byte-for-byte copy
+    except OSError:
+        _die(f"federation_source_missing: cannot read the producer snapshot at '{fed[fid]['source']}' "
+             f"(resolved {source}) — publish/commit it in the producer repo first")
+    try:
+        snap = json.loads(raw.decode("utf-8"))
+    except (json.JSONDecodeError, ValueError, UnicodeDecodeError):
+        snap = None
+    if not isinstance(snap, dict) or snap.get("id") != fid or not snap.get("hash"):
+        _die(f"federation_snapshot_invalid: the source for '{fid}' is not a valid contract snapshot "
+             f"(needs JSON with matching id + a hash) — refusing to land a guessed shape")
+    pin = fed[fid]["pin"]
+    if pin and snap.get("version") != pin:
+        _die(f"federation_version_mismatch: [federation.{fid}] pins '{pin}' but the source is "
+             f"'{snap.get('version')}' — bump the pin or wait for the producer to publish {pin}")
+    _atomic_write_bytes(_contract_snapshot(root, fid), raw)
+    print(f"federated '{fid}' {snap.get('version', '?')} {snap['hash']} from {fed[fid]['source']}")
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Read-only integrity check of the .add project. Exit 1 if anything fails."""
     as_json = getattr(args, "json", False)
@@ -2340,6 +2650,29 @@ def cmd_check(args: argparse.Namespace) -> None:
         if _alvl is None and t.get("phase") not in ("done", "observe"):
             warnings.append((f"task '{slug}'", "has no explicit autonomy level (implicit_autonomy) "
                              "— run `add.py autonomy set <level>` to set it"))
+        # per-component-verify: a bound task whose component declares no green_bar can't be
+        # gated on a bar — surface it (WARN, never red). Unbound / "?" -> silent.
+        _tc = _task_component(root, slug)
+        if _tc and _tc != "?" and not (_components(root).get(_tc) or {}).get("green_bar"):
+            warnings.append((f"task '{slug}'", f"component_green_bar_unset — bound component '{_tc}' "
+                             "declares no green_bar; the per-component gate cannot check a bar"))
+        # cross-component-contract: a consumer whose pinned hash drifted from the live snapshot
+        # (the producer re-froze a CHANGED shape) — the §7-stale cue. Degrade-safe (unreadable
+        # snapshot ⇒ no finding here; the missing-snapshot HARD-STOP lives at the advance crossing).
+        _pin = t.get("contract_pin")
+        if _pin:
+            try:
+                _live = json.loads(_contract_snapshot(root, _pin["id"]).read_text(encoding="utf-8")).get("hash")
+            except (OSError, ValueError, KeyError, TypeError, AttributeError):
+                _live = None
+            if _live is None:                # missing / corrupt / hash-less ⇒ SURFACE, never mask
+                warnings.append((f"task '{slug}'", f"contract_snapshot_unreadable — pinned contract "
+                                 f"'{_pin.get('id')}' snapshot is missing or corrupt; re-publish the "
+                                 "producer contract (cannot confirm the pin is current)"))
+            elif _live != _pin.get("hash"):
+                warnings.append((f"task '{slug}'", f"contract_consumer_stale — pinned contract "
+                                 f"'{_pin.get('id')}' changed shape since pin; re-pin (re-cross contract→tests) "
+                                 "after reviewing the producer's new frozen shape"))
         for dep in t.get("depends_on") or []:
             checks.append((dep in tasks or dep in archived_slugs,
                            f"task '{slug}' dep '{dep}' resolves", "unknown task"))
@@ -2453,6 +2786,26 @@ def cmd_check(args: argparse.Namespace) -> None:
     checks.append((cycle is None, "task dependencies are acyclic",
                    f"cycle: {' -> '.join(cycle)}" if cycle else ""))
 
+    # component registry (component-aware-add): a malformed .add/components.toml, a root
+    # escaping the project, or a task binding an unregistered component are integrity FAILS
+    # — fail-closed RED (like wave_ledger_malformed), loud but never a crash (the readers
+    # themselves degrade-safe). Silent when there is no components.toml.
+    for _ccode, _cdetail in _component_findings(root):
+        checks.append((False, f"component registry ({_ccode})", _cdetail))
+    # cross-component-contract: a [contract.<id>] naming an unregistered producer is an
+    # integrity FAIL (same fail-closed RED discipline; the readers stay degrade-safe).
+    for _ccode, _cdetail in _contract_findings(root):
+        checks.append((False, f"contract registry ({_ccode})", _cdetail))
+    # multirepo-federation: a declared [federation.<id>] whose producer-repo source is unreadable
+    # is a BROKEN JOIN — surface it EARLY as a WARN (never red alone; `federate pull` is where it
+    # HARD-STOPs). Silent when no federation is declared (opt-in / byte-identical).
+    for _fid, _fspec in _federation(root).items():
+        if not (root.parent / _fspec["source"]).is_file():
+            warnings.append((f"federation '{_fid}'",
+                             f"federation_source_unreadable — the producer snapshot at "
+                             f"'{_fspec['source']}' is missing/unreadable; `federate pull {_fid}` "
+                             "will hard-stop until the producer repo publishes it"))
+
     # UDD foundation (udd-check-lint): lint a project's named set under .add/design/ —
     # composes the token + catalog/tree validators + the cross-file prop-token resolution.
     # Silent when absent; read-only; fail-closed on malformed JSON.
@@ -3701,6 +4054,204 @@ _SCOPE_EXCLUDE_FILES = (".DS_Store",)                  # plus *.pyc / *.tsbuildi
 _SCOPE_EXCLUDE_SUFFIXES = (".pyc", ".tsbuildinfo")
 
 
+# ── component registry (component-aware-add): declared components + task binding ─────
+# OPT-IN + DEGRADE-SAFE: with no .add/components.toml every reader is byte-identical to
+# pre-component ADD. A read NEVER raises (absent/unreadable/malformed → {} / dropped
+# cover); the loud surface is _component_findings, consumed by the scope gate (cmd_check).
+def _components(root: Path) -> dict[str, dict]:
+    """The registry from .add/components.toml → {name: {root, verify, green_bar,
+    language}}. `root` required per entry; an entry missing it is skipped (the finding
+    surface reports it). `verify` is stored OPAQUE — parsed as data, NEVER executed. PURE."""
+    if tomllib is None:
+        return {}
+    try:
+        raw = (root / "components.toml").read_bytes()
+    except OSError:
+        return {}
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
+        return {}
+    out: dict[str, dict] = {}
+    for name, spec in (data.get("component") or {}).items():
+        # "?" is the reserved unknown-binding sentinel (_task_component) — a component
+        # named "?" would collide and silently drop cover, so it never registers.
+        if name == "?" or not isinstance(spec, dict) or not isinstance(spec.get("root"), str):
+            continue
+        out[name] = {"root": spec["root"], "verify": spec.get("verify"),
+                     "green_bar": spec.get("green_bar"), "language": spec.get("language")}
+    return out
+
+
+def _component_root(root: Path, name: str) -> str | None:
+    """Project-root-relative path (trailing '/') of component `name`'s root, or None
+    when the name is absent OR the root escapes the project (fail-closed — grants no
+    scope cover, mirroring _declared_scope's _confined drop). PURE."""
+    spec = _components(root).get(name)
+    if not spec:
+        return None
+    rootp = root.parent.resolve()
+    p = root.parent / spec["root"]
+    if not _confined(p, rootp):
+        return None
+    try:
+        return str(p.resolve().relative_to(rootp)).rstrip("/") + "/"
+    except (OSError, ValueError):
+        return None
+
+
+def _task_component(root: Path, slug: str):
+    """The component a task binds to via its `component:` header token (anchored like
+    autonomy). None = no line / unfilled `<…>` placeholder; "?" = a real token absent
+    from the registry; otherwise the component name. PURE."""
+    m = _COMPONENT_LINE_RE.search(_task_header(root, slug))
+    if not m:
+        return None
+    tok = m.group(1).strip()
+    return tok if tok in _components(root) else "?"
+
+
+def _task_green_bar(root: Path, slug: str) -> str | None:
+    """The green_bar phrase of the task's bound component (per-component-verify), else
+    None — unbound, "?", or no green_bar declared all yield None. PURE."""
+    comp = _task_component(root, slug)
+    if not comp or comp == "?":
+        return None
+    return (_components(root).get(comp) or {}).get("green_bar") or None
+
+
+def _cite_region(body: str) -> str:
+    """The user-authored "Build expectations" evidence region of a §6 body, stamp-stripped —
+    the only place a per-component green-bar cite counts (per-component-verify, v3). PURE.
+
+    The marker matches BOTH template shapes: the standard "### Build expectations …" heading AND
+    the fast-lane bare "Build expectations (from …):" line, running up to the GATE RECORD sub-block.
+    So the top-of-§6 checklist ("- [ ] all tests pass") and the "Outcome: <PASS|…>" placeholder are
+    excluded, and a component-bound FAST task is still citable. The trailing strip removes the
+    engine's own "component: … · expected green-bar: …" stamp wherever it landed, so a stamp that
+    fell inside the region can never self-satisfy the gate. No marker -> "" (fail-closed for a bound
+    task: it must declare its evidence)."""
+    m = re.search(r"(?im)^#*[ \t]*Build expectations\b.*?(?=\n#+[ \t]*GATE RECORD\b|\Z)", body, re.DOTALL)
+    region = m.group(0) if m else ""
+    return re.sub(r"(?m)^component:.*·.*expected green-bar:.*$", "", region)
+
+
+def _component_findings(root: Path) -> list[tuple[str, str]]:
+    """The loud gate surface for the registry — the codes a degrade-safe read passes
+    over silently. Consumed by cmd_check (the scope_violation surface). [] when clean."""
+    findings: list[tuple[str, str]] = []
+    try:
+        raw = (root / "components.toml").read_bytes()
+    except OSError:
+        return findings                       # absent/unreadable = opt-out, nothing to report
+    data = None
+    if tomllib is None:
+        findings.append(("components_malformed", "components.toml present but tomllib unavailable (Python < 3.11)"))
+    else:
+        try:
+            data = tomllib.loads(raw.decode("utf-8"))
+        except (tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError) as e:
+            findings.append(("components_malformed", f"components.toml: {e}"))
+    if data is not None:
+        rootp = root.parent.resolve()
+        for name, spec in (data.get("component") or {}).items():
+            if name == "?":
+                findings.append(("components_malformed", "component name '?' is reserved (the unknown-binding sentinel)"))
+                continue
+            if not isinstance(spec, dict) or not isinstance(spec.get("root"), str):
+                findings.append(("components_malformed", f"[component.{name}] missing required `root`"))
+                continue
+            if not _confined(root.parent / spec["root"], rootp):
+                findings.append(("component_root_outside", f"[component.{name}] root {spec['root']!r} escapes the project"))
+    known = set(_components(root))
+    try:
+        task_dirs = sorted(p for p in (root / "tasks").iterdir() if p.is_dir())
+    except OSError:
+        task_dirs = []                       # unreadable tasks/ degrades safe — never crash a read
+    for d in task_dirs:
+        tc = _task_component(root, d.name)
+        if tc is not None and tc not in known:      # "?" or a stale name
+            findings.append(("component_unknown", f"task {d.name} binds an unregistered component"))
+    return findings
+
+
+# ── cross-component contracts (cross-component-contract) ──────────────────────────────────
+# OPT-IN + DEGRADE-SAFE, like the component readers: no [contract.*] / no produces|consumes
+# header ⇒ every path below is byte-identical to pre-contract ADD. A read NEVER raises.
+def _contracts(root: Path) -> dict[str, dict]:
+    """[contract.<id>] from .add/components.toml -> {id: {producer: str, consumers: list[str]}}.
+    A malformed entry (producer not a str) is skipped (the finding surface reports it). PURE."""
+    if tomllib is None:
+        return {}
+    try:
+        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
+        return {}
+    out: dict[str, dict] = {}
+    for cid, spec in (data.get("contract") or {}).items():
+        if not isinstance(spec, dict) or not isinstance(spec.get("producer"), str):
+            continue
+        cons = spec.get("consumers")
+        out[cid] = {"producer": spec["producer"],
+                    "consumers": [c for c in cons if isinstance(c, str)] if isinstance(cons, list) else []}
+    return out
+
+
+def _federation(root: Path) -> dict[str, dict]:
+    """[federation.<id>] from .add/components.toml -> {id: {source: str, pin: str|None}}.
+    The cross-REPO join: a consumer repo names where a producer repo's published snapshot lives.
+    A malformed entry (no string source) is skipped; a non-string `pin` degrades to None. Degrade-safe
+    — never raises. PURE. On Python < 3.11 (no tomllib) this returns {} like the other component
+    readers, so `federate` reports federation_unknown — components.toml needs a 3.11+ runtime."""
+    if tomllib is None:
+        return {}
+    try:
+        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
+        return {}
+    out: dict[str, dict] = {}
+    for fid, spec in (data.get("federation") or {}).items():
+        if not isinstance(spec, dict) or not isinstance(spec.get("source"), str):
+            continue
+        pin = spec.get("pin")
+        out[fid] = {"source": spec["source"], "pin": pin if isinstance(pin, str) else None}
+    return out
+
+
+def _task_produces(root: Path, slug: str) -> str | None:
+    m = _PRODUCES_LINE_RE.search(_task_header(root, slug))
+    return m.group(1).strip() if m else None
+
+
+def _task_consumes(root: Path, slug: str) -> str | None:
+    m = _CONSUMES_LINE_RE.search(_task_header(root, slug))
+    return m.group(1).strip() if m else None
+
+
+def _contract_snapshot(root: Path, cid: str) -> Path:
+    return root / "contracts" / f"{cid}.json"
+
+
+def _contract_body_hash(raw3: str) -> str:
+    """md5 of the §3 contract SHAPE — the first ```fenced``` block, whitespace-normalized. The
+    version stamp + freeze flags are excluded (fallback strips Status:/flag/change-request lines)
+    so a pure version bump does NOT churn pinned consumers stale. PURE."""
+    m = re.search(r"```(.*?)```", raw3, re.DOTALL)
+    body = m.group(1) if m else re.sub(r"(?m)^(Status:|.*surfaced at freeze:|v\d+ CHANGE REQUEST).*$", "", raw3)
+    return _md5_text(re.sub(r"\s+", " ", body).strip())
+
+
+def _contract_findings(root: Path) -> list[tuple[str, str]]:
+    """The loud gate surface for cross-component contracts — [] when clean / opted-out."""
+    findings: list[tuple[str, str]] = []
+    known = set(_components(root))
+    for cid, spec in _contracts(root).items():
+        if spec["producer"] not in known:
+            findings.append(("contract_producer_unknown",
+                             f"[contract.{cid}] producer {spec['producer']!r} is not a declared component"))
+    return findings
+
+
 def _declared_scope(root: Path, slug: str) -> list[str] | None:
     """Resolve the §5 'Scope (may touch):' declaration to project-root-relative
     strings (directory tokens keep a trailing '/'). The frozen scope-decl-template
@@ -3710,11 +4261,19 @@ def _declared_scope(root: Path, slug: str) -> list[str] | None:
     root, fail-closed — with ONE divergence: a directory token covers its WHOLE
     subtree (containment, judged by _in_scope). None = no Scope line (UNDECLARED,
     grandfathered — never retro-red); [] = a line whose every token was dropped
-    (a garbage declaration grants NO cover)."""
+    (a garbage declaration grants NO cover).
+
+    component-aware-add: when the task binds a known `component:` (_task_component),
+    that component's root subtree (_component_root) is APPENDED to the resolved tokens
+    (dedup) — composing with the explicit declaration, never redrawing token resolution.
+    A bound task with NO Scope line returns [component_root] (not None); an UNBOUND task
+    is byte-identical to before."""
+    comp = _task_component(root, slug)
+    croot = _component_root(root, comp) if comp and comp != "?" else None
     body = _raw_phase_bodies(root, slug).get(5, "")
     m = re.search(r"^\s*Scope \(may touch\):.*$", body, re.M)
     if not m:
-        return None
+        return [croot] if croot else None
     tdir = root / "tasks" / slug
     rootp = root.parent.resolve()
     out: list[str] = []
@@ -3740,6 +4299,8 @@ def _declared_scope(root: Path, slug: str) -> list[str] | None:
             continue
         if rel not in out:
             out.append(rel)
+    if croot and croot not in out:        # component-aware-add: compose, never redraw
+        out.append(croot)
     return out
 
 
@@ -5847,6 +6408,9 @@ def build_parser() -> argparse.ArgumentParser:
     pi.add_argument("--force", action="store_true", help="reset state.json if present")
     pi.add_argument("--await-lock", dest="await_lock", action="store_true",
                     help="seed an unlocked setup; gates new-task/advance/gate until `add.py lock`")
+    pi.add_argument("--rule-file", dest="rule_file", action="store_true",
+                    help="write the ADD block to .claude/rules/add-workflows.md and reference it "
+                         "from CLAUDE.md (auto-on for ccsk projects with a .ccsk/ dir)")
     pi.set_defaults(func=cmd_init)
 
     pl = sub.add_parser("lock",
@@ -6033,6 +6597,14 @@ def build_parser() -> argparse.ArgumentParser:
     pck.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pck.set_defaults(func=cmd_check)
 
+    pfed = sub.add_parser("federate", help="multi-repo: pull a producer repo's published, immutable "
+                                           "contract snapshot into this repo (fail-loud)")
+    pfedsub = pfed.add_subparsers(dest="action", required=True)
+    pfedpull = pfedsub.add_parser("pull", help="land [federation.<id>].source at the local "
+                                               ".add/contracts/<id>.json (hard-stops on a bad source)")
+    pfedpull.add_argument("id", help="the contract id declared under [federation.<id>]")
+    pfedpull.set_defaults(func=cmd_federate)
+
     pdoc = sub.add_parser("doctor", help="read-only diagnosis of state.json integrity + "
                                          "referential consistency (run after a git merge)")
     pdoc.set_defaults(func=cmd_doctor)
@@ -6053,6 +6625,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     psg = sub.add_parser("sync-guidelines",
                          help="(re)write the ADD guideline block into AGENTS.md + CLAUDE.md")
+    psg.add_argument("--rule-file", dest="rule_file", action="store_true",
+                     help="relocate CLAUDE.md's block to .claude/rules/add-workflows.md + reference "
+                          "it (auto-on for ccsk projects)")
     psg.set_defaults(func=cmd_sync_guidelines)
 
     pgd = sub.add_parser("guide", help="print the one concrete next step for the active task")

package/tooling/templates/TASK.md.tmpl

@@ -1,7 +1,7 @@
 # TASK: {{title}}
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
-autonomy: {{autonomy}}   <!-- inherited from the project default (PROJECT.md); explicit level: manual < conservative < auto (visible · overridable) — lower below if a high-risk task needs it, or run `add.py autonomy set`. -->
+autonomy: {{autonomy}}   <!-- inherited from the project default (PROJECT.md); explicit level: manual < conservative < auto (visible · overridable) — lower below if a high-risk task needs it, or run `add.py autonomy set`. Multi-component repo (monorepo/multi-repo)? add a `component: <name>` line (declared in `.add/components.toml`) to ADD that component's root to your §5 Scope; omit for single-component projects (byte-identical default). -->
 phase: ground   <!-- ground -> specify -> scenarios -> contract -> tests -> build -> verify -> observe -> done -->
 <!-- high-risk/method-defining scope? declare `risk: high` on the slug line above and lower the
      autonomy level to `manual` or `conservative` — the engine refuses an unguarded completion