@pilotspace/add 1.8.0 → 1.10.0

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}
@@ -152,6 +167,47 @@ Outcome:
 """
 
 
+# Fast-lane fallback: the minimal TASK.md variant (sections {0,1,3,4,5,6}; §2 + §7 dropped).
+# Mirrors templates/TASK.fast.md.tmpl's section set (circuit-breaker parity); a deleted
+# templates/ never hard-fails the fast lane. Keeps the trust floor: §3 freeze-flag + Status,
+# §6 GATE RECORD/Outcome, §0 Anchors, §4 red-before-build, §5 Scope.
+_FALLBACK_TASK_FAST = """# TASK: {title}
+
+slug: {slug} · created: {date} · stage: {stage}
+autonomy: auto
+phase: ground
+fast: true
+
+## 0 · GROUND
+Touches (files · symbols):
+Anchors the contract cites:
+
+## 1 · SPECIFY
+Feature:
+Must:
+Reject:
+Accept:
+Assumptions: ⚠ <most likely wrong> — why; if wrong: <cost>
+
+## 3 · CONTRACT
+Least-sure flag surfaced at freeze:
+Status: DRAFT
+
+## 4 · TESTS
+Plan:
+Tests live in: `./tests/` · MUST run red before Build.
+
+## 5 · BUILD
+Scope (may touch): `./src/`
+
+## 6 · VERIFY
+Build expectations (from §1 Accept + §3 CONTRACT):
+### GATE RECORD
+Outcome:
+Reviewed by:
+"""
+
+
 # --- low-level IO (designed for failure: atomic, no silent clobber) ----------
 
 def _now() -> str:
@@ -174,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.
 
@@ -237,13 +307,14 @@ def _templates_dir() -> Path:
 def _render_template(name: str, **subs: str) -> str:
     """Load templates/<name>.tmpl and substitute {{key}} tokens.
 
-    Falls back to a built-in minimal template only for TASK.md.
+    Falls back to a built-in minimal template for TASK.md and the fast-lane TASK.fast.md.
     """
     tmpl = _templates_dir() / f"{name}.tmpl"
+    _fallbacks = {"TASK.md": _FALLBACK_TASK, "TASK.fast.md": _FALLBACK_TASK_FAST}
     if tmpl.exists():
         text = tmpl.read_text(encoding="utf-8")
-    elif name == "TASK.md":
-        text = _FALLBACK_TASK.replace("{title}", "{{title}}").replace(
+    elif name in _fallbacks:
+        text = _fallbacks[name].replace("{title}", "{{title}}").replace(
             "{slug}", "{{slug}}").replace("{date}", "{{date}}").replace("{stage}", "{{stage}}")
     else:
         text = ""
@@ -543,6 +614,87 @@ def _setup_locked(state: dict) -> bool:
     return ("setup" not in state) or (state["setup"].get("locked") is True)
 
 
+def _milestone_confirmed(state: dict, mslug: str) -> bool:
+    """True when milestone `mslug` is confirmed — i.e. the new-task gate is OPEN.
+
+    Mirrors `_setup_locked` one level down. A milestone record with NO "confirmed" key is
+    GRANDFATHERED-confirmed: every milestone created WITHOUT `--await-confirm` (and every
+    pre-existing one) is never gated. Opt-in: `new-milestone --await-confirm` seeds confirmed:false,
+    so the gate is active in exactly one case: the record is present AND confirmed is False. An
+    unknown milestone is treated as confirmed here (existence is cmd_new_task's separate check)."""
+    m = (state.get("milestones") or {}).get(mslug)
+    if not isinstance(m, dict) or "confirmed" not in m:
+        return True
+    return m["confirmed"] is True
+
+
+def _section_unfilled(md_text: str, header: str) -> bool:
+    """True iff the `header` section is PRESENT but UNFILLED — empty (no real bullet) or
+    still a `<…>` template placeholder. ABSENT section -> False (grandfathered legacy);
+    a filled section (>=1 real bullet, no `<…>`) -> False. Pure predicate — the shared
+    placeholder test the fill gates use (contract-fill at confirm; build-expectations at build)."""
+    body, in_sec, present = [], False, False
+    for ln in md_text.splitlines():
+        if ln.startswith(header):
+            in_sec, present = True, True
+            continue
+        if in_sec:
+            if ln.startswith("#"):          # ANY next header (## or ###) ends our section
+                break
+            if ln.lstrip().startswith(">"):  # skip blockquote GUIDANCE — it is not content
+                continue
+            body.append(ln)
+    if not present:
+        return False                        # absent -> grandfather
+    text = "\n".join(body).strip()
+    if not text:
+        return True                         # present but empty
+    return bool(re.search(r"<[^>\n]+>", text))   # a <…> placeholder remains
+
+
+def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None:
+    """Write-back (gate-record-writeback): mirror the resolved gate verdict into the task's
+    §6 `### GATE RECORD`, so the file and state.json never silently diverge (Finding C). Runs
+    for EVERY task — the write is ADDITIVE and never refuses, so (unlike the two refusal gates)
+    it needs no `--await-confirm` opt-in to protect the census. GRANDFATHER is the safety: a
+    GATE RECORD line is rewritten ONLY while it still holds a `<…>` placeholder; a resolved
+    (hand-filled) line is byte-untouched. No GATE RECORD block / no placeholder line / an
+    unreadable file -> silent no-op, the file stays byte-identical. Called AFTER save_state —
+    state is the source of truth; the file only mirrors it, so a write fault never loses a verdict."""
+    f = root / "tasks" / slug / "TASK.md"
+    try:
+        text = f.read_text(encoding="utf-8")
+    except OSError:
+        return                                   # unreadable -> no-op (never blocks the gate)
+    if "### GATE RECORD" not in text:
+        return                                   # nothing to mirror into
+    actor = _actor_stamp(state)
+    today = date.today().isoformat()
+    # each rule matches ONLY a line still carrying a `<…>` placeholder -> grandfather a resolved line.
+    rules = [
+        (r"(?m)^(Outcome:[ \t]*)<[^>\n]*>.*$", f"Outcome: {outcome}"),
+        (r"(?m)^Reviewed by:[ \t]*.*<[^>\n]*>.*$",
+         f"Reviewed by: {actor['name']} · date: {today}"),
+    ]
+    if outcome == "RISK-ACCEPTED":
+        w = ((state.get("tasks") or {}).get(slug) or {}).get("waiver") or {}
+        rules.append((r"(?m)^If RISK-ACCEPTED ->.*<[^>\n]*>.*$",
+                      f"If RISK-ACCEPTED -> owner: {w.get('owner', '?')} · "
+                      f"ticket: {w.get('ticket', '?')} · expires: {w.get('expires', '?')}"))
+    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)
+
+
 def _die(msg: str, code: int = 1) -> None:
     print(f"add: error: {msg}", file=sys.stderr)
     raise SystemExit(code)
@@ -624,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:
@@ -725,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}")
@@ -741,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}")
 
 
@@ -763,6 +1029,12 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     milestone = getattr(args, "milestone", None) or _active_milestone(state)
     if milestone and milestone not in state.get("milestones", {}):
         _die("unknown_milestone")
+    # confirm-parent gate (OPT-IN): a task may not be detailed before its parent milestone is
+    # human-confirmed — but ONLY when the milestone opted in via `new-milestone --await-confirm`.
+    # validate-then-write — refuse BEFORE any scaffold/state mutation. A milestone with no
+    # `confirmed` key (non-flag + pre-existing) is grandfathered (mirrors the setup-lock).
+    if milestone and not _milestone_confirmed(state, milestone):
+        _die(f"milestone_unconfirmed: confirm it first — add.py milestone-confirm {milestone}")
     depends_on = _parse_deps(getattr(args, "depends_on", None))
 
     # SEED (--from-delta): resolve a prior task's FIRST open SPEC delta into THIS task.
@@ -796,8 +1068,13 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     # inherit the project's DECLARED autonomy default (task init-auto-default) — fail-SAFE:
     # absent -> auto, garbled -> conservative; the posture is project-scoped, not hardcoded.
     autonomy = _project_autonomy(root)
+    # fast lane (fast-new-task-flag): --fast scaffolds the MINIMAL template instead of the full one.
+    # The human opts in explicitly (the engine never guesses ceremony); the freeze floor is held by
+    # the freeze-before-build gate's fast arm (cmd_advance), so the lighter shape never drops the trust seam.
+    fast = bool(getattr(args, "fast", False))
     rendered = _render_template(
-        "TASK.md", title=title, slug=slug, date=date.today().isoformat(),
+        "TASK.fast.md" if fast else "TASK.md",
+        title=title, slug=slug, date=date.today().isoformat(),
         stage=state["stage"], autonomy=autonomy)
     if feature_override:                                     # pre-fill §1 from the seeded delta
         rendered = re.sub(r"(?m)^Feature:.*$",
@@ -822,6 +1099,8 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     }
     if from_delta:
         state["tasks"][slug]["from_delta"] = from_delta     # lineage: seeded from <prior>
+    if fast:
+        state["tasks"][slug]["fast"] = True                 # durable lane marker (absent == not-fast)
     _set_active_task(state, slug, milestone)
     save_state(root, state)
     print(f"created task '{slug}' -> {task_md}")
@@ -932,13 +1211,48 @@ 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
     # freezes — the unmarked predecessors are never retro-redded). REFUSE writes
     # nothing (fail-closed); below the build boundary the flag is never checked.
     if nxt == "build":
+        # the OPTED-IN crossing guards (fast-lane + flow-enforcement): a task whose PARENT
+        # milestone opted into --await-confirm is held to the trust floor at tests->build. A
+        # task under a plain / no milestone is never gated (every existing advance-to-build flow
+        # stays green). validate-then-write — every refusal runs BEFORE the tripwire/scope
+        # snapshots below, writing nothing; the task stays at `tests`.
+        _ms = state["tasks"][slug].get("milestone")
+        _optin = bool(_ms) and (state.get("milestones") or {}).get(_ms, {}).get("await_confirm") is True
         raw3 = _raw_phase_bodies(root, slug).get(3, "")
+        # freeze-before-build gate (fast-lane): "collapse-never-skip" made REAL — the freeze is
+        # engine-enforced for an opted-in milestone OR any --fast task (the fast arm, fast-new-task-flag:
+        # a fast task is held to the floor under ANY milestone, so the lighter lane never drops the
+        # trust seam). PRECEDES build-expectations: you freeze §3 before pre-declaring §6's outcomes.
+        _freeze_gated = _optin or state["tasks"][slug].get("fast") is True
+        if _freeze_gated and not _contract_frozen(raw3):
+            _die("contract_not_frozen: freeze §3 before crossing into build — approve "
+                 f"the contract in {slug}'s TASK.md (Status: FROZEN @ vN)")
+        # build-expectations gate (flow-enforcement): an opted-in task may not enter build until
+        # its §6 `### Build expectations` are pre-declared — so verify checks the build is RIGHT,
+        # not just green. Same opt-in switch as the contract-fill gate, one level out.
+        if _optin:
+            if _section_unfilled(_raw_phase_bodies(root, slug).get(6, ""), "### Build expectations"):
+                _die("build_expectations_unfilled: fill the §6 '### Build expectations' block "
+                     f"of {slug}'s TASK.md before crossing into build")
         if _contract_frozen(raw3):
             if not _flag_well_formed(raw3):
                 _die("unflagged_freeze: a frozen §3 must surface a well-formed "
@@ -973,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)
@@ -1011,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
@@ -1109,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.
@@ -1126,7 +1498,11 @@ def cmd_gate(args: argparse.Namespace) -> None:
     state["tasks"][slug]["gate_actor"] = _actor_stamp(state)   # WHO recorded the verdict (every outcome)
     state["tasks"][slug]["updated"] = _now()
     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))
@@ -1423,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()
@@ -1531,7 +1939,10 @@ def cmd_status(args: argparse.Namespace) -> None:
     if _rel:
         print(f"  → {RELEASABLE_CUE.format(n=len(_rel))}")
 
-    print(f"active  : {active or '(none)'}")
+    # fast-lane marker (fast-new-task-flag): tag an ACTIVE fast task so the lane is visible at a
+    # glance. Presentation-only, existence-gated — a plain/absent active task is byte-unchanged.
+    _fast_mark = " · fast" if active and tasks.get(active, {}).get("fast") is True else ""
+    print(f"active  : {active or '(none)'}{_fast_mark}")
     # parallel streams (parallel-status-view): when >=2 milestones are active, render each as its
     # own stream (active task + phase) so a user working N fronts reads them all at once. ADDITIVE —
     # the N<=1 output above is byte-identical (the standing additive-cue convention); presentation
@@ -1614,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.")
@@ -1665,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"),
@@ -1685,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).
@@ -1701,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")
 
@@ -2137,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)
@@ -2185,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"))
@@ -2298,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.
@@ -2577,17 +3085,64 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     _atomic_write(mfile, _render_template(
         "MILESTONE.md", title=title, goal=args.goal or "<goal>",
         stage=args.stage, date=date.today().isoformat()))
-    state["milestones"][slug] = {
+    # confirm-parent gate (OPT-IN, mirrors `init --await-lock`): `--await-confirm` seeds the
+    # milestone UNCONFIRMED so new-task is held until `add.py milestone-confirm`. WITHOUT the flag
+    # NO `confirmed` key is written → grandfathered-confirmed → no gate (so the existing engine
+    # tests stay byte-green). The guided skill flow passes the flag at the human-review point.
+    await_confirm = bool(getattr(args, "await_confirm", False))
+    record = {
         "title": title, "goal": args.goal or "", "stage": args.stage,
         "status": "active", "created": _now(), "updated": _now(),
     }
+    if await_confirm:
+        # `await_confirm` is the STABLE opt-in marker (set ONLY here, at creation). `confirmed`
+        # alone is NOT a reliable opt-in signal: milestone-confirm stamps confirmed:true on a plain
+        # milestone too, so a later build-entry gate must key on `await_confirm`, not `confirmed`.
+        record.update(confirmed=False, confirmed_at=None, confirmed_by=None, await_confirm=True)
+    state["milestones"][slug] = record
     _set_active_milestone(state, slug)
     save_state(root, state)
     print(f"created milestone '{slug}' -> {mfile}")
-    print("active milestone set.")
+    print("active milestone set." + ("" if not await_confirm else
+          "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 
+def cmd_milestone_confirm(args: argparse.Namespace) -> None:
+    """The human gate that opens new-task for a milestone (confirm-parent). Mirrors `cmd_lock`
+    one level down: the human reviews the filled MILESTONE.md, then RECORDS confirmation here.
+    The engine never self-confirms. Validate-then-write; re-confirm is an idempotent note."""
+    root = _require_root()
+    state = load_state(root)
+    slug = args.slug
+    if slug not in state.get("milestones", {}):
+        _die("unknown_milestone")
+    m = state["milestones"][slug]
+    if m.get("confirmed") is True:
+        print(f"milestone '{slug}' already confirmed (by {m.get('confirmed_by', '?')}).")
+        return
+    # contract-fill gate (flow-enforcement, OPTED-IN only): a milestone that opted into
+    # --await-confirm (carries a `confirmed` key) may not be confirmed until its cross-task
+    # `## Shared / risky contracts` section is filled — so "confirmed" MEANS the contracts
+    # were present at confirm time. A grandfathered no-key milestone keeps the plain stamp
+    # (gate skipped — keeps the census + existing flows green). Validate-then-write.
+    if "confirmed" in m:
+        mfile = root / "milestones" / slug / MILESTONE_FILE
+        md = mfile.read_text(encoding="utf-8") if mfile.exists() else ""
+        if _section_unfilled(md, "## Shared / risky contracts"):
+            _die("milestone_contracts_unfilled: fill the '## Shared / risky contracts' "
+                 f"section of {slug}'s MILESTONE.md before confirming")
+    who = getattr(args, "by", None) or getpass.getuser()
+    m["confirmed"] = True
+    m["confirmed_at"] = _now()
+    m["confirmed_by"] = who
+    m["actor"] = _actor_stamp(state)   # structured actor alongside the free-text confirmed_by
+    m["updated"] = _now()
+    save_state(root, state)
+    print(f"confirmed milestone '{slug}' (by {who}) — new-task is now open for it.")
+    print(_next_footer(root, state))
+
+
 def cmd_ready(args: argparse.Namespace) -> None:
     if getattr(args, "json", False):
         _, state = _load_state_for_json()
@@ -3499,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
@@ -3508,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] = []
@@ -3538,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
 
 
@@ -5645,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",
@@ -5696,6 +6462,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="with --from-delta: target the UNIQUE open SPEC delta whose text "
                          "contains SUBSTR (case-insensitive) instead of the first")
     pn.add_argument("--force", action="store_true", help="overwrite TASK.md if present")
+    pn.add_argument("--fast", action="store_true",
+                    help="opt into the fast lane: scaffold the minimal TASK.fast.md template + "
+                         "hold the task to the freeze floor under any milestone")
     pn.set_defaults(func=cmd_new_task)
 
     pdd = sub.add_parser("drop-delta",
@@ -5712,8 +6481,18 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--goal", default=None, help="one-sentence outcome")
     pm.add_argument("--stage", default="mvp", choices=STAGES)
     pm.add_argument("--force", action="store_true", help="overwrite MILESTONE.md if present")
+    pm.add_argument("--await-confirm", action="store_true",
+                    help="opt into the confirm-parent gate: seed the milestone unconfirmed so "
+                         "new-task is held until `milestone-confirm` (mirrors `init --await-lock`); "
+                         "the guided skill flow passes this at the human-review point")
     pm.set_defaults(func=cmd_new_milestone)
 
+    pmc = sub.add_parser("milestone-confirm",
+                         help="confirm a milestone (the human gate that opens new-task for it)")
+    pmc.add_argument("slug")
+    pmc.add_argument("--by", default=None, help="free-text confirmer name (defaults to the OS user)")
+    pmc.set_defaults(func=cmd_milestone_confirm)
+
     pr = sub.add_parser("ready", help="list tasks whose dependencies are satisfied")
     pr.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pr.set_defaults(func=cmd_ready)
@@ -5818,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)
@@ -5838,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")