@pilotspace/add 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,110 @@ 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.11.0] — 2026-06-26
+
+Engine-modularization + audit-hardening release — the 7k-line monolith becomes a
+navigable package, the verify/atomicity/coverage gates get five fixes, and the
+standalone (milestone-free) lane becomes first-class. **No behavior change** to the
+CLI, the flow, or any output: this is an internal architecture + hardening release.
+
+### Changed
+- **The engine is now a focused package.** `add-method/tooling/add.py` (7049 → 5640
+  lines, −20%) split into **13 `add_engine/*.py` modules** — `constants`, `io_state`,
+  `accessors`, `predicates`, `identity`, `guidelines`, `render`, `milestones`,
+  `components`, `version`, `release`, `taskdoc`, `autonomy` — behind a stable
+  re-export surface (`import add; add.<name>` still resolves, public AND `_`-prefixed,
+  so every existing test is untouched). `add.py` stays the runnable **orchestrator
+  entry** (the `load_state`/`save_state`/`report_data`/`cmd_*`/`main` spine). Each of
+  the 16 extractions was its own CI-green PR, proven verbatim by an AST source-segment
+  diff and gated by the full suite (1815 → 1959 green throughout, no test weakened).
+- **Two-pin integrity model.** Alongside `ENGINE_MD5` (md5 of `add.py`),
+  `ENGINE_PKG_MD5` is a manifest digest over every `add_engine/*.py`; both are literal
+  pins (never self-hashed) and are checked byte-identical across the 3-tree mirror
+  (canonical · `.add` · `_bundled`). `prepare_bundle` + both installers + the `.add`
+  mirror now ship the whole `add_engine/` package.
+
+### Fixed (audit-hardening)
+- Five gate/atomicity/coverage fixes: a phase-build guard, hardened save-state
+  atomicity, force-preserve self-healing, setup-tests-before-build ordering, and a
+  consumer-stale gate. A security finding remains an un-forceable HARD-STOP.
+
+### Added (the standalone / lightweight lane)
+- **`add.py todo`** — capture a milestone-free backlog item without scaffolding a task.
+- **`loose tasks:` release attribution** — a release now attributes *any* done,
+  milestone-free task on its `RELEASES.md` row (not only milestone membership), with a
+  separate status cue for releasable loose work.
+- **`fast` (task) + `auto` (mode) flag modes** — the standalone lane is first-class:
+  a minimal `TASK.fast.md`, freeze-gated under any milestone, with a flag-mode quick
+  reference.
+
+This release bundles **2 closed milestones** (`audit-hardening`,
+`engine-modularization`) and **27 loose tasks** since 1.10.0.
+
+## [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
@@ -439,6 +562,57 @@ function writeGeminiSettings(target) {
   }
 }
 
+// Seed .add/SOUL.md from the bundled template if it does not yet exist. Mirror of
+// _installer.py:_seed_soul_md (npm <-> pip parity): skip-if-exists (SOUL.md is
+// user-owned — never clobber); fail-soft (warn + return, never abort install/update).
+function seedSoulMd(target) {
+  const dest = path.join(target, ".add", "SOUL.md");
+  if (fs.existsSync(dest)) return;                       // skip-if-exists (never clobber)
+  const source = path.join(PKG_ROOT, "tooling", "templates", "SOUL.md.tmpl");
+  if (!fs.existsSync(source)) {
+    warn("soul_seed_skipped: SOUL.md.tmpl not found in bundled tooling/templates/");
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(source, "utf8"));
+  } catch (e) {
+    warn("soul_seed_skipped: could not write .add/SOUL.md — " + (e && e.message ? e.message : e));
+  }
+}
+
+// Ensure .add/.gitignore lists the engine's transient artifacts. Seed it from the bundled
+// tooling/templates/gitignore.tmpl if absent; else APPEND-IF-ABSENT each pattern line the
+// template carries that the file lacks — additive only, never reorders/removes user lines,
+// idempotent; comment/blank lines are not appended to an existing file. Fail-soft. Twin of
+// _installer.py:_seed_gitignore.
+function seedGitignore(target) {
+  const source = path.join(PKG_ROOT, "tooling", "templates", "gitignore.tmpl");
+  if (!fs.existsSync(source)) {
+    warn("gitignore_seed_skipped: gitignore.tmpl not found in bundled tooling/templates/");
+    return;
+  }
+  const dest = path.join(target, ".add", ".gitignore");
+  try {
+    const body = fs.readFileSync(source, "utf8");
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, body);                       // seed-if-missing
+      return;
+    }
+    const current = fs.readFileSync(dest, "utf8");
+    const have = new Set(current.split("\n").map((l) => l.trim()));
+    const missing = body.split("\n").filter(
+      (l) => l.trim() && !l.trim().startsWith("#") && !have.has(l.trim())
+    );
+    if (missing.length === 0) return;                     // idempotent — nothing to add
+    const suffix = current === "" || current.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(dest, current + suffix + missing.join("\n") + "\n");
+  } catch (e) {
+    warn("gitignore_seed_skipped: could not update .add/.gitignore — " + (e && e.message ? e.message : e));
+  }
+}
+
 // The drop — now a RECONCILE: restore missing managed trees + refresh present ones
 // (sweep orphans) + report per-tree status. Byte-compatible handoff with the prior
 // installer. The interactive path resolves a target then calls straight into this.
@@ -446,11 +620,22 @@ function dropFiles(args, target, profile, intent) {
   profile = profile || detectAgent(process.env);
   log("Installing ADD into " + target);
   reconcile(args, target);
+  seedSoulMd(target);   // pip parity: re-seed a missing user-owned SOUL.md (never clobber)
+  seedGitignore(target);   // pip parity: seed/append-if-absent the engine-transient ignore lines
 
   // 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.
@@ -800,6 +985,8 @@ function cmdUpdate(args) {
     fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
   }
   reconcile(args, target);
+  seedSoulMd(target);   // pip parity: re-seed a missing user-owned SOUL.md (never clobber)
+  seedGitignore(target);   // pip parity: seed/append-if-absent the engine-transient ignore lines
   writeStamp(addDir, version);
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
       " · managed layer reconciled · your project state untouched.");
@@ -847,4 +1034,7 @@ module.exports = {
   scopeOptions: scopeOptions,
   writeIntentNote: writeIntentNote,
   writeGeminiSettings: writeGeminiSettings,
+  ruleFileMode: ruleFileMode,
+  ensureClaudeReference: ensureClaudeReference,
+  writeRuleFilePointer: writeRuleFilePointer,
 };

package/docs/09-the-loop.md

@@ -51,7 +51,7 @@ Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evide
 
 **The consolidation.** At milestone close (or on demand, when open deltas pile up), a person runs the retrospective consolidation: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only, newest-first (the newest record prepended at the top) — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas consolidate into the matching section of `PROJECT.md`; `TDD`/`ADD` consolidate into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** consolidation also prepends one row at the top of `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
 
-**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be consolidated is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. There is deliberately **no `add.py fold`**: the engine stays judgment-free, and the ritual lives with the human who owns it.
+**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be consolidated is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. `add.py fold [--task <slug>] [--comp <TAG>]` mechanizes the consolidation — flip + transcribe + route + bump, validate-all-then-write so a reject leaves the tree byte-unchanged; running it **is** the human's confirmation, and the engine never self-approves *which* lessons to keep.
 
 **Foundation compaction.** The consolidation *prepends* new learnings; **foundation compaction** is the separate, later step that *shrinks* the result. At milestone close (or on demand, once a foundation spec grows past one screen), the AI proposes collapsing the stable, shipped, zero-residue tail of each foundation spec into ONE per-spec **rolled-up settled line** at the bottom — and the human confirms, one line at a time, exactly as with the consolidation. It never deletes: a settled line summarizes the prose and keeps a `see git` pointer, so the record is lossy on wording but lossless on traceability, and any OPEN residue always stays live. Each spec collapses in its own **per-spec shape** — `PROJECT.md` §Spec version bullets, §Key-Decisions rows, `CONVENTIONS.md` learnings, the `GLOSSARY.md` definition, the `MODEL_REGISTRY.md` rows — under one shared eligibility rule. Because every append-only sequence is **newest-first** (newest record on top), compaction collapses *upward from the bottom*: the settled line anchors at the tail (the oldest end). Like the consolidation it is convention-guided — there is deliberately no `add.py` command for it (read `compact-foundation.md`) — and it is distinct from the engine's `add.py compact <slug>`, which archives a finished milestone's files rather than shrinking a living spec.
 

package/docs/11-governance.md

@@ -31,7 +31,7 @@ Every checkpoint produces three short reports — **Test** (does it pass?), **Qu
 
 - **`PASS`** — criteria met; proceed.
 - **`RISK-ACCEPTED`** — proceed with a signed waiver carrying a named owner, a linked ticket, and an expiry. Allowed for non-security gaps only.
-- **`HARD-STOP`** — cannot proceed. Triggered by any failing test or any security finding; overridable only by the most senior accountable owner, and never for security.
+- **`HARD-STOP`** — cannot proceed. Triggered by any failing test or any security finding. A non-security limitation may proceed only with a signed `RISK-ACCEPTED` record carrying an owner and an expiry; security is never waved through.
 
 The rule behind the protocol is *no silent skips.* A report nobody is accountable for approving is just a document; an outcome with an owner is governance.
 

package/docs/14-foundation.md

@@ -56,7 +56,7 @@ then render a real screen and **capture** it. That capture is the **design-confi
 evidence — a real image the person approves *before* implementation, so the build
 matches the layout instead of discovering it. The book keeps the *why*; the
 operational recipe (the wireframe format, the token-bound mock, the capture engines)
-lives in the `add` skill's `design.md` and `udd-wireframe.md`.
+lives in the `add` skill's `design.md` and the `udd-wireframe.md` template (`tooling/templates/`).
 
 These three foundation competencies, together with the **TDD ⇄ ADD** engine of
 [Part II](./02-the-flow.md), are ADD's five. The first four feed context to the

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)
 
 ---
 
@@ -11,8 +11,8 @@ them *ship*. This chapter names the act every project eventually performs and th
 now, never formalized: bundling closed milestones into a versioned, user-facing release whose notes
 are evidence-backed, whose risk is disclosed, and whose behaviour is then watched.
 
-Releasing is the **fifth scope level** — after the task, the milestone, the foundation/setup level,
-and stage graduation. Like every scope level it runs the same shape: **gather → propose → the human
+Releasing is the **fifth scope level** — after setup, intake, the milestone loop, and stage graduation.
+Like every scope level it runs the same shape: **gather → propose → the human
 confirms → the engine records and enforces a floor.** And like graduation, it ends with an outward
 act the human owns. The operational recipe lives in the `release.md` skill guide; this chapter is the
 *why* behind it.
@@ -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.
@@ -78,7 +84,7 @@
 
 **Baseline approval** (formerly "the lock-down") — the single human gate ending autonomous setup: an explicit yes that freezes the foundation, first scope, and first contract together; runs as `add.py lock --by <name>`.
 
-**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level · release level (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
+**Scope level** (formerly "altitude") — the granularity a decision lives at, as one ordered ladder of five: **setup/foundation** · **intake** (request → versioned scope) · **the milestone loop** (the task is its inner unit) · **stage graduation** (changes rigor, not version; see **Stage graduation**) · **release** (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). One ⚠-assumption notation is shared across every scope level.
 
 **Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
 
@@ -128,9 +134,9 @@
 
 **Newest-first append-only** — every append-only foundation sequence prepends the newest record at the top; the rolled-up settled line anchors at the bottom (the oldest end), so compaction collapses upward.
 
-**Wireframe** — the Stage-A low-fidelity, *structural* map of one screen: its regions and the component **slots** inside them, derived from `prototypes/<name>.json` *before* any color, type, or spacing — it answers "what goes where", not "what it looks like". Beat 3 of the UDD **design-definition loop**; the low-fi half of the two-stage fidelity that ends in a confirmed capture. See the `add` skill's `udd-wireframe.md` (Stage A).
+**Wireframe** — the Stage-A low-fidelity, *structural* map of one screen: its regions and the component **slots** inside them, derived from `prototypes/<name>.json` *before* any color, type, or spacing — it answers "what goes where", not "what it looks like". Beat 3 of the UDD **design-definition loop**; the low-fi half of the two-stage fidelity that ends in a confirmed capture. See the `udd-wireframe.md` template (`tooling/templates/`, Stage A).
 
-**Design mock** — the Stage-B high-fidelity, **self-contained** HTML render of a screen: the `catalog.json` components as a reusable token-bound kit, bound to `tokens.json` and populated with mock data, openable offline and screenshot-able. The human-facing *visible* evidence the human confirms (the frozen `prototypes/<name>.json` tree is its machine-checkable twin). Beat 4's hi-fi artifact; the recipe lives in the `add` skill's `udd-wireframe.md` (Stage B).
+**Design mock** — the Stage-B high-fidelity, **self-contained** HTML render of a screen: the `catalog.json` components as a reusable token-bound kit, bound to `tokens.json` and populated with mock data, openable offline and screenshot-able. The human-facing *visible* evidence the human confirms (the frozen `prototypes/<name>.json` tree is its machine-checkable twin). Beat 4's hi-fi artifact; the recipe lives in the `udd-wireframe.md` template (`tooling/templates/`, Stage B).
 
 **Capture** — the real rendered image (PNG/SVG) of a design mock: the **design-confirm evidence** artifact. Captures live at `.add/design/captures/<name>.<ext>` (one per prototype) and are attached or mentioned in the feature's `TASK.md`; `@json-render/image` (Satori → PNG/SVG, no browser) is the named default capture engine, otherwise the self-contained mock is screenshot headless. The engine never renders — it only MEASURES presence: `add.py check` raises a never-red `missing_capture` WARN for a prototype with no capture.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.9.0",
+  "version": "1.11.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"
@@ -19,6 +19,9 @@
     "bin/",
     "skill/",
     "tooling/add.py",
+    "tooling/add_engine/",
+    "!tooling/add_engine/__pycache__",
+    "!**/*.pyc",
     "tooling/templates/",
     "docs/",
     "README.md",
@@ -46,7 +49,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

@@ -62,7 +62,13 @@ self-improving via the `soul-self-improve` path). Then branch on state:
 - **No active task** → first SIZE the request (Intake below), then `add.py new-task <slug> --title "..."`.
 
 **Quick ref** — `status` resume · `init` bootstrap · `advance` continue · `gate PASS` at verify.
-**Opt-in flags** (human picks, never auto): `new-task --fast` = fast lane (minimal template, freeze-gated) · `new-milestone --await-confirm` = confirm-gate the milestone's tasks.
+**Flag mode** — two human-owned settings (never auto-picked): **fast** (task) · **auto** (mode).
+- **fast** — `new-task --fast`: minimal template, freeze-gated; a milestone-free `--fast` task is a
+  blessed standalone low-ceremony lane. Jot ideas first with `add.py todo "<text>"` (then `todo` to
+  list · `todo --done <id>`).
+- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; lower the autonomy level with
+  `add.py autonomy set conservative|manual` for a human gate · `new-milestone --await-confirm`
+  confirm-gates a milestone's tasks.
 
 ## Intake — size a request before creating scope
 
@@ -130,6 +136,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)