@pilotspace/add 1.13.0 → 1.15.0

package/tooling/add.py

@@ -36,8 +36,11 @@ from add_engine.constants import (  # the _-prefixed names (import * skips them)
     _GITIGNORE_BODY, _GUIDE_BEGIN, _GUIDE_END,
     _RULE_REF_LINE, _FALLBACK_TASK, _FALLBACK_TASK_FAST,
     _DEFAULT_WIDTH,
-    _DELTA_RE, _EVIDENCE_RE, _SPEC_DELTA_RE,   # shared delta regexes (taskdoc + deltas-web lint)
+    _DELTA_RE, _PERSONA_TAG_RE, _EVIDENCE_RE, _SPEC_DELTA_RE,   # shared delta regexes (taskdoc + deltas-web lint)
+    _SEED_POINTER_RE,   # shared (delta-task-backlink) — reads the `[→ slug]` seed stamp back
     _AUTONOMY_LEVELS,   # shared (autonomy resolvers + _AUTONOMY_ORDER/cmd_autonomy)
+    _STREAMS_POSTURES,  # shared (streams resolvers + cmd_streams) — run-mode streams half
+    _SENSITIVITY_VALUES,  # shared (_task_sensitivity + cmd_freeze/status/audit) — risk-class taxonomy
 )
 
 # --- terminal-render primitives (moved to add_engine/render.py) -------------
@@ -78,8 +81,12 @@ from add_engine.taskdoc import (
 # --- autonomy-level resolvers (moved to add_engine/autonomy.py) -------------
 from add_engine.autonomy import (
     _autonomy_level, _effective_autonomy, _project_autonomy, _project_autonomy_token,
+    _project_streams,   # run-mode streams half (persist-run-mode) — read live from PROJECT.md
 )
 
+# --- keyword/substring corpus search (NEW — add_engine/search.py) -----------
+from add_engine.search import _search_corpus
+
 
 def _phase_index(name: str) -> int:
     """Ordinal of a phase in PHASES; used to enforce forward-skip rules."""
@@ -150,10 +157,151 @@ def _render_template(name: str, **subs: str) -> str:
         text = text.replace("{{" + key + "}}", val)
     return text
 
+
+# --- TASK.md milestone backlink (task-milestone-backlink) --------------------
+# The task↔milestone link is mirrored into the TASK.md header so the file names its
+# own parent. The engine WRITES it (new-task) and MAINTAINS it (set-milestone); a
+# milestone-free task reads the "(none)" sentinel, never blank. Keeping it engine-owned
+# is what makes it drift-proof — `check` flags a hand-edited line that disagrees.
+_MILESTONE_BACKLINK = "(none)"
+_MILESTONE_LINE_RE = re.compile(r"(?m)^milestone:[^\n]*$")
+_SLUG_LINE_RE = re.compile(r"(?m)^slug:[^\n]*$")
+
+
+def _milestone_backlink_value(milestone) -> str:
+    """The header value for a milestone slug (or the sentinel when milestone-free)."""
+    return milestone if milestone else _MILESTONE_BACKLINK
+
+
+def _set_milestone_line(text: str, value: str) -> str:
+    """Rewrite (or insert) the TASK.md header `milestone:` backlink — idempotent.
+
+    A grandfathered file lacking the line gets it inserted right after `slug:`; with no
+    slug line either, the text is returned unchanged (degrade-safe — never corrupts a doc).
+    """
+    line = f"milestone: {value}"
+    if _MILESTONE_LINE_RE.search(text):
+        return _MILESTONE_LINE_RE.sub(lambda _m: line, text, count=1)
+    m = _SLUG_LINE_RE.search(text)
+    if not m:
+        return text
+    return text[:m.end()] + "\n" + line + text[m.end():]
+
+
+def _read_milestone_line(text: str):
+    """The current `milestone:` backlink value in a TASK.md header, or None if absent."""
+    m = _MILESTONE_LINE_RE.search(text)
+    return m.group(0)[len("milestone:"):].strip() if m else None
+
+
+# --- MILESTONE.md release backlink (milestone-release-backlink) --------------
+# The milestone↔release link is mirrored into the MILESTONE.md header: the template seeds
+# `release: pending`; cmd_release STAMPS it to the cut version (the stamp rides the same
+# all-or-nothing batch as CHANGELOG + RELEASES). The mirror of _set_milestone_line, one
+# scope level up — keying on `^release:`, inserting after the `stage:` line if absent.
+_RELEASE_LINE_RE = re.compile(r"(?m)^release:[^\n]*$")
+_STAGE_LINE_RE = re.compile(r"(?m)^stage:[^\n]*$")
+
+
+def _set_release_line(text: str, value: str) -> str:
+    """Rewrite (or insert) the MILESTONE.md header `release:` backlink — idempotent.
+
+    A grandfathered file lacking the line gets it inserted right after the `stage:` line;
+    with no stage line either, the text is returned unchanged (degrade-safe)."""
+    line = f"release: {value}"
+    if _RELEASE_LINE_RE.search(text):
+        return _RELEASE_LINE_RE.sub(lambda _m: line, text, count=1)
+    m = _STAGE_LINE_RE.search(text)
+    if not m:
+        return text
+    return text[:m.end()] + "\n" + line + text[m.end():]
+
+
+# --- §0 GROUND drift anchor (ground-anchor-sha) -----------------------------
+# §0 line numbers rot during BUILD while symbols survive (PR40 audit). The engine SEEDS a
+# `Ground SHA:` field (the AI fills it via git — NO-EXEC: add.py never shells out) and `check`
+# WARNs when a §0 cites bare line numbers without one, so drift is detectable not silent.
+_GROUND_SHA_RE = re.compile(r"(?m)^Ground SHA:[ \t]*(.*?)[ \t]*$")
+_LINE_REF_RE = re.compile(r"l\.\d+")
+
+
+def _ground_section(text: str) -> str:
+    """The §0 GROUND block of a TASK.md — from the `## 0` heading to the next `## ` heading."""
+    m = re.search(r"(?m)^## 0\b", text)
+    if not m:
+        return ""
+    rest = text[m.end():]
+    nxt = re.search(r"(?m)^## ", rest)
+    return rest[:nxt.start()] if nxt else rest
+
+
+def _read_ground_sha(text: str):
+    """The §0 `Ground SHA:` value, or None if absent or still a `<…>` placeholder."""
+    m = _GROUND_SHA_RE.search(_ground_section(text))
+    if not m:
+        return None
+    val = m.group(1).strip()
+    return None if (not val or val.startswith("<")) else val
+
+
+def _ground_cites_line_ref(text: str) -> bool:
+    """True iff the §0 GROUND block cites a bare line number (the `l.NNN` idiom)."""
+    return bool(_LINE_REF_RE.search(_ground_section(text)))
+
+
+def _seeded_delta_pointers(text: str) -> list[str]:
+    """The task slugs `[SPEC · seeded] … [→ <slug>]` lines point at (delta-task-backlink). PURE.
+
+    Walks the delta→task lineage backward: each seeded SPEC delta carries the slug it was seeded
+    into (the `[→ <slug>]` stamp `_resolve_spec_delta` appends). `check` flags a pointer that no
+    longer resolves to a live or archived task. Order-preserving; open/dropped deltas are ignored."""
+    out: list[str] = []
+    for ln in text.splitlines():
+        m = _SPEC_DELTA_RE.match(ln.rstrip("\n"))
+        if not m or m.group(2) != "seeded":
+            continue
+        p = _SEED_POINTER_RE.search(m.group(3))
+        if p:
+            out.append(p.group(1))
+    return out
+
+
+# --- tidy a closed TASK.md (strip-scaffold-at-done) --------------------------
+# A live TASK.md carries `<!-- … -->` instruction comments that guide the active phase; once the
+# task is `done` they are dead weight (PR40 audit). cmd_gate strips them on a COMPLETING gate.
+# Content-safe: fenced code blocks (```…```, incl. the frozen §3) pass through BYTE-EXACT — only
+# comments OUTSIDE a fence are removed; idempotent.
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_TRAILING_WS_RE = re.compile(r"(?m)[ \t]+$")
+_BLANK_RUN_RE = re.compile(r"\n{3,}")
+
+
+def _strip_live_scaffold(text: str) -> str:
+    """Remove `<!-- … -->` instruction comments from a TASK.md — fences untouched, idempotent.
+
+    Splits on fenced code blocks so a comment inside a ``` fence (e.g. the frozen §3) is never
+    touched; in the non-fence segments it drops comment spans, trims the trailing whitespace a
+    removal leaves on a line, and collapses 3+ consecutive newlines to one blank line."""
+    segs = re.split(r"(```.*?```)", text, flags=re.DOTALL)
+    for i in range(0, len(segs), 2):                     # even indices = OUTSIDE any fence
+        s = _HTML_COMMENT_RE.sub("", segs[i])
+        s = _TRAILING_WS_RE.sub("", s)
+        segs[i] = _BLANK_RUN_RE.sub("\n\n", s)
+    return "".join(segs)
+
+
+def _contract_fingerprint(raw3: str) -> str:
+    """md5 of the §3 CONTRACT CONTENT — comment-normalized + outer-whitespace-canonical (the
+    instruction comment is scaffolding, not contract). Used on BOTH tamper-guard sides
+    (_tripwire_snapshot + _tripwire_divergence) so the at-done strip — which removes the §3
+    comment and shifts the section's boundary whitespace — never reads as `contract_tampered`,
+    while a real fenced-shape edit still does."""
+    return _md5_text(_strip_live_scaffold(raw3).strip())
+
 # --- state/markdown predicates (moved to add_engine/predicates.py) -----------
 from add_engine.predicates import (
     _phase_owner, _setup_locked, _milestone_confirmed, _section_unfilled,
-    _task_done,
+    _task_done, _persona_missing, _persona_slug_valid, _rule_coverage_gaps,
 )
 
 # --- git-native identity/actor seam (moved to add_engine/identity.py) --------
@@ -228,11 +376,18 @@ def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None
     new = text
     for pat, repl in rules:
         new = re.sub(pat, repl, new, count=1)
-    # component-aware-add (per-component-verify): record WHICH green-bar a bound task gated
-    # against, right after the Outcome line. Unbound / no green_bar -> no line (byte-identical).
+    # component-aware-add (per-component-verify) + component-registry-fill: record WHICH green-bar
+    # the bound task gated against AND the component's verify COMMAND, right after the Outcome line.
+    # Unbound / neither declared -> no line (byte-identical). green-bar-only output is unchanged.
     _bar = _task_green_bar(root, slug)
-    if _bar:
-        _line = f"component: {_task_component(root, slug)} · expected green-bar: {_bar}"
+    _vfy = _task_verify(root, slug)
+    if _bar or _vfy:
+        _parts = [f"component: {_task_component(root, slug)}"]
+        if _bar:
+            _parts.append(f"expected green-bar: {_bar}")
+        if _vfy:
+            _parts.append(f"verify: {_vfy}")
+        _line = " · ".join(_parts)        # deterministic per task -> idempotent on re-stamp
         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)
@@ -383,6 +538,19 @@ def cmd_init(args: argparse.Namespace) -> None:
             continue
         _atomic_write(dest, rendered)
 
+    # --run-mode: apply the paired autonomy + streams posture into PROJECT.md.
+    # ONLY when the flag is explicitly set — absent flag leaves PROJECT.md byte-identical.
+    run_mode = getattr(args, "run_mode", None)
+    if run_mode is not None:
+        _level = run_mode                                           # "auto" | "conservative"
+        _posture = "parallel" if run_mode == "auto" else "sequential"
+        proj_md = root / "PROJECT.md"
+        if proj_md.exists():
+            _text = proj_md.read_text(encoding="utf-8")
+            _text = _autonomy_decl_line(_text, _level)
+            _text = _streams_decl_line(_text, _posture)
+            _atomic_write(proj_md, _text)
+
     state = {
         "project": proj_name,
         "stage": args.stage,
@@ -489,10 +657,18 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     rendered = _render_template(
         "TASK.fast.md" if fast else "TASK.md",
         title=title, slug=slug, date=date.today().isoformat(),
-        stage=state["stage"], autonomy=autonomy)
+        stage=state["stage"], autonomy=autonomy,
+        milestone=_milestone_backlink_value(milestone))
     if feature_override:                                     # pre-fill §1 from the seeded delta
         rendered = re.sub(r"(?m)^Feature:.*$",
                           lambda _m: f"Feature: {feature_override}", rendered, count=1)
+    if from_delta:                                           # delta-task-backlink: §0 reverse link
+        # pre-fill the §0 Related-intent PLACEHOLDER only (the `<…>` line a fresh full template
+        # carries) — mirrors the §1 Feature pre-fill, gated by from_delta, count=1. The fast
+        # template has no §0 Related-intent line, so the sub is a silent no-op there.
+        _bl = f"Related intent: seeded from {prior} spec-delta — \"{delta_text}\" [← {prior}]"
+        rendered = re.sub(r"(?m)^Related intent:\s*<.*>\s*$",
+                          lambda _m: _bl, rendered, count=1)
     seed_writes: list[tuple[Path, str]] = [(task_md, rendered)]
     if flipped_prior is not None:                           # consume the source delta -> seeded
         seed_writes.append((prior_md, flipped_prior))
@@ -690,6 +866,15 @@ def cmd_freeze(args: argparse.Namespace) -> None:
     if not _flag_well_formed(raw3):
         _die(f"unflagged_freeze: {slug}'s §3 must surface a well-formed lowest-confidence flag "
              f"('Least-sure flag surfaced at freeze:' + a [part] tag) before it freezes")
+    # the human declares the risk-CLASS at freeze (risk-sensitivity-taxonomy): a present-but-
+    # unknown sensitivity token is refused here (validate-then-write — nothing is written);
+    # an absent token is grandfathered (allowed), a valid member proceeds. The engine never
+    # classifies — it only validates the human's declaration.
+    _valid_sens = _project_sensitivity_values(root)        # base ∪ project GLOSSARY classes (sensitivity-glossary)
+    if _task_sensitivity(_task_header(root, slug), valid=_valid_sens) == "?":
+        _die(f"sensitivity_invalid: {slug} declares an unknown sensitivity — use one of "
+             f"{', '.join(_valid_sens)} (or add the class to GLOSSARY.md's '## Sensitivity classes', "
+             "or omit the line)")
     # --- write ---
     ver = _next_freeze_version(state, slug)
     who = args.by or identity._actor_stamp(state)["name"]
@@ -835,6 +1020,10 @@ def cmd_phase(args: argparse.Namespace) -> None:
     # loop sets phase=build directly (never via cmd_phase) and so stays exempt.
     if args.phase == "build":
         _build_entry(root, state, slug, skip_freeze=getattr(args, "skip_freeze", False))
+    # cross-component-recency: the `phase contract` override runs the SAME consumer HOLD `advance`
+    # runs (existence + recency), so it is not a backdoor around producer_contract_unfrozen/_stale.
+    if args.phase == "contract":
+        _consumer_contract_hold(root, state, slug)
     state["tasks"][slug]["phase"] = args.phase
     state["tasks"][slug]["updated"] = _now()
     save_state(root, state)                    # F12: durable state FIRST (source of truth) — may _die
@@ -863,12 +1052,10 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # 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")
+        # existence + RECENCY (cross-component-recency): a missing snapshot HARD-STOPs
+        # producer_contract_unfrozen; a present-but-stale leftover (live producer drifted/unfroze)
+        # HARD-STOPs producer_contract_stale. Shared with cmd_phase so the override is no backdoor.
+        _consumer_contract_hold(root, state, slug)
     # 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
@@ -947,6 +1134,71 @@ def cmd_advance(args: argparse.Namespace) -> None:
 # not be able to fool the guard either way).
 _RISK_HIGH_RE = re.compile(r"(?:^|·)[ \t]*risk:[ \t]*high\b", re.MULTILINE)
 
+# sensitivity taxonomy (risk-sensitivity-taxonomy): the risk-CLASS the human declares in the
+# TASK header at freeze — same anchored declaration grammar as risk:/autonomy: (line-start or
+# `·`, value stops at whitespace/`<`/`#`/`|`), so a title/prose substring is never a declaration.
+_SENSITIVITY_RE = re.compile(r"(?:^|·)[ \t]*sensitivity:[ \t]*([^\s<#|]+)", re.MULTILINE)
+
+def _task_sensitivity(hdr: str, valid=None):
+    """The declared sensitivity from a TASK.md header region (HTML comments already stripped by
+    _task_header). A member of `valid`, None when no `sensitivity:` line is present, or "?" when a
+    REAL token outside `valid` was written. `valid` defaults to _SENSITIVITY_VALUES (the universal
+    base — back-compat); callers that honor a project's GLOSSARY domain classes pass
+    valid=_project_sensitivity_values(root) (sensitivity-glossary). PURE — the engine validates a
+    human-declared token against the project's vocabulary, it never infers it (mirrors _autonomy_level)."""
+    if valid is None:
+        valid = _SENSITIVITY_VALUES
+    m = _SENSITIVITY_RE.search(hdr)
+    if not m:
+        return None
+    tok = m.group(1).strip().lower()
+    return tok if tok in valid else "?"
+
+
+# sensitivity-glossary: a project EXTENDS the universal base with domain risk-classes declared in
+# GLOSSARY.md's "## Sensitivity classes" section (the AI keeps it current per the skill guide). The
+# base four stay method-universal (advisor-gate-relax keys off `mechanical`) — a project never
+# REMOVES them. Read live like _project_autonomy/_project_streams (no state.json field). The first
+# GLOSSARY reader in the engine; degrade-safe by construction (design-for-failure).
+_SENS_CLASSES_HEADING_RE = re.compile(r"(?im)^##[ \t]+sensitivity[ \t]+classes\b.*$")
+# a domain line is "- <token>: …" or "- <token> — …"; the token must START with a letter, so a
+# placeholder ("- <token>: …") begins with "<" and never matches, and the ": "/"—" separator keeps
+# a prose bullet from being read as a class. HTML comments are stripped FIRST (mirrors _project_
+# autonomy/_project_streams) so a commented-out template example is never a declaration.
+_SENS_CLASS_LINE_RE = re.compile(r"(?m)^[ \t]*-[ \t]+([A-Za-z][\w-]*)[ \t]*(?::|—)")
+
+def _project_sensitivity_domain(root: Path) -> tuple:
+    """Domain sensitivity tokens declared in GLOSSARY.md's "## Sensitivity classes" section,
+    lowercased and deduped in document order. FAIL-SAFE: no GLOSSARY.md / no section / unreadable
+    -> () (the caller always unions the base in, so the vocabulary is never empty)."""
+    try:
+        text = (root / "GLOSSARY.md").read_text(encoding="utf-8")
+    except OSError:
+        return ()
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.S)    # a commented example is never a declaration
+    m = _SENS_CLASSES_HEADING_RE.search(text)
+    if not m:
+        return ()
+    body = text[m.end():]
+    nxt = re.search(r"(?m)^##[ \t]", body)        # stop at the next section heading
+    if nxt:
+        body = body[:nxt.start()]
+    seen, out = set(), []
+    for tok in (t.strip().lower() for t in _SENS_CLASS_LINE_RE.findall(body)):
+        if tok and tok not in seen:
+            seen.add(tok)
+            out.append(tok)
+    return tuple(out)
+
+def _project_sensitivity_values(root: Path) -> tuple:
+    """The full sensitivity vocabulary for a project: the universal base _SENSITIVITY_VALUES
+    (always present, listed first) ∪ the project's GLOSSARY.md domain classes. Base-first, deduped."""
+    out = list(_SENSITIVITY_VALUES)
+    for tok in _project_sensitivity_domain(root):
+        if tok not in out:
+            out.append(tok)
+    return tuple(out)
+
 # the explicit 3-mode autonomy dial (task explicit-autonomy-dial): an ordered ladder
 # manual < conservative < auto, declared as a per-task `autonomy:` header token.
 # anchored to a DECLARATION position — line-start `autonomy:` OR the inline slug-line form
@@ -969,6 +1221,66 @@ def _autonomy_lowered(hdr: str) -> bool:
     return _autonomy_level(hdr) in ("manual", "conservative")
 
 
+# advisor-gate-relax helpers: read the "### Advisor 3-lens verdict" SUB-SECTION
+# of body6, not the whole §6, so the refute-read's Verdict/Residue lines are
+# never mistaken for the advisor's fields.  Fail-safe: both return False when the
+# advisor block is absent → the guard fires (conservative by design).
+
+def _advisor_slice(body6: str) -> str:
+    """Return the '### Advisor 3-lens verdict' sub-section text from §6 body.
+    Returns '' when the block is absent (fail-safe)."""
+    m = re.search(r"(?m)^### Advisor 3-lens verdict\b", body6)
+    if not m:
+        return ""
+    nxt = re.search(r"(?m)^### ", body6[m.end():])
+    end = m.end() + nxt.start() if nxt else len(body6)
+    return body6[m.start():end]
+
+
+def _advisor_verdict_is_pass(body6: str) -> bool:
+    """True iff the Advisor 3-lens verdict sub-section declares Verdict: PASS…
+    Scoped to the advisor block only — the §6 Refute-read Verdict line is excluded.
+    Fail-safe: False when the advisor block is absent (guard fires)."""
+    slc = _advisor_slice(body6)
+    m = re.search(r"(?m)^Verdict:[ \t]*(\S+)", slc)
+    return bool(m) and m.group(1).upper().startswith("PASS")
+
+
+def _advisor_no_residue(body6: str) -> bool:
+    """True iff the Advisor 3-lens verdict sub-section declares Residue: none.
+    Fail-safe: False when the advisor block is absent (guard fires)."""
+    slc = _advisor_slice(body6)
+    m = re.search(r"(?m)^Residue:[ \t]*(\S+)", slc)
+    return bool(m) and m.group(1).strip().lower() == "none"
+
+
+# step-spawn-hint (advisor-gated-autonomy): the engine's pinned terse copy of each phase
+# guide's Advisor hook — one spawn idiom per phase. contract/done are ABSENT (no batch to
+# fan out: a freeze is one human decision; done is closed). Advisory ONLY — the engine never
+# spawns; the line just NAMES the agent shape a parallel run would use at this step.
+_SPAWN_HINTS = {
+    "ground": "broad sweep",
+    "specify": "domain researcher",
+    "scenarios": "wide scenario sweep",
+    "tests": "red-suite test-author",
+    "build": "independent well-scoped batch",
+    "verify": "earned-green refute-read",
+    "observe": "lessons-mining reviewer",
+}
+
+
+def _spawn_hint_line(task: dict, autonomy: str) -> str | None:
+    """PURE: the one-line per-step spawn hint for the ACTIVE task, or None. Suppressed when
+    the autonomy level is `manual` (the human drives every step) or the phase has no idiom
+    (contract/done). The tier reflects declared risk: a `risk: high` task earns `top`
+    (your strongest agent), everything else `mid`. Never spawns, never mutates state."""
+    phase = task.get("phase")
+    if autonomy == "manual" or phase not in _SPAWN_HINTS:
+        return None
+    tier = "top" if task.get("risk") == "high" else "mid"
+    return f"spawn hint: {phase} → {_SPAWN_HINTS[phase]} (tier: {tier})"
+
+
 def _driver_stop(root: Path, state: dict, slug: str, phase: str) -> bool:
     """True iff a HUMAN owns the next step for `phase` under the effective autonomy — the
     SINGLE source the footer marker and the guide TEXT marker both render (task
@@ -1014,8 +1326,16 @@ def cmd_gate(args: argparse.Namespace) -> None:
         # the mechanized high-risk guard: an unguarded high-risk header refuses
         # COMPLETION (PASS / RISK-ACCEPTED) until the dial is lowered and a human
         # owns the gate. HARD-STOP is never blocked — stopping is always allowed.
+        # advisor-gate-relax: a mechanical task whose Advisor 3-lens verdict shows
+        # PASS + Residue: none is the one exception — it may auto-complete even
+        # without a lowered dial. Only sensitivity:"mechanical" qualifies; security/
+        # data/architecture never relax; an absent advisor block is fail-safe False.
         hdr = _task_header(root, slug)
-        if _RISK_HIGH_RE.search(hdr) and not _autonomy_lowered(hdr):
+        body6 = _raw_phase_bodies(root, slug).get(6, "")
+        _relaxed = (_task_sensitivity(hdr) == "mechanical"
+                    and _advisor_verdict_is_pass(body6)
+                    and _advisor_no_residue(body6))
+        if _RISK_HIGH_RE.search(hdr) and not _autonomy_lowered(hdr) and not _relaxed:
             _die(f"unguarded_high_risk_auto: task '{slug}' declares risk: high "
                  "without a lowered autonomy level — run `add.py autonomy set conservative` "
                  "(or manual); a human must own a high-risk gate (run.md guard)")
@@ -1063,10 +1383,22 @@ def cmd_gate(args: argparse.Namespace) -> None:
         _sync_task_marker(root, slug, "done")             # then mirror the phase into TASK.md — no split-brain
     _stamp_gate_record(root, state, slug, args.outcome)   # mirror the verdict into §6 (Finding C)
     _stamp_adr_record(root, state, slug)                  # adr-at-observe: harvest §7 Decisions (ADR) — AFTER §6 is mirrored
+    if completing:                                         # strip-scaffold-at-done: tidy the now-closed
+        _tf = root / "tasks" / slug / "TASK.md"           # TASK.md LAST (after the stampers) — drop the
+        try:                                              # live-phase `<!-- -->` comments; fences untouched.
+            _tt = _tf.read_text(encoding="utf-8")
+            _st = _strip_live_scaffold(_tt)
+            if _st != _tt:
+                _atomic_write(_tf, _st)
+        except OSError:
+            pass                                          # degrade-safe — the verdict is already in state
     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}")
+    _vfy = _task_verify(root, slug)                       # component-registry-fill: surface the verify command
+    if _vfy:
+        print(f"verify: {_vfy}   # run this suite — the engine does not (NO-EXEC)")
     # 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))
@@ -1097,6 +1429,20 @@ def _autonomy_decl_line(text: str, level: str) -> str:
     return f"autonomy: {level}\n" + text
 
 
+def _streams_decl_line(text: str, posture: str) -> str:
+    """Rewrite the SINGLE `streams:` declaration line to `posture`, PRESERVING its trailing comment,
+    idempotently (replace in place, count=1 — never a second line). If absent, insert it after a
+    leading `#` heading (PROJECT.md), else prepend. PURE on the text; the caller does the atomic
+    write. Mirrors _autonomy_decl_line — streams is project-scoped, so there is no slug-line branch."""
+    pat = re.compile(r"(?m)^(streams:[ \t]*)[^\s<#|]+(.*)$")
+    if pat.search(text):
+        return pat.sub(lambda m: f"{m.group(1)}{posture}{m.group(2)}", text, count=1)
+    lines = text.splitlines(keepends=True)
+    if lines and lines[0].lstrip().startswith("#"):
+        return lines[0] + f"streams: {posture}\n" + "".join(lines[1:])
+    return f"streams: {posture}\n" + text
+
+
 def _guard_autonomy_raise(current: str, target: str, yes: bool) -> None:
     """RAISING the level toward `auto` is a human-owned trust escalation (run.md: the AI may LOWER
     freely — RECOMMEND-only — but RAISING needs a human). Refuse a raise unless --yes confirms it."""
@@ -1146,6 +1492,25 @@ def cmd_autonomy(args: argparse.Namespace) -> None:
     _print_autonomy(root, state, slug)
 
 
+def cmd_streams(args: argparse.Namespace) -> None:
+    """show / set the project STREAMS posture — the parallel-vs-sequential half of the run mode
+    (persist-run-mode). Project-scoped (parallelism is ACROSS tasks, so there is no per-task posture)
+    and unguarded by a raise (parallel drops no human gate — it only overlaps builds). The setter
+    mirrors cmd_autonomy's --project branch: a PURE _streams_decl_line + atomic write into PROJECT.md.
+    state.json is UNTOUCHED — the posture lives in PROJECT.md beside autonomy."""
+    root = _require_root()                                   # reused -> "no .add/ project found …"
+    if (getattr(args, "action", None) or "show") == "show":
+        print(f"streams: {_project_streams(root)}")
+        return
+    posture = args.posture
+    if posture not in _STREAMS_POSTURES:
+        _die("streams_posture_invalid: posture must be one of "
+             f"{', '.join(_STREAMS_POSTURES)} (got {posture!r})")
+    target = root / "PROJECT.md"
+    _atomic_write(target, _streams_decl_line(target.read_text(encoding="utf-8"), posture))
+    print(f"project streams -> {posture}")
+
+
 def cmd_todo(args: argparse.Namespace) -> None:
     """Capture / list / close a lightweight backlog todo (task: todo-capture).
 
@@ -1425,18 +1790,41 @@ def _done_resume(root: Path, state: dict, slug: str) -> tuple[str, str, str]:
     return PLAIN
 
 
+_STATUS_PAGE_SIZE = 10  # status-pagination: default cap on milestones:/tasks: lists; --all lifts it
+
+
+def _sorted_by_updated(items: dict) -> list:
+    """Return `items.items()` sorted by each record's `updated` timestamp, newest first.
+    Read/serialization-time only — never mutates the caller's dict or state.json order."""
+    return sorted(items.items(), key=lambda kv: kv[1].get("updated") or "", reverse=True)
+
+
 def cmd_status(args: argparse.Namespace) -> None:
+    show_all = getattr(args, "all", False)
     if getattr(args, "json", False):
         root, state = _load_state_for_json()
         tasks = state.get("tasks") or {}
+        task_slug = getattr(args, "task", None)
+        if task_slug:
+            t = tasks.get(task_slug)
+            if t is None:
+                _die("unknown_task")
+            print(json.dumps({"slug": task_slug, "phase": t.get("phase"), "gate": t.get("gate"),
+                               "milestone": t.get("milestone"),
+                               "owner": t.get("owner"), "assignee": t.get("assignee")}))
+            return
         milestones = state.get("milestones") or {}
+        sorted_ms = _sorted_by_updated(milestones)
+        page_ms = sorted_ms if show_all else sorted_ms[:_STATUS_PAGE_SIZE]
         ms_list = []
-        for mslug, m in milestones.items():
+        for mslug, m in page_ms:
             members = [t for t in tasks.values() if t.get("milestone") == mslug]
             ms_list.append({"slug": mslug, "status": m.get("status", "active"),
                             "done": sum(1 for t in members if _task_done(t)),
                             "total": len(members),
                             "owner": m.get("owner"), "assignee": m.get("assignee")})
+        sorted_tasks = _sorted_by_updated(tasks)
+        page_tasks = sorted_tasks if show_all else sorted_tasks[:_STATUS_PAGE_SIZE]
         grad_ready, grad_met, grad_total = _graduation_ready(root, state)
         print(json.dumps({
             "project": state.get("project"), "stage": state.get("stage"),
@@ -1445,10 +1833,12 @@ def cmd_status(args: argparse.Namespace) -> None:
             "active_milestones": list(state.get("active_milestones") or []),
             "active_tasks": dict(state.get("active_tasks") or {}),
             "milestones": ms_list,
+            "milestones_total": len(milestones),
             "tasks": [{"slug": s, "phase": t.get("phase"), "gate": t.get("gate"),
                        "milestone": t.get("milestone"),
                        "owner": t.get("owner"), "assignee": t.get("assignee")}
-                      for s, t in tasks.items()],
+                      for s, t in page_tasks],
+            "tasks_total": len(tasks),
             "graduation_ready": grad_ready,
             "stage_criteria": {"met": grad_met, "total": grad_total}}))
         return
@@ -1463,6 +1853,9 @@ def cmd_status(args: argparse.Namespace) -> None:
     # project autonomy default (task init-auto-default): the posture new tasks INHERIT,
     # read LIVE from PROJECT.md so the human sees the project-wide throttle every session.
     print(f"project autonomy: {_project_autonomy(root)}   (default — new tasks inherit)")
+    # run mode (persist-run-mode): the combined streams + autonomy posture, both read LIVE from
+    # PROJECT.md so the human sees the whole run-mode throttle every session. Advisory; engine never spawns.
+    print(f"run mode: {_project_streams(root)} + {_project_autonomy(root)}")
     # git-native actor (user-identity): who ADD sees you as this session — the identity every
     # human-owned stamp records. Always present (the resolver is TOTAL). Read-only, no write.
     _who = identity._whoami(state)
@@ -1483,6 +1876,9 @@ def cmd_status(args: argparse.Namespace) -> None:
         _gr_cited, _gr_total = _exit_criteria_cited(root, _active_ms)
         _gr_state = "auto-ready ✓" if _goal_auto_ready(root, _active_ms) else "NOT auto-ready"
         print(f"goal-ready: {_gr_state}   ({_gr_cited}/{_gr_total} exit criteria cite a verifier)")
+        # dag-plan snapshot freshness (persist-dag-plan): per-active-milestone, read-only —
+        # fresh ✓ / stale / none / unreadable vs the LIVE depends_on edges. Advisory; never writes.
+        print(_dag_plan_status_line(root, state, _active_ms))
     # foundation pointer — read the cross-milestone context first (anti-rot)
     if (root / "PROJECT.md").exists():
         print("context : .add/PROJECT.md  (foundation: domain · spec · UI/UX — read first)")
@@ -1504,12 +1900,16 @@ def cmd_status(args: argparse.Namespace) -> None:
     active_ms = _active_milestone(state)
     if milestones:
         print("milestones:")
-        for mslug, m in milestones.items():
+        _sorted_ms = _sorted_by_updated(milestones)
+        _page_ms = _sorted_ms if show_all else _sorted_ms[:_STATUS_PAGE_SIZE]
+        for mslug, m in _page_ms:
             members = [t for t in tasks.values() if t.get("milestone") == mslug]
             done = sum(1 for t in members if _task_done(t))
             mark = "*" if mslug in (state.get("active_milestones") or []) else " "
             print(f"  {mark} {mslug:<20} {done}/{len(members)} tasks done"
                   f"   status={m.get('status', 'active')}")
+        if not show_all and len(_sorted_ms) > _STATUS_PAGE_SIZE:
+            print(f"  … {len(_sorted_ms) - _STATUS_PAGE_SIZE} more (see status --all)")
         # graduation cue (v22): project-global + read-only. Fires only when every milestone
         # is done AND the human's PROJECT.md stage-goal-criteria are all checked — additive
         # (a new line solely when ready; the non-ready output is byte-identical to before).
@@ -1578,6 +1978,19 @@ def cmd_status(args: argparse.Namespace) -> None:
     # reads the throttle every session; "unset" when no explicit `autonomy:` line is present.
     if active and active in tasks:
         print(f"autonomy: {_autonomy_level(_task_header(root, active)) or 'unset'}")
+        # the human-declared risk-CLASS (risk-sensitivity-taxonomy): present-only when a valid
+        # sensitivity is declared; "unset" cue when absent; "?" surfaces a typo to fix at freeze.
+        _sens = _task_sensitivity(_task_header(root, active), valid=_project_sensitivity_values(root))
+        print(f"sensitivity: {('unset' if _sens is None else _sens)}")
+        # step-spawn-hint (advisor-gated-autonomy): one advisory line naming the agent shape a
+        # parallel run would fan out at THIS step. Present-only (None → no line): suppressed under
+        # the `manual` dial and at contract/done. The tier reflects declared `risk: high`.
+        _hint = _spawn_hint_line(
+            {"phase": tasks[active].get("phase"),
+             "risk": "high" if _RISK_HIGH_RE.search(_task_header(root, active)) else None},
+            _project_autonomy(root))
+        if _hint:
+            print(_hint)
         # owner/assignee of the active task (ownership-assignment) — present-only, never a
         # placeholder; an unassigned active task adds no line (additive-cue convention).
         _own = _fmt_ownership(tasks[active])
@@ -1607,12 +2020,16 @@ def cmd_status(args: argparse.Namespace) -> None:
             print('          build with you. Escape hatch: add.py new-task <slug> --title "..."')
         return
     print("tasks   :")
-    for slug, t in tasks.items():
+    _sorted_tasks = _sorted_by_updated(tasks)
+    _page_tasks = _sorted_tasks if show_all else _sorted_tasks[:_STATUS_PAGE_SIZE]
+    for slug, t in _page_tasks:
         mark = "*" if slug == active else " "
         deps = t.get("depends_on") or []
         dep_s = f"  deps={','.join(deps)}" if deps else ""
         ms_s = f"  [{t['milestone']}]" if t.get("milestone") else ""
         print(f"  {mark} {slug:<24} phase={t['phase']:<10} gate={t['gate']}{ms_s}{dep_s}")
+    if not show_all and len(_sorted_tasks) > _STATUS_PAGE_SIZE:
+        print(f"  … {len(_sorted_tasks) - _STATUS_PAGE_SIZE} more (see status --all)")
     # fold-pressure nudge: surface unfolded competency deltas so emission can't
     # silently outrun the human fold (read-only; v11). Silent when none are open.
     open_deltas = sum(len(v) for v in _collect_open_deltas(root).values())
@@ -1737,6 +2154,14 @@ def cmd_guide(args: argparse.Namespace) -> None:
         print(f"guide  : {gp}")
     elif phase in _PHASE_GUIDE_FILES:
         print("guide  : (phase guides not installed — npx @pilotspace/add init)")
+    # step-spawn-hint (advisor-gated-autonomy): one advisory line naming the agent shape a parallel
+    # run would fan out at THIS step. Present-only: suppressed under `manual` and at contract/done.
+    _hint = _spawn_hint_line(
+        {"phase": phase,
+         "risk": "high" if _RISK_HIGH_RE.search(_task_header(root, slug)) else None},
+        _project_autonomy(root))
+    if _hint:
+        print(_hint)
     if phase == "verify":
         print("then   : add.py gate PASS | RISK-ACCEPTED | HARD-STOP")
     elif phase == "done":
@@ -2179,12 +2604,25 @@ def _missing_captures(root: Path) -> list[str]:
             if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
 
 
+def _federation_source_confined(root: Path, source: str) -> bool:
+    """True iff a federation manifest `source` resolves INSIDE the sibling-repo allowlist — the
+    workspace dir (root.parent.parent) that holds this project and its sibling checkouts. A legit
+    cross-repo source is one level up + down (`../<repo>/…`); an absolute path or a `../../` escape
+    resolves OUTSIDE and returns False. PURE + TOTAL — never raises (every error, incl. an embedded
+    NUL, → False, fail-closed), so cmd_federate can gate on it BEFORE any read (federation-harden)."""
+    try:
+        allow = root.parent.parent.resolve()
+        return _confined(root.parent / source, allow)
+    except (OSError, ValueError):
+        return False
+
+
 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)."""
+    `consumes: <id>` task then holds/pins identically. Designed-for-failure: unknown / escaping /
+    missing / invalid / version-mismatched sources HARD-STOP and land NOTHING (never build blind)."""
     root = find_root()
     if root is None:
         _die("no_project")
@@ -2193,6 +2631,13 @@ def cmd_federate(args: argparse.Namespace) -> None:
     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")
+    # federation-harden: confine the source to the sibling-repo allowlist BEFORE any read — an
+    # absolute path or a `../../` traversal must HARD-STOP and land nothing (never read a path
+    # that escapes the project's sibling repos). Checked after the id lookup, before read_bytes.
+    if not _federation_source_confined(root, fed[fid]["source"]):
+        _die(f"federation_source_escapes: the source '{fed[fid]['source']}' for '{fid}' resolves "
+             f"outside the sibling-repo allowlist (the workspace dir) — refusing to read a path "
+             f"that escapes the project's sibling repos")
     source = (root.parent / fed[fid]["source"])
     try:
         raw = source.read_bytes()       # bytes — the landed snapshot must be a byte-for-byte copy
@@ -2214,6 +2659,72 @@ def cmd_federate(args: argparse.Namespace) -> None:
     print(f"federated '{fid}' {snap.get('version', '?')} {snap['hash']} from {fed[fid]['source']}")
 
 
+def cmd_components(args: argparse.Namespace) -> None:
+    """Read-only: print + validate the component registry (.add/components.toml).
+
+    Opt-in — with no registry this is a friendly single-component no-op (exit 0). Prints
+    the parsed components/contracts/federation, then the existing RED integrity findings
+    (_component_findings + _contract_findings), then the new schema-lint WARNs
+    (_component_schema_findings); exits 1 IFF a RED finding exists (a typo/WARN never fails).
+    NO-EXEC — `verify` is shown as data, never run. Reads no docs/ chapter."""
+    root = find_root()
+    if root is None:
+        _die("no_project")
+    if not (root / "components.toml").exists():
+        print("single-component project (no components.toml) — nothing to validate")
+        return
+    comps, cons, feds = _components(root), _contracts(root), _federation(root)
+    for name in sorted(comps):
+        c = comps[name]
+        print(f"component {name}  root={c['root']}  verify={c.get('verify') or '-'}  "
+              f"green_bar={c.get('green_bar') or '-'}  language={c.get('language') or '-'}")
+    for cid in sorted(cons):
+        c = cons[cid]
+        print(f"contract {cid}  producer={c['producer']}  consumers={c['consumers']}")
+    for fid in sorted(feds):
+        f = feds[fid]
+        print(f"federation {fid}  source={f['source']}  pin={f.get('pin') or '-'}")
+    reds = sorted(_component_findings(root) + _contract_findings(root))
+    warns = sorted(_component_schema_findings(root))
+    for code, detail in reds:
+        print(f"ERROR {code}: {detail}")
+    for code, detail in warns:
+        print(f"WARN {code}: {detail}")
+    head = f"components: {len(comps)} · contracts: {len(cons)} · federation: {len(feds)}"
+    if reds or warns:
+        seg = ([f"{len(reds)} error(s)"] if reds else []) + ([f"{len(warns)} warning(s)"] if warns else [])
+        print(f"{head} — {', '.join(seg)}")
+    else:
+        print(f"{head} — valid")
+    if reds:
+        raise SystemExit(1)
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    """Read-only keyword/substring search over the milestone/task corpus (active
+    + archived) — title/goal/rationale (milestone) or title/Feature (task) lines
+    only, never full body, never graph traversal (context-search, search-index).
+    Fresh per-call scan via add_engine.search._search_corpus — no persisted
+    index/cache. Exit 0 always, including zero matches; --json mirrors
+    check/ready's own machine-readable convention."""
+    root = find_root()
+    if root is None:
+        _die("no_project")
+    hits = _search_corpus(root, args.keywords)
+    if getattr(args, "json", False):
+        print(json.dumps([{k: h[k] for k in ("slug", "kind", "status", "snippet")}
+                          for h in hits], ensure_ascii=False, indent=2))
+        return
+    query = " ".join(args.keywords)
+    if not hits:
+        print(f"no matches for: {query}")
+        return
+    print(f"{len(hits)} match(es) for: {query}")
+    for h in hits:
+        print(f"{h['slug']}  [{h['kind']}, {h['status']}]  ({h['count']} match(es))")
+        print(f"    {h['snippet']}")
+
+
 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)
@@ -2257,6 +2768,46 @@ def cmd_check(args: argparse.Namespace) -> None:
             # the intake flow — NOT a failure. Names structure, never the act of intake.
             warnings.append((f"task '{slug}'", "is outside a milestone — size it via the /add "
                                                "intake flow (or attach with --milestone)"))
+        # backlink-drift (task-milestone-backlink): the TASK.md `milestone:` header mirrors state.
+        # WARN (never red, warn-never-block) when a PRESENT line disagrees; an ABSENT line is a
+        # grandfathered task — silent, never retro-red. Degrade-safe: an unreadable file skips here.
+        try:
+            _task_text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+        except OSError:
+            _task_text = None
+        _bl = _read_milestone_line(_task_text) if _task_text is not None else None
+        if _bl is not None and _bl != _milestone_backlink_value(ms):
+            warnings.append((f"task '{slug}'", f"milestone backlink '{_bl}' disagrees with state "
+                             f"'{_milestone_backlink_value(ms)}' — re-run `add.py set-milestone "
+                             f"{slug} {ms or 'none'}` to re-sync"))
+        # §0 drift anchor (ground-anchor-sha): a §0 that cites bare line numbers (l.NNN) with no
+        # `Ground SHA:` has undetectable drift. WARN (never red, warn-never-block); a §0 with a SHA,
+        # with no line refs, or an unreadable file is silent. Reuses the read above (one read).
+        if _task_text is not None and _ground_cites_line_ref(_task_text) and \
+                _read_ground_sha(_task_text) is None:
+            warnings.append((f"task '{slug}'", "§0 cites line numbers (l.NNN) with no `Ground SHA:` — "
+                             "record `git rev-parse --short HEAD` so drift is detectable"))
+        # dangling lineage (delta-task-backlink): a `[SPEC · seeded] … [→ ptr]` whose pointer task
+        # is neither live nor archived. WARN (never red); reuses the read above. `_archived_task_slugs`
+        # is the same resolver `cmd_ready` trusts (archived ⇒ was PASS-done), so a healthy
+        # completed-then-archived seed stays silent.
+        if _task_text is not None:
+            _arch = _archived_task_slugs(state)
+            for _ptr in _seeded_delta_pointers(_task_text):
+                if _ptr not in tasks and _ptr not in _arch:
+                    warnings.append((f"task '{slug}'", f"seeded SPEC delta points at '{_ptr}' which no "
+                                     "longer exists (dangling lineage) — re-point or drop the delta"))
+        # rule-id-coverage: a §1 Must/Reject ID with no §2 scenario tag and no §4 `covers:`
+        # reference is a coverage gap. WARN only, runs in ANY phase (a gap in already-shipped
+        # work must still surface — the whole point of the check); opt-in per task via
+        # `_rule_coverage_gaps`'s own tag-presence gate, so a task that never adopted the M#/
+        # R:code convention is silently grandfathered — never retro-flagged.
+        if _task_text is not None:
+            _spans = _phase_spans(_task_text)
+            for _rid, _kind in _rule_coverage_gaps(_spans.get(1, ""), _spans.get(2, ""), _spans.get(4, "")):
+                warnings.append((f"task '{slug}'", f"rule '{_rid}' ({_kind}) has no §2 scenario tag "
+                                 "and no §4 test covering it (coverage gap) — add a scenario tag "
+                                 "or a covers: line"))
         # autonomy level (task explicit-autonomy-dial): a REAL out-of-set token is a hard
         # unknown_autonomy_level; a LIVE task (phase before done/observe) with no `autonomy:`
         # line is implicit_autonomy — a WARN, never red. Done/observe predecessors are SKIPPED
@@ -2290,6 +2841,28 @@ def cmd_check(args: argparse.Namespace) -> None:
                 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"))
+        # cross-component-recency: a consumer whose landed snapshot's LIVE producer drifted/unfroze
+        # since the snapshot — surfaced EARLY (never red) before the consumer re-enters §3, the
+        # check twin of the producer_contract_stale advance HARD-STOP. Degrade-safe.
+        _ccons = _task_consumes(root, slug)
+        if _ccons and _ccons in _contracts(root):
+            _csnap = _contract_snapshot(root, _ccons)
+            if _csnap.exists():
+                try:
+                    _chash = json.loads(_csnap.read_text(encoding="utf-8")).get("hash")
+                except (OSError, ValueError, AttributeError):
+                    _chash = None
+                if _chash is None:
+                    # cross-component-recency R1: a present-but-hash-less snapshot degrades the
+                    # recency check to existence-only (frozen behavior) — SURFACE the blind spot
+                    # (never red) so a hand-tampered/hash-stripped snapshot is not silently trusted.
+                    warnings.append((f"task '{slug}'", f"contract_snapshot_hashless — the landed "
+                                     f"snapshot for '{_ccons}' carries no hash; recency cannot be "
+                                     "verified (re-publish the producer contract / re-cross contract→tests)"))
+                elif _producer_snapshot_stale(root, _ccons, _chash):
+                    warnings.append((f"task '{slug}'", f"contract_producer_stale — the live producer "
+                                     f"of '{_ccons}' changed or re-opened its §3 since the landed "
+                                     "snapshot; re-cross the producer contract→tests, then re-enter"))
         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"))
@@ -2337,6 +2910,27 @@ def cmd_check(args: argparse.Namespace) -> None:
                                      "(scope_violation pending) — the verify gate "
                                      "will refuse it"))
 
+    # persona-setup: validate each persona living doc (.add/personas/*.md) presence-based
+    # (measure-not-block) — a missing required key/section is a WARN naming the slug, never a
+    # hard failure; a conformant persona is an INFO affirmation. NO-EXEC: pure read + predicate.
+    personas_dir = root / "personas"
+    if personas_dir.is_dir():
+        for pf in sorted(personas_dir.glob("*.md")):
+            slug = pf.stem
+            if not _persona_slug_valid(slug):
+                warnings.append((f"persona '{slug}'",
+                                 "persona_slug_invalid — rename to alphanumeric with - or _ only"))
+                continue
+            try:
+                missing = _persona_missing(pf.read_text(encoding="utf-8"))
+            except OSError:
+                missing = ["(unreadable)"]
+            if missing:
+                warnings.append((f"persona '{slug}'",
+                                 "persona_schema_incomplete: missing " + ", ".join(missing)))
+            else:
+                infos.append((f"persona '{slug}'", "schema-conformant"))
+
     # drift: a done milestone must have no unfinished tasks
     for mslug, m in milestones.items():
         if m.get("status") == "done":
@@ -2375,6 +2969,17 @@ def cmd_check(args: argparse.Namespace) -> None:
                              f"task '{_at}' froze its contract without grounding — fill the "
                              "§0 GROUND anchors the contract cites (add.py guide)"))
 
+    # sensitivity-glossary: nudge a project to declare its DOMAIN sensitivity classes. WARN, NEVER
+    # red (measure-not-block, mirrors goal_not_auto_ready) — the base four always apply; this only
+    # invites the project's own risk-class vocabulary into GLOSSARY.md (the AI maintains it per the
+    # skill guide). Fires IFF the "## Sensitivity classes" section declares no domain class.
+    if not _project_sensitivity_domain(root):
+        warnings.append(("sensitivity_classes_unset",
+                         "no domain sensitivity classes declared — add the project's risk-class "
+                         "vocabulary to GLOSSARY.md's '## Sensitivity classes' section (the base "
+                         "security|data|architecture|mechanical always apply; the AI keeps the "
+                         "domain classes current — see the sensitivity skill guide)"))
+
     # wave-ledger fork-base (engine-merge-base-enforcement): the engine EXECUTES the
     # streams.md rule — every roster echo must match `base:`. A FILLED mismatch is red at
     # ANY status; a pending row is red at `status: merging` (merge-time strictness) but only
@@ -2417,11 +3022,23 @@ def cmd_check(args: argparse.Namespace) -> None:
     # 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():
+        if not _federation_source_confined(root, _fspec["source"]):
+            # federation-harden: an out-of-allowlist source surfaced EARLY as a never-red WARN
+            # (escape takes precedence over unreadable — a real /etc/passwd passes is_file()).
+            warnings.append((f"federation '{_fid}'",
+                             f"federation_source_escapes — '{_fspec['source']}' resolves outside the "
+                             f"sibling-repo allowlist; `federate pull {_fid}` will HARD-STOP"))
+        elif 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"))
+    # components-validator: the schema-lint (typo'd/unknown key · wrong-type value · unknown
+    # table) is a never-red WARN — measure-not-block, forward-compat-safe. Rides `warnings`,
+    # NEVER `checks`/`failed`. Silent when no components.toml. `add.py components` is the
+    # richer surface; this catches the same typos EARLY in CI without failing the build.
+    for _scode, _sdetail in _component_schema_findings(root):
+        warnings.append((_scode, _sdetail))
 
     # 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.
@@ -3108,6 +3725,88 @@ def cmd_waves(args: argparse.Namespace) -> None:
         print("\n".join(_wave_block_lines(state, t, s)))
 
 
+# --- persisted DAG-plan snapshot (persist-dag-plan) --------------------------------
+# `waves` recomputes the schedule live and is the authority; `dag-plan` MATERIALIZES that
+# computed schedule into a committed, auditable per-milestone snapshot + a freshness check
+# against the live edges. The snapshot is NEVER the authority — only a checkable projection.
+def _dag_plan_path(root: Path, mslug: str) -> Path:
+    return root / "milestones" / mslug / "dag-plan.json"
+
+
+def _edges_fingerprint(state: dict, mslug: str) -> str:
+    """md5 over the EDGE STRUCTURE: every member's (done OR open) sorted depends_on. PURE.
+    Invariant under a task COMPLETING (phase/gate change, not edges) — so completion is NOT
+    drift — and changes only when a dep is added/removed/redirected or a member added/removed."""
+    tasks = state.get("tasks") or {}
+    edges = {s: sorted(t.get("depends_on") or [])
+             for s, t in tasks.items() if t.get("milestone") == mslug}
+    return _md5_text(json.dumps(edges, sort_keys=True))
+
+
+def _dag_plan_freshness(root: Path, state: dict, mslug: str) -> tuple[str, dict | None]:
+    """Read the snapshot and compare its stored fingerprint to the live one. Fail-safe:
+    absent -> ("none", None) · unreadable/garbled -> ("unreadable", None) · match -> "fresh"
+    · mismatch -> "stale". Never raises on a missing/corrupt file (no traceback to the user)."""
+    sp = _dag_plan_path(root, mslug)
+    if not sp.exists():
+        return ("none", None)
+    try:
+        snap = json.loads(sp.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return ("unreadable", None)
+    if not isinstance(snap, dict) or "edges_fingerprint" not in snap:
+        return ("unreadable", None)
+    live = _edges_fingerprint(state, mslug)
+    return (("fresh" if snap.get("edges_fingerprint") == live else "stale"), snap)
+
+
+def _dag_plan_status_line(root: Path, state: dict, mslug: str) -> str:
+    """The single `dag-plan:` line cmd_status prints for the active milestone."""
+    fresh, snap = _dag_plan_freshness(root, state, mslug)
+    if fresh == "fresh":
+        return "dag-plan: fresh ✓"
+    if fresh == "stale":
+        return f"dag-plan: stale (edges changed since {(snap or {}).get('generated', '?')})"
+    if fresh == "unreadable":
+        return "dag-plan: unreadable — run add.py dag-plan"
+    return "dag-plan: none — run add.py dag-plan"
+
+
+def cmd_dag_plan(args: argparse.Namespace) -> None:
+    """RECORD-ONLY: materialize the active (or --milestone) milestone's computed DAG schedule
+    into a committed snapshot + an edge fingerprint. Reuses cmd_waves' rejects; writes NOTHING
+    on any reject. Idempotent: an unchanged fingerprint leaves the file byte-identical."""
+    root = _require_root()
+    state = load_state(root)
+    mslug = getattr(args, "milestone", None) or _active_milestone(state)
+    if not mslug:
+        _die("no_active_milestone: no active milestone and no --milestone given")
+    if mslug not in (state.get("milestones") or {}):
+        _die(f"unknown_milestone: '{mslug}' is not a milestone in this project")
+    sched = _wave_schedule(state, mslug)
+    if "cycle" in sched:
+        _die(f"dependency_cycle: not-done deps form a cycle "
+             f"({' -> '.join(sched['cycle'])}) — no valid schedule")
+    live_fp = _edges_fingerprint(state, mslug)
+    sp = _dag_plan_path(root, mslug)
+    # idempotent: an unchanged fingerprint leaves the snapshot (and its `generated` date) untouched
+    if sp.exists():
+        try:
+            cur = json.loads(sp.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            cur = None
+        if isinstance(cur, dict) and cur.get("edges_fingerprint") == live_fp:
+            print(f"dag-plan: {mslug} already fresh ✓ (generated {cur.get('generated', '?')})")
+            return
+    snap = {"milestone": mslug, "generated": date.today().isoformat(),
+            "edges_fingerprint": live_fp, "schedule": sched}
+    sp.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write(sp, json.dumps(snap, indent=2, sort_keys=True) + "\n")
+    nwaves = len(sched.get("waves") or [])
+    ntasks = sum(len(w) for w in (sched.get("waves") or []))
+    print(f"dag-plan: wrote {mslug} — {nwaves} wave(s), {ntasks} task(s) (fresh ✓)")
+
+
 def cmd_milestone_done(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
@@ -3324,6 +4023,17 @@ def cmd_set_milestone(args: argparse.Namespace) -> None:
     state["tasks"][task]["milestone"] = new
     state["tasks"][task]["updated"] = _now()
     save_state(root, state)
+    # keep the TASK.md `milestone:` backlink in lockstep with state (task-milestone-backlink):
+    # rewrite the header line (insert it if a grandfathered file lacks it). Degrade-safe — a
+    # missing/unreadable TASK.md never blocks the move (state is already the source of truth).
+    task_md = root / "tasks" / task / "TASK.md"
+    try:
+        _txt = task_md.read_text(encoding="utf-8")
+        _new_txt = _set_milestone_line(_txt, _milestone_backlink_value(new))
+        if _new_txt != _txt:
+            _atomic_write(task_md, _new_txt)
+    except OSError:
+        pass
     print(f"task '{task}' -> milestone '{new}'" if new else f"task '{task}' -> milestone (none)")
     print(_next_footer(root, state))
 
@@ -3498,7 +4208,10 @@ def _tripwire_snapshot(root: Path, slug: str, raw3: str) -> dict:
         except (ValueError, OSError):
             rel = str(f)
         tests[rel] = h
-    return {"contract_md5": _md5_text(raw3), "tests": tests}
+    # strip-scaffold-at-done: fingerprint the contract CONTENT (comment-normalized, see
+    # _contract_fingerprint) so the at-done comment strip is invisible to the tamper guard; a real
+    # fenced-shape edit still changes it. Mirrored byte-for-byte in _tripwire_divergence.
+    return {"contract_md5": _contract_fingerprint(raw3), "tests": tests}
 
 
 def _tripwire_divergence(root: Path, slug: str, tw: dict) -> list[str]:
@@ -3506,7 +4219,9 @@ def _tripwire_divergence(root: Path, slug: str, tw: dict) -> list[str]:
     path directly (never re-globs), so a weakened, deleted, or unreadable test file
     and an edited frozen §3 all surface. Fail-closed: an unreadable file -> diverged."""
     diffs: list[str] = []
-    if _md5_text(_raw_phase_bodies(root, slug).get(3, "")) != tw.get("contract_md5"):
+    # compare the contract CONTENT fingerprint (strip-scaffold-at-done) — same normalization as the
+    # snapshot, so the at-done comment strip never reads as tampering; a real shape edit still does.
+    if _contract_fingerprint(_raw_phase_bodies(root, slug).get(3, "")) != tw.get("contract_md5"):
         diffs.append("contract_tampered")
     rootp = root.parent.resolve()
     for rel, snap in (tw.get("tests") or {}).items():
@@ -3525,7 +4240,10 @@ def _tripwire_divergence(root: Path, slug: str, tw: dict) -> list[str]:
 # likewise NOT a source touch — counting one produced repeated false `scope_violation`s in
 # consuming projects (`.next/`, `coverage/`, `tsconfig.tsbuildinfo`, whose `incremental`
 # rewrite even races a clean re-snapshot), so they are pruned here too.
-_SCOPE_EXCLUDE_DIRS = (".git", ".add", "__pycache__", "node_modules", ".serena",
+# `.claude` is an agent-tool internal dir (config/skills/worktrees) like `.serena` — never a
+# task's declared source; without it, the walk descends into `.claude/worktrees/<wt>/` (linked
+# git worktrees: full branch checkouts) and their churn produces false `scope_violation`s.
+_SCOPE_EXCLUDE_DIRS = (".git", ".add", ".claude", "__pycache__", "node_modules", ".serena",
                        ".next", "coverage", "test-results")
 _SCOPE_EXCLUDE_FILES = (".DS_Store",)                  # plus *.pyc / *.tsbuildinfo by suffix
 _SCOPE_EXCLUDE_SUFFIXES = (".pyc", ".tsbuildinfo")
@@ -3572,6 +4290,16 @@ def _task_green_bar(root: Path, slug: str) -> str | None:
     return (_components(root).get(comp) or {}).get("green_bar") or None
 
 
+def _task_verify(root: Path, slug: str) -> str | None:
+    """The `verify` COMMAND of the task's bound component (component-registry-fill) — the literal
+    suite the operator runs at the gate. Twin of _task_green_bar: unbound / "?" / no verify
+    declared all yield None. PURE. SURFACED as data only — the engine NEVER executes it (NO-EXEC)."""
+    comp = _task_component(root, slug)
+    if not comp or comp == "?":
+        return None
+    return (_components(root).get(comp) or {}).get("verify") or None
+
+
 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."""
@@ -3624,6 +4352,64 @@ def _task_consumes(root: Path, slug: str) -> str | None:
     return m.group(1).strip() if m else None
 
 
+def _producer_snapshot_stale(root: Path, cid: str, snap_hash: str | None) -> bool:
+    """True IFF a LIVE producer task backs `cid` (some task under root/tasks/ whose header carries
+    `produces: cid`) AND that producer's current §3 is NOT frozen, OR its frozen body-hash differs
+    from `snap_hash` (the landed snapshot's hash) — i.e. the producer re-opened/changed its contract
+    since the snapshot was written (cross-component-recency). No live producer task (archived in a
+    prior milestone, or a federation/external snapshot) -> False = existence-only, recency is the
+    producer repo's job via the federation version pin. snap_hash None / unreadable §3 -> False (not
+    confirmable here). PURE + TOTAL — never raises (a read error is a non-confirmation, not a block)."""
+    if snap_hash is None:
+        return False
+    tasks_dir = root / "tasks"
+    if not tasks_dir.is_dir():
+        return False
+    try:
+        producers = sorted(td.name for td in tasks_dir.iterdir() if td.is_dir())
+    except OSError:
+        return False
+    for pslug in producers:
+        if _task_produces(root, pslug) != cid:
+            continue
+        raw3 = _raw_phase_bodies(root, pslug).get(3, "")
+        if "FROZEN @" not in raw3:
+            return True                                  # live producer exists but its §3 is not frozen
+        return _contract_body_hash(raw3) != snap_hash    # frozen but drifted from the landed snapshot
+    return False                                         # no live producer backs cid -> existence-only
+
+
+def _consumer_contract_hold(root: Path, state: dict, slug: str) -> None:
+    """The cross-component consumer HOLD at the §3 boundary, shared by cmd_advance (nxt=="contract")
+    and cmd_phase (phase=="contract") so the admin override is not a backdoor (mirrors the
+    phase build -> _build_entry precedent). A `consumes: <cid>` task targeting a DECLARED contract:
+    a MISSING snapshot HARD-STOPs `producer_contract_unfrozen` (producer hasn't frozen); a PRESENT
+    snapshot whose live producer has drifted/unfrozen HARD-STOPs `producer_contract_stale`
+    (cross-component-recency — a stale leftover must not admit a consumer). No consumes / undeclared
+    id -> return (byte-identical; a typo'd id is a cmd_check finding). `state` is accepted for call-site
+    symmetry with _build_entry (unused here — the hold reads the task + contract files). Validate-
+    then-write: every _die precedes the caller's phase bump, so a refused task does not move."""
+    cid = _task_consumes(root, slug)
+    if not cid:
+        return
+    cmap = _contracts(root)
+    if cid not in cmap:
+        return
+    snap = _contract_snapshot(root, cid)
+    if not snap.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")
+    try:
+        snap_hash = json.loads(snap.read_text(encoding="utf-8")).get("hash")
+    except (OSError, ValueError, AttributeError):
+        snap_hash = None
+    if _producer_snapshot_stale(root, cid, snap_hash):
+        _die(f"producer_contract_stale: the live producer of contract '{cid}' changed or re-opened "
+             f"its §3 since the landed .add/contracts/{cid}.json — re-cross the producer "
+             "contract->tests to refresh the snapshot, then re-enter (never build against a stale shape)")
+
+
 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)
@@ -3644,6 +4430,67 @@ def _contract_findings(root: Path) -> list[tuple[str, str]]:
     return findings
 
 
+# ── components.toml schema-lint (components-validator) ─────────────────────────────────
+# The SOFT typo surface: the keys/tables a DEGRADE-SAFE read silently drops. All three
+# codes are WARN-severity (measure-not-block) — forward-compat-safe (an older engine
+# reading a newer file flags, never fails). Surfaced at `check` (as warnings) AND by
+# `add.py components`. PURE · DEGRADE-SAFE · NO-EXEC: reads only .add/components.toml,
+# never raises, never executes `verify`. A parse break is _component_findings' RED job.
+_SCHEMA_KNOWN_KEYS: dict[str, tuple[str, ...]] = {
+    "component": ("root", "verify", "green_bar", "language"),
+    "contract": ("producer", "consumers"),
+    "federation": ("source", "pin"),
+}
+_SCHEMA_KEY_TYPES: dict[str, dict[str, type]] = {
+    # `root` is intentionally absent — a missing/non-str root is already RED `components_malformed`
+    "component": {"verify": str, "green_bar": str, "language": str},
+    "contract": {"producer": str, "consumers": list},
+    "federation": {"source": str, "pin": str},
+}
+_SCHEMA_TYPENAME = {str: "a string", list: "a list"}
+
+
+def _component_schema_findings(root: Path) -> list[tuple[str, str]]:
+    """Schema-lint the components.toml registry for typos a degrade-safe read drops:
+    an unknown/misspelled key, a wrong-type value on a known key, or an unrecognized
+    top-level table. Returns [(code, detail)] (deterministic file order); [] when the
+    file is absent / opted-out / unparseable (no double-report with the RED surface).
+    All codes WARN: component_unknown_key · component_type_mismatch · component_unknown_table."""
+    if tomllib is None:
+        return []
+    try:
+        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
+        return []                       # a parse break is _component_findings' RED job
+    if not isinstance(data, dict):
+        return []
+    out: list[tuple[str, str]] = []
+    for top in data:                    # 1. unrecognized top-level tables/keys
+        if top not in _SCHEMA_KNOWN_KEYS:
+            out.append(("component_unknown_table",
+                        f"top-level [{top}] is not a known table "
+                        f"(expected one of: {', '.join(_SCHEMA_KNOWN_KEYS)})"))
+    for table, known in _SCHEMA_KNOWN_KEYS.items():     # 2/3. per-entry keys + value types
+        entries = data.get(table)
+        if not isinstance(entries, dict):
+            continue
+        types = _SCHEMA_KEY_TYPES[table]
+        for name, spec in entries.items():
+            if not isinstance(spec, dict):
+                continue                # a non-table entry is the RED surface's job
+            for key, val in spec.items():
+                if key not in known:
+                    out.append(("component_unknown_key",
+                                f"[{table}.{name}] has unknown key {key!r} "
+                                f"(known: {', '.join(known)})"))
+                elif key in types and not isinstance(val, types[key]):
+                    out.append(("component_type_mismatch",
+                                f"[{table}.{name}].{key} should be "
+                                f"{_SCHEMA_TYPENAME.get(types[key], types[key].__name__)}, "
+                                f"got {type(val).__name__}"))
+    return out
+
+
 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
@@ -4273,8 +5120,15 @@ def _flag_well_formed(raw3: str) -> bool:
     refused unless it takes the honest escape 'none material — biggest risk: X'.
     why/cost stay a human-read convention, never machine keywords (evidence: the
     lived flags use em-dash/prose, never literal because/if-wrong). HTML comments
-    (template hints) never count. PURE — fail-closed on a missing label."""
-    body = re.sub(r"<!--.*?-->", "", raw3, flags=re.S)
+    (template hints) never count. Fence-aware (mirrors _strip_live_scaffold): a
+    frozen §3 may legitimately quote a bare `<!--` inside its own fenced code
+    block (documenting an HTML-comment invariant) — that must never merge with
+    an unrelated `-->` found later in the raw text. PURE — fail-closed on a
+    missing label."""
+    segs = re.split(r"(```.*?```)", raw3, flags=re.DOTALL)
+    for i in range(0, len(segs), 2):      # even indices = OUTSIDE any fence
+        segs[i] = re.sub(r"<!--.*?-->", "", segs[i], flags=re.S)
+    body = "".join(segs)
     m = _FLAG_LABEL_RE.search(body)
     if not m:
         return False
@@ -4700,7 +5554,12 @@ def _collect_open_deltas(root: Path) -> dict[str, list[dict]]:
                 delta_text, evidence = em.group(1).strip(), em.group(2).strip()
             else:
                 delta_text, evidence = tail, ""
-            by_comp[comp].append({"task": slug, "text": delta_text, "evidence": evidence})
+            # OPTIONAL persona target + section hint (persona-self-improve) — None for a plain lesson.
+            pm = _PERSONA_TAG_RE.search(unit[0])
+            persona = pm.group(1).strip() if pm else None
+            hint = pm.group(2).strip() if pm else None
+            by_comp[comp].append({"task": slug, "text": delta_text, "evidence": evidence,
+                                  "persona": persona, "hint": hint})
     return by_comp
 
 
@@ -4826,7 +5685,11 @@ def _select_spec_delta(text: str, match: str | None = None,
 # literal, both exempt via MACHINE_CONSTANTS.
 _FOLD_VERB = "fold"        # the subcommand / decision-record verb
 _FOLDED = "folded"         # the resolved status value
-_COMP_OPEN_TOKEN_RE = re.compile(r"(\[\s*(?:DDD|SDD|UDD|TDD|ADD)\s*·\s*)open(\s*\])")
+# group(2) carries any OPTIONAL persona annotation (`· persona:<slug> · <hint>`) so flipping
+# open->folded preserves it byte-for-byte (persona-self-improve).
+_COMP_OPEN_TOKEN_RE = re.compile(
+    r"(\[\s*(?:DDD|SDD|UDD|TDD|ADD)\s*·\s*)open"
+    r"(\s*(?:·\s*persona:[^\s·\]]+\s*·\s*[^·\]]+?\s*)?\])")
 
 # competency -> (foundation file, section-heading PREFIX) — fold.md's routing table. DDD/SDD/UDD
 # land in PROJECT.md sections; TDD/ADD in CONVENTIONS.md (they ARE the engine). Total over the five.
@@ -4840,6 +5703,13 @@ _FOLD_ROUTES = {
 _KEY_DECISIONS_HEADING = "## Key Decisions"   # the universal audit-trail section (every session adds one row)
 _TABLE_SEP_RE = re.compile(r"\s*\|[-\s|]+\|\s*$")
 
+# persona-self-improve: a `persona:<slug>` lesson routes into `.add/personas/<slug>.md` instead of a
+# foundation file. The section HINT picks the growable section; only these two are routable.
+_PERSONA_FOLD_SECTIONS = {
+    "critical-rule": "## Critical Rules",
+    "success-metric": "## Success Metrics",
+}
+
 
 def _fold_competency_delta(text: str, version: int, comps=None) -> str | None:
     """Flip EVERY open competency lesson in `text` to resolved + append ` [<resolved> foundation-version N]`.
@@ -4934,11 +5804,16 @@ def cmd_fold(args: argparse.Namespace) -> None:
     prev_v = int(vm.group(1))
     new_v = prev_v + 1
 
-    # routing — every selected lesson's destination section (and the audit-trail section) must exist.
+    # A lesson with a `persona:<slug>` target routes to a persona living doc, NOT a foundation file
+    # (persona-self-improve). Partition first so the foundation-route checks skip persona lessons.
+    persona_sel = [it for it in selected if it.get("persona")]
+    found_sel = [it for it in selected if not it.get("persona")]
+
+    # routing — every FOUNDATION lesson's destination section (and the audit-trail section) must exist.
     conventions_md = root / "CONVENTIONS.md"
     conventions_text = conventions_md.read_text(encoding="utf-8") if conventions_md.exists() else ""
     file_text = {"PROJECT.md": project_text, "CONVENTIONS.md": conventions_text}
-    for it in selected:
+    for it in found_sel:
         fname, heading = _FOLD_ROUTES[it["comp"]]
         if not _section_present(file_text[fname], heading):
             _die(f"missing_route_section: {fname} has no '{heading}' section for a "
@@ -4947,6 +5822,21 @@ def cmd_fold(args: argparse.Namespace) -> None:
         _die(f"missing_route_section: PROJECT.md has no '{_KEY_DECISIONS_HEADING}' "
              "section for the audit-trail row — add the section header and re-run")
 
+    # persona routing — validate fail-closed BEFORE any write (design-for-failure): the section hint
+    # must be routable and the target persona file must exist. No network, no child launch — pure IO.
+    persona_paths: dict[str, Path] = {}
+    for it in persona_sel:
+        hint = (it.get("hint") or "").strip()
+        if hint not in _PERSONA_FOLD_SECTIONS:
+            _die(f"persona_section_unroutable: '{hint or '(none)'}' is not a growable persona "
+                 f"section — use one of {', '.join(_PERSONA_FOLD_SECTIONS)}")
+        slug = it["persona"]
+        ppath = root / "personas" / f"{slug}.md"
+        if not _persona_slug_valid(slug) or not ppath.is_file():
+            _die(f"missing_persona_target: no .add/personas/{slug}.md for a persona lesson — "
+                 "seed the persona first (setup) or fix the slug")
+        persona_paths[slug] = ppath
+
     # ── build EVERY edit in memory before writing anything ──────────────────────────────────────
     comps_filter = {want_comp} if want_comp else None
     task_new: dict[str, str] = {}
@@ -4962,15 +5852,40 @@ def cmd_fold(args: argparse.Namespace) -> None:
         return (f"- ({it['comp']}) {it['text']}{ev}  "
                 f"[{_FOLDED} foundation-version {new_v} · from {it['task']}]")
 
-    # transcribe verbatim (reverse so canonical-order first lands on top, newest-first).
+    def _persona_bullet(it):
+        ev = f" (evidence: {it['evidence']})" if it["evidence"] else ""
+        return (f"- {it['text']}{ev}  "
+                f"[{_FOLDED} {date.today().isoformat()} · from {it['task']}]")
+
+    # transcribe FOUNDATION lessons verbatim (reverse so canonical-order first lands on top, newest-first).
     proj_text, conv_text = project_text, conventions_text
-    for it in reversed(selected):
+    for it in reversed(found_sel):
         fname, heading = _FOLD_ROUTES[it["comp"]]
         if fname == "PROJECT.md":
             proj_text = _prepend_to_section(proj_text, heading, _bullet(it))
         else:
             conv_text = _prepend_to_section(conv_text, heading, _bullet(it))
 
+    # transcribe PERSONA lessons into their living docs — PREPEND newest-first under the hinted
+    # section, NEVER clobbering (every prior persona line survives; the schema stays conformant).
+    from collections import Counter
+    persona_new: dict[str, str] = {}
+    for it in reversed(persona_sel):
+        slug = it["persona"]
+        before = persona_new.get(slug) or persona_paths[slug].read_text(encoding="utf-8")
+        heading = _PERSONA_FOLD_SECTIONS[it["hint"].strip()]
+        if not _section_present(before, heading):           # defensive: a conformant persona has it
+            _die(f"persona_section_unroutable: .add/personas/{slug}.md has no '{heading}' section")
+        after = _prepend_to_section(before, heading, _persona_bullet(it))
+        # never-clobber INVARIANT: every pre-existing line must survive the merge.
+        if Counter(before.splitlines()) - Counter(after.splitlines()):
+            _die(f"persona_clobber_forbidden: consolidating into {slug}.md would drop existing content")
+        # post-merge INVARIANT: the four required persona sections survive.
+        if _persona_missing(after):
+            _die(f"persona_clobber_forbidden: consolidating into {slug}.md broke the persona schema "
+                 f"(missing {', '.join(_persona_missing(after))})")
+        persona_new[slug] = after
+
     counts = {c: sum(1 for it in selected if it["comp"] == c) for c in _COMPETENCY_ORDER}
     count_str = " · ".join(f"{c} {counts[c]}" for c in _COMPETENCY_ORDER if counts[c])
     scope = "all" if not (want_task or want_comp) else " ".join(
@@ -4993,6 +5908,10 @@ def cmd_fold(args: argparse.Namespace) -> None:
     for slug, body in task_new.items():
         writes.append((root / "tasks" / slug / "TASK.md", body))
     touched.append(f"{len(task_new)} TASK.md")
+    for slug, body in persona_new.items():
+        writes.append((persona_paths[slug], body))
+    if persona_new:
+        touched.append(f"{len(persona_new)} persona")
     _atomic_write_many(writes)
 
     print(f"{_FOLDED} {len(selected)} lessons -> foundation-version {new_v}")
@@ -5067,8 +5986,14 @@ def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
         # F7 unguarded_high_risk_auto (task high-risk-signal, v14): a declared
         # high-risk record must show a guarded dial AND a human at the gate —
         # catches post-gate header tampering and auto-resolved high-risk gates.
+        # advisor-gate-relax: a mechanical task whose Advisor 3-lens verdict shows
+        # PASS + Residue: none is exempt — the outer condition is False so both
+        # sub-branches are skipped.  Non-mechanical (security/data/architecture)
+        # never relax; an absent advisor block is fail-safe False → guard fires.
         hdr = _task_header(root, slug)
-        if _RISK_HIGH_RE.search(hdr):
+        if _RISK_HIGH_RE.search(hdr) and not (_task_sensitivity(hdr) == "mechanical"
+                and _advisor_verdict_is_pass(s6)
+                and _advisor_no_residue(s6)):
             if not _autonomy_lowered(hdr):
                 f(slug, "unguarded_high_risk_auto",
                   "risk: high declared but autonomy is not lowered (manual or conservative)")
@@ -5119,24 +6044,68 @@ def _guarantee_lint_notices(root: Path, state: dict) -> dict:
       shallow[]          = §6 '### Deep checks' block present-but-unfilled (_section_unfilled; an
                            ABSENT block grandfathers a legacy task — never retro-flagged);
       risk_unset[]       = the header carries NO `risk:` token (an undeclared risk level at verify);
+      sensitivity_unset[]= the header carries NO valid `sensitivity:` token (risk-sensitivity-taxonomy);
       refute_unrecorded[]= §6 '### Refute-read verdict' block present-but-unfilled (self-grading-
                            refute-record, M4) — the earned-green verdict the AI must record under
                            `auto`; ABSENT block grandfathers exactly like shallow. MEASURE-NOT-BLOCK:
                            never auto-blocks a gate, only surfaced here for review + a human spot-audit.
     Honest visibility for three verify guarantees; NEVER a finding (audit stays exit 0). PURE — reads
     TASK.md + state only, writes nothing."""
-    shallow, risk_unset, refute_unrecorded = [], [], []
+    shallow, risk_unset, refute_unrecorded, sensitivity_unset = [], [], [], []
+    advisor_verdict_unrecorded = []
+    advisor_reviewer_is_author = []
+    advisor_residue_on_mechanical_mis_tier = []
     for slug in sorted(state.get("tasks") or {}):
         if (state["tasks"][slug] or {}).get("phase") not in ("verify", "observe", "done"):
             continue
         body6 = _raw_phase_bodies(root, slug).get(6, "")
+        hdr = _task_header(root, slug)
         if _section_unfilled(body6, "### Deep checks"):
             shallow.append(slug)
         if _section_unfilled(body6, "### Refute-read verdict"):
             refute_unrecorded.append(slug)
-        if not _RISK_ANY_RE.search(_task_header(root, slug)):
+        if _section_unfilled(body6, "### Advisor 3-lens verdict"):
+            advisor_verdict_unrecorded.append(slug)
+        if not _RISK_ANY_RE.search(hdr):
             risk_unset.append(slug)
-    return {"shallow": shallow, "risk_unset": risk_unset, "refute_unrecorded": refute_unrecorded}
+        # sensitivity_unset (risk-sensitivity-taxonomy): a verify-reached task with no
+        # human-declared sensitivity — MEASURE-NOT-BLOCK, same class as risk_unset.
+        if _task_sensitivity(hdr) is None:
+            sensitivity_unset.append(slug)
+        # advisor_reviewer_is_author / advisor_residue_on_mechanical_mis_tier
+        # (advisor-verdict-audit): MEASURE-NOT-BLOCK lints on the filled advisor block.
+        # Both require the block to be PRESENT AND FILLED (not just unfilled).
+        # Extract ONLY the advisor sub-section to avoid false matches from
+        # the Refute-read verdict block (which also carries Verdict:/Residue: lines).
+        _advisor_body = ""
+        _adv_idx = body6.find("### Advisor 3-lens verdict")
+        if _adv_idx != -1:
+            _adv_rest = body6[_adv_idx + len("### Advisor 3-lens verdict"):]
+            _next_hdr = re.search(r"\n###", _adv_rest)
+            _advisor_body = _adv_rest[:_next_hdr.start()] if _next_hdr else _adv_rest
+        _advisor_filled = (_adv_idx != -1
+                           and not _section_unfilled(body6, "### Advisor 3-lens verdict"))
+        if _advisor_filled:
+            _ma = re.search(r"(?m)^Advisor:(.*)$", _advisor_body)
+            _advisor_name = _ma.group(1).strip() if _ma else ""
+            _gate_name = (state["tasks"][slug].get("gate_actor") or {}).get("name", "").strip()
+            if (_advisor_name and _gate_name
+                    and _advisor_name.lower() == _gate_name.lower()):
+                advisor_reviewer_is_author.append(slug)
+            _sens = _task_sensitivity(hdr)
+            if _sens == "mechanical":
+                _mr = re.search(r"(?m)^Residue:(.*)$", _advisor_body)
+                _mv = re.search(r"(?m)^Verdict:(.*)$", _advisor_body)
+                _residue = _mr.group(1).strip() if _mr else ""
+                _verdict = _mv.group(1).strip() if _mv else ""
+                if (_residue and _residue.lower() != "none"
+                        and _verdict.upper().startswith("PASS")):
+                    advisor_residue_on_mechanical_mis_tier.append(slug)
+    return {"shallow": shallow, "risk_unset": risk_unset, "refute_unrecorded": refute_unrecorded,
+            "sensitivity_unset": sensitivity_unset,
+            "advisor_verdict_unrecorded": advisor_verdict_unrecorded,
+            "advisor_reviewer_is_author": advisor_reviewer_is_author,
+            "advisor_residue_on_mechanical_mis_tier": advisor_residue_on_mechanical_mis_tier}
 
 
 def cmd_audit(args: argparse.Namespace) -> None:
@@ -5169,8 +6138,28 @@ def cmd_audit(args: argparse.Namespace) -> None:
             ru = glints["refute_unrecorded"]
             print(f"audit: refute_unrecorded — {len(ru)} task(s): {', '.join(ru)} "
                   f"— record the earned-green refute verdict (§6); a spot-audit is the backstop")
+        if glints["advisor_verdict_unrecorded"]:
+            av = glints["advisor_verdict_unrecorded"]
+            print(f"audit: advisor_verdict_unrecorded — {len(av)} task(s): {', '.join(av)} "
+                  f"— record the 3-lens advisor verdict (§6); a spot-audit is the backstop")
+        if glints["sensitivity_unset"]:
+            su = glints["sensitivity_unset"]
+            print(f"audit: sensitivity_unset — {len(su)} task(s) reached verify with no "
+                  f"sensitivity: declaration: {', '.join(su)}")
+        if glints["advisor_reviewer_is_author"]:
+            ar = glints["advisor_reviewer_is_author"]
+            print(f"audit: advisor_reviewer_is_author — {len(ar)} task(s): {', '.join(ar)} "
+                  f"— advisor and gate actor are the same identity")
+        if glints["advisor_residue_on_mechanical_mis_tier"]:
+            am = glints["advisor_residue_on_mechanical_mis_tier"]
+            print(f"audit: advisor_residue_on_mechanical_mis_tier — {len(am)} task(s): "
+                  f"{', '.join(am)} — mechanical tier with non-none residue and PASS verdict "
+                  f"is incoherent; consider re-tiering")
         if not findings and not skips and not glints["shallow"] and not glints["risk_unset"] \
-                and not glints["refute_unrecorded"]:
+                and not glints["refute_unrecorded"] and not glints["advisor_verdict_unrecorded"] \
+                and not glints["sensitivity_unset"] \
+                and not glints["advisor_reviewer_is_author"] \
+                and not glints["advisor_residue_on_mechanical_mis_tier"]:
             print(f"audit: clean ({checked} tasks checked)")
     # MEASURE-NOT-BLOCK: only real findings raise the exit code; notices never do.
     if findings:
@@ -5570,8 +6559,23 @@ def cmd_release(args: argparse.Namespace) -> None:
                              _render_releases_row(args.version, day, bundle, waiver_slugs,
                                                   getattr(args, "evidence", None),
                                                   identity._render_actor_line(state), loose_bundle))
-    try:                                              # CHANGELOG + RELEASES as one all-or-nothing commit
-        _atomic_write_many([(changelog_path, new_cl), (releases_path, new_rel)])
+    # milestone-release-backlink: STAMP each bundled milestone's MILESTONE.md `release:` line to
+    # the cut version. Built in memory NOW and appended to the SAME atomic batch as the ledgers,
+    # so the stamp commits all-or-nothing with them (a failed write rolls back everything). Only
+    # `bundle` (closed-and-unreleased) milestones are stamped; a missing/unreadable file is skipped
+    # (degrade-safe — the ledger attribution stays the source of truth).
+    stamp_writes: list[tuple[Path, str]] = []
+    for m in bundle:
+        mfile = root / "milestones" / m["slug"] / "MILESTONE.md"
+        try:
+            _mtxt = mfile.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        _stamped = _set_release_line(_mtxt, args.version)
+        if _stamped != _mtxt:
+            stamp_writes.append((mfile, _stamped))
+    try:                                              # CHANGELOG + RELEASES + milestone stamps: one all-or-nothing commit
+        _atomic_write_many([(changelog_path, new_cl), (releases_path, new_rel)] + stamp_writes)
     except OSError as e:
         _die(f"release_write_failed: the ledger write failed ({e}); nothing was recorded — both "
              "files were rolled back to their prior content. Retry the release.")
@@ -5764,6 +6768,10 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("--run-mode", dest="run_mode", default=None,
+                    choices=["auto", "conservative"],
+                    help="seed autonomy+streams posture: auto→parallel, conservative→sequential "
+                         "(absent: PROJECT.md is byte-identical to a plain init)")
     pi.set_defaults(func=cmd_init)
 
     pl = sub.add_parser("lock",
@@ -5892,6 +6900,13 @@ def build_parser() -> argparse.ArgumentParser:
     pwa.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pwa.set_defaults(func=cmd_waves)
 
+    pdp = sub.add_parser("dag-plan", help="record a committed snapshot of the milestone's computed "
+                                          "DAG schedule (waves + critical path + tiers) + a freshness "
+                                          "check vs the live depends_on edges")
+    pdp.add_argument("--milestone", default=None,
+                     help="milestone slug to snapshot (default: the active milestone)")
+    pdp.set_defaults(func=cmd_dag_plan)
+
     pmd = sub.add_parser("milestone-done", help="exit-gate a milestone (all tasks must PASS)")
     pmd.add_argument("slug")
     pmd.set_defaults(func=cmd_milestone_done)
@@ -5962,6 +6977,11 @@ def build_parser() -> argparse.ArgumentParser:
                      help="confirm a RAISE toward auto (a human-owned trust escalation)")
     pan.set_defaults(func=cmd_autonomy, _opt_positionals=("a1", "a2"))
 
+    pst = sub.add_parser("streams", help="show or set the project streams posture (parallel|sequential)")
+    pst.add_argument("action", nargs="?", choices=("show", "set"), default="show")
+    pst.add_argument("posture", nargs="?", default=None, help="set: <parallel|sequential>")
+    pst.set_defaults(func=cmd_streams, _opt_positionals=("posture",))
+
     pto = sub.add_parser("todo", help="capture / list / close a lightweight backlog todo (jot an idea)")
     pto.add_argument("text", nargs="?", default=None,
                      help="todo text to capture; omit to LIST open todos")
@@ -5992,12 +7012,29 @@ def build_parser() -> argparse.ArgumentParser:
 
     pst = sub.add_parser("status", help="print where the project is (resume point)")
     pst.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    pst.add_argument("--task", metavar="SLUG", help="with --json, filter to one task's "
+                      "{slug, phase, gate, milestone, owner, assignee} object")
+    pst.add_argument("--all", action="store_true", help="show every milestone/task "
+                      "(default: top 10 by most-recently-updated)")
     pst.set_defaults(func=cmd_status)
 
     pck = sub.add_parser("check", help="read-only integrity check of the .add project")
     pck.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pck.set_defaults(func=cmd_check)
 
+    pcomp = sub.add_parser("components",
+                           help="read-only: print + validate the component registry "
+                                "(.add/components.toml) — RED integrity errors + schema-lint typo warnings")
+    pcomp.set_defaults(func=cmd_components)
+
+    psrch = sub.add_parser("search", help="keyword/substring search over the "
+                            "milestone/task corpus (active + archived) — "
+                            "title/goal/rationale lines only, never the full body")
+    psrch.add_argument("keywords", nargs="+", metavar="KEYWORD",
+                       help="one or more keywords (case-insensitive substring, OR-combined)")
+    psrch.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    psrch.set_defaults(func=cmd_search)
+
     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)