@pilotspace/add 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,115 @@ 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
+prompt at optimized token cost, *not* token-golf. Bundles four closed milestones:
+`skill-effectiveness` (M1), `flow-simplification` (M3), `flow-enforcement` (M4), and
+the `fast-lane` sub-milestone. The skill tree routes identically but loads lighter;
+the method's three fill-seams are now engine-enforced rather than convention; and a
+new opt-in **fast lane** collapses ceremony for small tasks without lowering the trust
+floor. Every new gate is opt-in or grandfathered — existing flows are byte-unchanged.
+
+### Added
+- **Fast lane (`fast-lane`)** — `add.py new-task <slug> --fast` runs a small task
+  through a minimal `TASK.fast.md` (sections {0,1,3,4,5,6}) that still freezes a
+  contract, proves a red→green, and reads back cold in a later session. The lane is
+  *collapse-never-skip*: a `--fast` task is freeze-gated under ANY milestone (the floor
+  fires on `_optin OR fast`). Human-triggered only — the engine never auto-classifies a
+  task as "small". New `phases/fast-lane.md` guide + a SKILL.md quick-ref document it.
+- **Freeze-before-build gate (`fast-lane`)** — crossing tests→build now refuses
+  `contract_not_frozen` when §3 is still DRAFT and the task is opted-in or fast, closing
+  the gap where a task could reach `gate=PASS` without an approved, frozen contract.
+- **Contract-fill + build-expectations gates (opt-in, `flow-enforcement`)** — under
+  `new-milestone --await-confirm`, the engine HOLDS a task whose §3 CONTRACT or §6
+  Build-expectations block is still a placeholder, so the method's fill-seams are
+  enforced rather than trusted. `await_confirm` is the master switch; without it no key
+  is written → grandfathered → byte-unchanged.
+- **Gate-record write-back (`flow-enforcement`)** — recording a verify gate now stamps
+  the verdict into the §6 GATE RECORD of the TASK.md for ALL tasks (grandfathered
+  backfill), so the file itself carries the outcome the Seam audit reads.
+- **Confirm-parent gate (opt-in, `flow-simplification`)** — `new-milestone <slug>
+  --await-confirm` seeds the milestone *unconfirmed*, so `new-task` is HELD (reject
+  `milestone_unconfirmed`) until you show the filled `MILESTONE.md`, get the human's go,
+  and run the new `add.py milestone-confirm <slug>`. Closes the gap where the AI would
+  detail a task's §0–§5 before the human had agreed the parent milestone. Mirrors
+  `init --await-lock` one level down.
+
+### Changed
+- **Skill tree 25% lighter (`skill-effectiveness`)** — the on-demand skill guides were
+  compacted tree-wide (164,333 → ~123,000 bytes) with zero routing, gate, reject-code,
+  threshold, or rule lost; an independent adversarial review confirmed every operative
+  element preserved (it flagged 6 dropped nuances → all restored). Same flow an agent
+  reads, fewer tokens to load.
+- **One home for the worker-spawn model tiers (`spawn-fold`)** — the tier→model mapping
+  (mid→sonnet / top→opus) now lives only in `streams.md`; `advisor.md` points at it
+  instead of copying. Advisor keeps its own advisory template.
+
 ## [1.8.0] — 2026-06-23
 
 Team collaboration: ADD becomes git-native and multi-user, with N

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,12 +16,20 @@
 
 **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.
 
 **Foundation version** — a monotonic integer marker in `PROJECT.md` that advances by one each time confirmed lessons learned are consolidated into the foundation. It makes the living documentation's evolution auditable: a rising version with fewer new deltas per milestone is the signal that a competency is converging rather than drifting. Bumped only by the retrospective consolidation (see the `add` skill's `fold.md`).
 
+**Fast lane** — the collapsed, opt-in task path for small, low-risk work. `add.py new-task <slug> --fast` scaffolds a minimal `TASK.fast.md` (sections {0,1,3,4,5,6}; scenarios and observe dropped) and the specification bundle is approved in one freeze. It runs the SAME flow with fewer sections — it never drops the trust floor: a `--fast` task is held to a frozen contract, a red test before build, and a recorded verify gate under any milestone. Collapse, never skip; the human opts in (the engine never auto-classifies a task as small). See the `add` skill's `phases/fast-lane.md`.
+
 **Gate** — a checkpoint with an explicit pass/fail exit. Its outcome is `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`.
 
 **Ground (phase-0 preamble)** — the per-task phase *before* Specify in which the AI gathers the real current codebase the task touches — files, symbols, signatures, patterns, conventions — into a lean **grounding map**, surfacing the **anchors** the frozen contract will cite. It is AI-owned and adds no approval (the one approval stays at the contract freeze); it precedes the seven steps as step 0 so the contract, tests, and build are grounded in the code as it actually is, not in assumption. Lives in the `add` skill's `phases/0-ground.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.8.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"
   }