@pilotspace/add 1.13.0 → 1.15.0

package/tooling/add_engine/autonomy.py

@@ -11,10 +11,11 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from add_engine.constants import _AUTONOMY_LEVELS
+from add_engine.constants import _AUTONOMY_LEVELS, _STREAMS_POSTURES
 from add_engine.taskdoc import _task_header
 
 _AUTONOMY_LINE_RE = re.compile(r"(?:^|·)[ \t]*autonomy:[ \t]*([^\s<#|]+)", re.MULTILINE)
+_STREAMS_LINE_RE = re.compile(r"(?:^|·)[ \t]*streams:[ \t]*([^\s<#|]+)", re.MULTILINE)
 
 
 def _autonomy_level(hdr: str):
@@ -56,3 +57,37 @@ def _project_autonomy(root: Path) -> str:
     Read-only and PURE — mirrors _project_goal; the seed source for cmd_new_task."""
     tok = _project_autonomy_token(root)
     return "auto" if tok is None else ("conservative" if tok == "?" else tok)
+
+
+# --- streams posture: the parallel-vs-sequential half of the run mode (persist-run-mode) ---
+# A project-scoped declaration in PROJECT.md beside autonomy. Mirrors the autonomy resolvers:
+# anchored read (a title/prose substring is never a declaration), fail-safe defaults.
+
+def _streams_posture(text: str):
+    """The declared streams posture from a foundation region (HTML comments already stripped
+    by the caller). A member of _STREAMS_POSTURES, None when no `streams:` line is present, or
+    "?" when a REAL token outside the set was written (unknown). PURE."""
+    m = _STREAMS_LINE_RE.search(text)
+    if not m:
+        return None
+    tok = m.group(1).strip().lower()
+    return tok if tok in _STREAMS_POSTURES else "?"
+
+def _project_streams_token(root: Path):
+    """The RAW streams declaration in PROJECT.md — a recognized posture, None when no
+    declaration line is present, or "?" for a real-but-unrecognized token. Uses the anchored
+    _streams_posture (a title/prose substring is never a declaration) with HTML comments
+    stripped. Unreadable foundation -> None. Read-only and PURE."""
+    try:
+        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+    except OSError:
+        return None
+    return _streams_posture(re.sub(r"<!--.*?-->", "", text, flags=re.S))
+
+def _project_streams(root: Path) -> str:
+    """The streams posture the project runs under. Fail-SAFE: no declaration -> "parallel"
+    (the documented project default: parallel+auto); an unrecognized token -> "sequential"
+    (the conservative fallback, NEVER silently parallel); an unreadable foundation -> "parallel".
+    Read-only and PURE — mirrors _project_autonomy."""
+    tok = _project_streams_token(root)
+    return "parallel" if tok is None else ("sequential" if tok == "?" else tok)

package/tooling/add_engine/constants.py

@@ -22,6 +22,8 @@ __all__ = [
     "PHASE_GUIDE",
     "PHASE_OWNER",
     "SETUP_FILES",
+    "PERSONA_FRONTMATTER_KEYS",
+    "PERSONA_REQUIRED_SECTIONS",
     "GUIDELINE_FILES",
     "RULES_FILE_REL",
     "WORKFLOW_HEADINGS",
@@ -88,7 +90,14 @@ PHASE_OWNER = {
     "specify": "human", "scenarios": "human", "contract": "seam",
     "tests": "ai", "build": "ai", "verify": "human", "observe": "ai", "done": "human",
 }
-SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md")
+SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md", "personas/_template.md")
+
+# persona-setup: a PERSONA living doc (`.add/personas/<slug>.md`) is a frozen-schema file
+# distilled from the vendored teacher library to its critical-rules + default-requirement +
+# measurable success-metrics. The schema is presence-based (these keys/sections must exist);
+# content quality is the AI's authoring concern, not the engine gate. NO-EXEC: validation is pure.
+PERSONA_FRONTMATTER_KEYS = ("name", "vibe")
+PERSONA_REQUIRED_SECTIONS = ("## Identity", "## Critical Rules", "## Default Requirement", "## Success Metrics")
 
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
 # never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
@@ -109,12 +118,24 @@ scope-snapshot.json
 pre-archive-state.bak.json
 pre-update-state.bak.json
 .update-cache.json
+
+# ADD-managed vendor trees: regenerable/vendored copies the installer drops in,
+# never project-authored — mirrors the .add/docs/ rationale above, generalized
+# to every consumer project (not just this repo). Patterns are BARE, not repo-
+# root style: this file lives INSIDE .add/, so git resolves its patterns
+# relative to .add/ itself — a ".add/"-prefixed pattern here would look for
+# the non-existent .add/.add/tooling/ and never match anything. (one further
+# managed tree is NOT listed here — the engine's own _GITIGNORE_BODY constant
+# must stay hands-off of it by name; the installer twins seed that pattern
+# themselves, also bare.)
+tooling/
+docs/
 """
 
 # Guideline-injection targets + version-stable markers. NEVER change these marker
 # strings: a re-run finds the old block by exact match, so changing them would
 # orphan every block written by a prior version (see TASK guideline-inject).
-GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md")
+GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md", ".clinerules")
 _GUIDE_BEGIN = "<!-- ADD:BEGIN — managed by `add.py sync-guidelines`; do not edit inside -->"
 _GUIDE_END = "<!-- ADD:END -->"
 
@@ -208,14 +229,46 @@ _DEFAULT_WIDTH = 72       # fixed width for the persisted/canonical render (RETR
 
 
 # --- shared delta-parsing regexes (used by taskdoc readers AND the deltas-web lint) ---
+# Groups stay (1) competency, (2) status, (3) text — every caller relies on that. A competency
+# lesson MAY carry an OPTIONAL persona target + section hint between status and `]`
+# (persona-self-improve): `[<comp> · <status> · persona:<slug> · <critical-rule|success-metric>] …`.
+# That clause is NON-capturing here (group numbering unchanged); _PERSONA_TAG_RE below pulls the
+# slug + hint out when a route needs them — permissively, so an unroutable hint still PARSES (and is
+# rejected by code) rather than silently failing to match.
 _DELTA_RE = re.compile(
-    r"\s*-\s*\[\s*(DDD|SDD|UDD|TDD|ADD)\s*·\s*(open|folded|rejected)\s*\]\s*(.+)$"
+    r"\s*-\s*\[\s*(DDD|SDD|UDD|TDD|ADD)\s*·\s*(open|folded|rejected)"
+    r"(?:\s*·\s*persona:[^\s·\]]+\s*·\s*[^·\]]+?)?\s*\]\s*(.+)$"
 )
+# Pull the OPTIONAL persona target + section hint out of a delta tag line (persona-self-improve).
+_PERSONA_TAG_RE = re.compile(r"persona:([^\s·\]]+)\s*·\s*([^·\]]+?)\s*\]")
 _EVIDENCE_RE = re.compile(r"^(.*?)\s*\(evidence:\s*(.*?)\)\s*$")
 _SPEC_DELTA_RE = re.compile(
     r"\s*-\s*\[\s*(SPEC)\s*·\s*(open|seeded|dropped|carried)\s*\]\s*(.+)$"
 )
 
+# delta-task-backlink: reads the `[→ <slug>]` seed stamp `_resolve_spec_delta` appends, so the
+# delta→task lineage can be walked back (check WARNs when a seeded pointer no longer resolves).
+_SEED_POINTER_RE = re.compile(r"\[→\s*([A-Za-z0-9_-]+)\s*\]")
+
+# rule-id-coverage: §1 Must-ID / Reject-code lines, plus the §2 scenario tag and §4 `covers:`
+# back-reference a task uses to claim coverage of a rule. A Reject's ID is its literal error_code
+# string (from `-> "<error_code>"`), never a positional R1/R2 sequence number.
+_MUST_ID_RE = re.compile(r"^\s*-\s*(M\d+)\s*:", re.MULTILINE)
+_REJECT_CODE_RE = re.compile(r'^\s*-\s.*->\s*"([^"]+)"\s*$', re.MULTILINE)
+_SCENARIO_TAG_RE = re.compile(r"^\s*Scenario:.*#\s*(.+?)\s*$", re.MULTILINE)
+_COVERS_LINE_RE = re.compile(r"covers:\s*(.+?)\s*$", re.MULTILINE)
+_TAG_TOKEN_RE = re.compile(r"(M\d+|R:[A-Za-z0-9_]+)")
+
 
 # --- autonomy levels (shared: autonomy resolvers + _AUTONOMY_ORDER/cmd_autonomy) ---
 _AUTONOMY_LEVELS = ("manual", "conservative", "auto")
+
+# --- streams posture (shared: streams resolvers + cmd_streams) — the parallel-vs-sequential
+#     half of the run mode (persist-run-mode); project-scoped, persisted in PROJECT.md beside autonomy ---
+_STREAMS_POSTURES = ("parallel", "sequential")
+
+# --- sensitivity taxonomy (shared: _task_sensitivity reader + cmd_freeze/status/audit) — the
+#     risk-CLASS the human declares in the TASK header at freeze (risk-sensitivity-taxonomy). The
+#     engine validates + surfaces a HUMAN-declared token; it NEVER classifies. A closed enum, sibling
+#     of _AUTONOMY_LEVELS/_STREAMS_POSTURES. Consumed downstream by advisor-gate-relax (mechanical). ---
+_SENSITIVITY_VALUES = ("security", "data", "architecture", "mechanical")

package/tooling/add_engine/guidelines.py

@@ -1,10 +1,11 @@
 """add_engine.guidelines — the guidelines / CLAUDE.md-injection subsystem (engine-modularization 8/N).
 
-Inject one stable, marker-delimited ADD block into the project root's AGENTS.md and
-CLAUDE.md. DYNAMIC-BY-REFERENCE: the block tells the agent to run `add.py status` and
-read PROJECT.md — it never embeds live state. A closed, self-contained cluster (8 fns +
-the cluster-private _INIT_EXCLUDE); transitive-closure AST scan: ZERO outbound calls to
-non-cluster add fns. Deps: constants + _atomic_write (io_state) + stdlib. None patched.
+Inject one stable, marker-delimited ADD block into every GUIDELINE_FILES target under the
+project root (AGENTS.md, CLAUDE.md, .clinerules). DYNAMIC-BY-REFERENCE: the block tells the
+agent to run `add.py status` and read PROJECT.md — it never embeds live state. A closed,
+self-contained cluster (8 fns + the cluster-private _INIT_EXCLUDE); transitive-closure AST
+scan: ZERO outbound calls to non-cluster add fns. Deps: constants + _atomic_write (io_state)
++ stdlib. None patched.
 """
 from __future__ import annotations
 
@@ -34,24 +35,25 @@ def _guideline_block() -> str:
         "the human owns direction and verification. The loop below works for any agent —\n"
         "Claude, Cursor, Copilot, Codex — through the CLI alone. Before you change code:\n"
         "\n"
-        "1. Run `python3 .add/tooling/add.py status` — where the project is and what's\n"
-        "   next (the resume point; read it first every session).\n"
-        "2. Read `.add/PROJECT.md` — the foundation (domain · spec · UI/UX) every task\n"
-        "   builds on.\n"
-        "3. Run `python3 .add/tooling/add.py guide` — it names the phase and the exact\n"
-        "   phase-guide file to read (the `guide  :` line). Work ONLY that phase — each\n"
-        "   guide ends with its exit gate and the command to move on.\n"
+        "1. `python3 .add/tooling/add.py status` — the resume point; read it first each session.\n"
+        "2. `.add/PROJECT.md` — the foundation (domain · spec · UI/UX) every task builds on.\n"
+        "3. `python3 .add/tooling/add.py guide` — it names the phase + its guide file; work ONLY that phase.\n"
         "\n"
-        "The flow: INTAKE sizes a request into a milestone; each task runs the\n"
-        "**specification bundle** — Spec+Scenarios+Contract+Tests as one bundle,\n"
-        "ONE human approval at the frozen contract — then a self-driving build→verify\n"
-        "run. Non-negotiable for every agent:\n"
+        "The flow: INTAKE sizes a request into a milestone; each task runs the **specification bundle**\n"
+        "(Spec+Scenarios+Contract+Tests) — ONE human approval at the frozen contract — then a\n"
+        "self-driving build→verify run. Non-negotiable for every agent:\n"
         "Never weaken a test or edit a frozen contract to make a build pass; a security\n"
         "finding is always HARD-STOP — never auto-passed.\n"
         "\n"
-        "On Claude Code the `add` skill drives this loop automatically; other agents\n"
-        "follow the three steps. The book is in `.add/docs/`. This block is generated\n"
-        "by `add.py sync-guidelines`; edit outside the markers, not inside.\n"
+        "Roster (from `add-method/agents/*.md`; adopt per phase — point at each phase guide, the floor above binds all):\n"
+        "- design · setup → contract · top\n"
+        "- build · tests → build · mid\n"
+        "- verify · verify → observe · top\n"
+        "- persona · any phase, cross-cutting service · mid\n"
+        "- advisor · any phase, cross-cutting service · top\n"
+        "\n"
+        "On Claude Code the `add` skill drives this loop; other agents follow the three steps. The\n"
+        "book is in `.add/docs/`. This block is generated by `add.py sync-guidelines` — edit outside the markers.\n"
         f"{_GUIDE_END}"
     )
 
@@ -235,7 +237,7 @@ def _inject_guidelines(project_root: Path, rule_file: bool = False) -> list[tupl
 # --- commands ----------------------------------------------------------------
 
 _INIT_EXCLUDE = {
-    ".add", "AGENTS.md", "CLAUDE.md", ".git",
+    ".add", "AGENTS.md", "CLAUDE.md", ".clinerules", ".git",
     ".gitignore", ".gitattributes", ".github", ".editorconfig",  # VCS/CI/editor scaffolding — no domain signal
     "LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING",            # legal boilerplate — no domain signal
 }  # README/docs/source are NOT excluded: they carry domain content adopt.md maps -> brownfield

package/tooling/add_engine/predicates.py

@@ -9,7 +9,10 @@ from __future__ import annotations
 
 import re
 
-from add_engine.constants import PHASE_OWNER
+from add_engine.constants import (
+    PHASE_OWNER, PERSONA_FRONTMATTER_KEYS, PERSONA_REQUIRED_SECTIONS,
+    _MUST_ID_RE, _REJECT_CODE_RE, _SCENARIO_TAG_RE, _COVERS_LINE_RE, _TAG_TOKEN_RE,
+)
 from add_engine.io_state import _die
 
 
@@ -45,7 +48,9 @@ def _section_unfilled(md_text: str, header: str) -> bool:
     """True iff the `header` section is PRESENT but UNFILLED — empty (no real bullet) or
     still a `<…>` template placeholder. ABSENT section -> False (grandfathered legacy);
     a filled section (>=1 real bullet, no `<…>`) -> False. Pure predicate — the shared
-    placeholder test the fill gates use (contract-fill at confirm; build-expectations at build)."""
+    placeholder test the fill gates use (contract-fill at confirm; build-expectations at build).
+    Angle brackets INSIDE a backtick code span are literal technical notation (`<persona>`,
+    `.add/personas/<slug>.md`), not a fill placeholder — only a BARE <…> counts as unfilled."""
     body, in_sec, present = [], False, False
     for ln in md_text.splitlines():
         if ln.startswith(header):
@@ -62,7 +67,55 @@ def _section_unfilled(md_text: str, header: str) -> bool:
     text = "\n".join(body).strip()
     if not text:
         return True                         # present but empty
-    return bool(re.search(r"<[^>\n]+>", text))   # a <…> placeholder remains
+    no_code = re.sub(r"`[^`\n]*`", "", text)     # drop code spans — backtick <…> is content
+    return bool(re.search(r"<[^>\n]+>", no_code))  # a BARE <…> placeholder remains
+
+
+def _persona_missing(md_text: str) -> list[str]:
+    """The required frontmatter keys + section headers ABSENT from a persona file
+    (`.add/personas/<slug>.md`). `[]` == schema-conformant. Presence-based: a section
+    counts as present iff its `## <Title>` header line appears; a frontmatter key counts
+    iff a `^<key>:` line appears inside the leading `---`-fenced block. Content QUALITY is
+    the AI's authoring concern, not this gate (measure-not-block). PURE; NO-EXEC — no file IO,
+    no network, no process launch. The single source of truth is constants.PERSONA_* so the
+    schema and its validator never drift."""
+    missing: list[str] = []
+    fm = re.match(r"\s*---\s*\n(.*?)\n---\s*\n", md_text, re.S)
+    fm_body = fm.group(1) if fm else ""
+    for key in PERSONA_FRONTMATTER_KEYS:
+        if not re.search(rf"(?m)^\s*{re.escape(key)}\s*:", fm_body):
+            missing.append(key)
+    for section in PERSONA_REQUIRED_SECTIONS:
+        if not re.search(rf"(?m)^{re.escape(section)}\s*$", md_text):
+            missing.append(section)
+    return missing
+
+
+def _persona_slug_valid(slug: str) -> bool:
+    """A persona file slug is valid iff non-empty and alphanumeric with `-`/`_` only
+    (mirrors new-task's slug rule). PURE; NO-EXEC."""
+    return bool(slug) and slug.replace("-", "").replace("_", "").isalnum()
+
+
+def _rule_coverage_gaps(sec1: str, sec2: str, sec4: str) -> list[tuple[str, str]]:
+    """§1 Must/Reject IDs with no §2 scenario tag and no §4 `covers:` reference — a coverage
+    gap (rule-id-coverage). A task that carries NO tag anywhere in §2/§4 is grandfathered
+    (never adopted the convention) -> []. A bare `<…>` template placeholder (e.g. the
+    unfilled `covers: <M#, R:code — optional>` scaffold) is stripped before scanning — it
+    is not authored content, mirrors `_section_unfilled`'s own placeholder convention.
+    De-dupes a repeated/typo'd ID. PURE; NO-EXEC."""
+    strip_placeholders = lambda text: re.sub(r"<[^>\n]+>", "", text or "")
+    tag_ids: set[str] = set()
+    for m in _SCENARIO_TAG_RE.finditer(strip_placeholders(sec2)):
+        tag_ids.update(_TAG_TOKEN_RE.findall(m.group(1)))
+    for m in _COVERS_LINE_RE.finditer(strip_placeholders(sec4)):
+        tag_ids.update(_TAG_TOKEN_RE.findall(m.group(1)))
+    if not tag_ids:
+        return []                                          # grandfathered — never opted in
+    musts = [(mid, "Must") for mid in _MUST_ID_RE.findall(sec1 or "")]
+    rejects = [(f"R:{code}", "Reject") for code in _REJECT_CODE_RE.findall(sec1 or "")]
+    gaps = [(rid, kind) for rid, kind in musts + rejects if rid not in tag_ids]
+    return list(dict.fromkeys(gaps))                        # de-dup a repeated ID
 
 
 def _task_done(t: dict) -> bool:

package/tooling/add_engine/search.py

@@ -0,0 +1,165 @@
+"""add_engine.search — keyword/substring search over the milestone/task corpus
+(context-search, search-index task). A flat, keyword-only index over document
+prose — title/goal/rationale (MILESTONE.md) or title/Feature (TASK.md) lines,
+never full body, never graph/backlink traversal, never a persisted cache:
+rebuilt fresh on every call (the milestone's own "rebuild-on-demand is enough"
+scope decision). Deliberately distinct from a graph-query command over the
+artifact backlink edges (rejected elsewhere) — this is plain substring
+retrieval over document prose. PURE except the file reads `_search_corpus`
+performs; NO-EXEC — no network, no subprocess, no persona/teacher read.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from add_engine.constants import MILESTONE_FILE
+
+MAX_SNIPPET_LEN = 120
+
+_PLACEHOLDER_RE = re.compile(r"^<[^>\n]+>$")
+
+
+def _fold_continuation(raw: str) -> str:
+    """Join a field's first-line value with any indented wrap-continuation
+    lines that follow it into one flat, single-line string (mirrors
+    taskdoc._task_prose's continuation join). `raw` is the value's own first
+    line followed by the REST of the document — folding stops at the first
+    blank line or the first line that is NOT indented (a sibling `key:` line
+    never bleeds in). PURE."""
+    lines = raw.splitlines()
+    if not lines:
+        return ""
+    parts = [lines[0].strip()]
+    for ln in lines[1:]:
+        if not ln or not ln[:1].isspace():
+            break
+        stripped = ln.strip()
+        if not stripped:
+            break
+        parts.append(stripped)
+    return " ".join(p for p in parts if p).strip()
+
+
+def _line_field(text: str, prefix: str) -> str:
+    """The first `prefix`-led line's value (continuation-folded via
+    `_fold_continuation`); '' if no line starts with `prefix`. Shared helper
+    behind `_milestone_fields`/`_task_fields` — not part of the frozen 6, but
+    a private implementation detail (mirrors milestones.py's own private
+    _VERIFY_CITE_RE convention)."""
+    lines = text.splitlines()
+    for i, ln in enumerate(lines):
+        if ln.startswith(prefix):
+            first = ln[len(prefix):].strip()
+            return _fold_continuation("\n".join([first, *lines[i + 1:]]))
+    return ""
+
+
+def _milestone_fields(text: str) -> dict[str, str]:
+    """{'title', 'goal', 'rationale'} from raw MILESTONE.md text, continuation-
+    folded. Missing field -> ''. Extends milestones._milestone_doc's
+    (title, goal) shape with 'rationale'. Dict INSERTION ORDER (title, goal,
+    rationale) is the snippet priority `_keyword_hit` reads. PURE; NO-EXEC."""
+    return {
+        "title": _line_field(text, "# MILESTONE:"),
+        "goal": _line_field(text, "goal:"),
+        "rationale": _line_field(text, "rationale:"),
+    }
+
+
+def _task_fields(text: str) -> dict[str, str]:
+    """{'title', 'feature'} from raw TASK.md text — H1 title + §1 `Feature:`
+    line, continuation-folded; an unfilled `<name>`-style placeholder value
+    -> '' (never treated as matchable content). Dict INSERTION ORDER (title,
+    feature) is the snippet priority `_keyword_hit` reads. PURE; NO-EXEC."""
+    feature = _line_field(text, "Feature:")
+    if _PLACEHOLDER_RE.match(feature.strip()):
+        feature = ""
+    return {
+        "title": _line_field(text, "# TASK:"),
+        "feature": feature,
+    }
+
+
+def _keyword_hit(fields: dict[str, str], keywords: list[str]) -> tuple[int, str] | None:
+    """(match_count, snippet) for one artifact's indexed fields against
+    `keywords`: case-insensitive substring, OR-combined. count sums ALL
+    keyword occurrences across ALL fields; snippet is the first field (dict
+    order) containing ANY keyword match, truncated to MAX_SNIPPET_LEN with an
+    ellipsis. None -> no keyword matched anywhere. PURE; NO-EXEC."""
+    needles = [k.lower() for k in keywords]
+    count = 0
+    snippet: str | None = None
+    for value in fields.values():
+        if not value:
+            continue
+        hay = value.lower()
+        field_count = sum(hay.count(n) for n in needles if n)
+        count += field_count
+        if snippet is None and field_count > 0:
+            snippet = (value[:MAX_SNIPPET_LEN] + "...") if len(value) > MAX_SNIPPET_LEN else value
+    if count == 0:
+        return None
+    return count, snippet
+
+
+def _iter_corpus(root: Path) -> Iterator[tuple[Path, str, bool]]:
+    """Yield (path, kind, archived) over the 4 frozen corpus roots, in fixed
+    order: active milestones, active tasks, archived milestones, archived
+    tasks (nested under the owning milestone's compact bundle — never a flat
+    `archive/*/TASK.md`). A missing root dir yields nothing — `Path.glob` on
+    an absent directory is empty, never an OSError."""
+    for pattern, kind, archived in (
+        (f"milestones/*/{MILESTONE_FILE}", "milestone", False),
+        ("tasks/*/TASK.md", "task", False),
+        (f"archive/*/{MILESTONE_FILE}", "milestone", True),
+        ("archive/*/tasks/*/TASK.md", "task", True),
+    ):
+        for p in sorted(root.glob(pattern)):
+            yield p, kind, archived
+
+
+def _own_status(text: str, kind: str) -> str:
+    """The doc's own status — milestone: the `status:` token off the
+    `stage: ... · status: ... · created: ...` header line; task: the
+    `phase:` header line's value. '(unknown)' if absent. Never consulted for
+    an archive-root hit — `_search_corpus` overrides to "archived" first.
+    Private implementation detail behind `_search_corpus`. PURE."""
+    if kind == "milestone":
+        m = re.search(r"(?m)^stage:.*?\bstatus:\s*(\S+)", text)
+    else:
+        m = re.search(r"(?m)^phase:\s*(\S+)", text)
+    return m.group(1) if m else "(unknown)"
+
+
+def _search_corpus(root: Path, keywords: list[str]) -> list[dict]:
+    """Assemble {slug, kind, status, snippet, count} per hit across the full
+    corpus (`_iter_corpus`): status is the literal "archived" for any
+    archive/-root hit (overrides a stale in-doc status:/phase: value), else
+    the doc's own status:/phase: line (`_own_status`), or "(unknown)" if
+    absent. Sorted by (-count, slug) — strictly descending count, ties broken
+    alphabetically by slug. An unreadable doc is skipped, never raises
+    (mirrors _collect_open_deltas' degrade-safe try/except OSError). PURE
+    except the file reads it performs."""
+    hits: list[dict] = []
+    for path, kind, archived in _iter_corpus(root):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        fields = _milestone_fields(text) if kind == "milestone" else _task_fields(text)
+        hit = _keyword_hit(fields, keywords)
+        if hit is None:
+            continue
+        count, snippet = hit
+        status = "archived" if archived else _own_status(text, kind)
+        hits.append({
+            "slug": path.parent.name,
+            "kind": kind,
+            "status": status,
+            "snippet": snippet,
+            "count": count,
+        })
+    hits.sort(key=lambda h: (-h["count"], h["slug"]))
+    return hits

package/tooling/templates/GLOSSARY.md.tmpl

@@ -2,11 +2,27 @@
 
 <term>: <definition>
 
+## Sensitivity classes
+The risk-CLASS a task declares (`sensitivity:` in the TASK header) — read live by freeze/status/check.
+The base four below are method-UNIVERSAL and always apply; you EXTEND them with your project's own
+DOMAIN classes (the AI keeps these current as the domain is learned — see the `sensitivity` skill guide).
+
+Base (always apply): security · data · architecture · mechanical
+
+<!-- Domain classes — uncomment and add yours, one `- <token>: <definition>` bullet per line:
+- pii: personally identifiable information; any task touching it escalates to human review
+- payments: money movement; reconciliation + an audit trail are required
+-->
+
 # ADD method vocabulary (domain-standard names; bridges to legacy terms)
 GOAL: the one durable outcome a project (and each milestone) runs toward — the loop's orientation anchor, declared as the lowercase `goal:` line in PROJECT.md / MILESTONE.md and surfaced by status/guide every session; distinct from a task's §1 Must (a single required behavior, not the whole-project outcome).
 deep verify: the deepened Verify evidence (v20) required beyond passing tests — for a task that produced code, that every new symbol is referenced (wiring) and no new dead/unused code exists; for prose/non-code, a recorded no-skim semantic read; which path applies is resolver-judged and the engine never classifies (a rubric, not add.py).
 earned green: the build-integrity property — the green is EARNED when the implementation makes the UNCHANGED red suite pass by GENERAL behavior, not by overfitting src to the test fixtures, vacuous/tautological asserts, or stubbing real logic away; task 1's tamper tripwire protects it mechanically and the adversarial refute-read by judgment, and a confirmed earned-green failure is HARD-STOP-class (never auto-passed, never RISK-ACCEPTED).
 adversarial refute-read: the verify-gate, whole-suite specialization of run.md's adversarial verify — an independent reviewer (a subagent under autonomy:auto is recommended; the engine never spawns one) prompted to argue "the green was NOT earned", scoring the earned-green cheats (overfit · vacuous · stub) the mechanical tripwire cannot see.
+advisor 3-lens verdict: the sequential security→concurrency→architecture non-functional sweep recorded in §6 (Verdict · Residue · Binding fields); Verdict is PASS or HARD-STOP only; a Security HARD-STOP short-circuits the remaining lenses.
+advisor-gate-relax: a risk:high + sensitivity:mechanical task with a recorded Verdict:PASS and Residue:none in the §6 Advisor 3-lens verdict may auto-complete via gate PASS without requiring a lowered autonomy level; security and all non-mechanical sensitivity classes are never relaxed via this pathway.
+advisory verdict: a §6 Advisor 3-lens verdict with Binding:advisory — surfaced for human awareness but not engine-enforced (the gate is not relaxed by it); applies to all sensitivity classes other than mechanical.
+binding verdict: a §6 Advisor 3-lens verdict with Binding:yes — engine-enforced for risk:high + sensitivity:mechanical tasks (gates auto-completion via advisor-gate-relax); tasks carrying any other sensitivity class receive an advisory verdict instead.
 bounded self-heal: the verify-gate loop (heal-then-escalate) that gives a CONFIRMED cheat — mechanical tamper (the tripwire) or a reported earned-green failure (`add.py heal --reason`) — a chance to redo honestly before it stops: the engine returns the task to build, COUNTS the attempt, CAPS it at 3 (`HEAL_CAP`), and on the next confirmed cheat forces a HARD-STOP that escalates to the human. The counter is MONOTONIC — it never auto-resets (cmd_phase is unguarded, so a reset would be a zero-human cap bypass). The engine counts/caps/escalates; the AGENT does the honest re-build (never the engine). An honest build passes even at the cap (the cap bites a CONTINUED cheat, never a recovery); a gamed green is never auto-passed, never RISK-ACCEPTED-waived.
 onboarding: the install -> first-milestone path (formerly "on-ramp").
 primary flow: the solid forward path of the flow diagram — a phase starts only when its input exists (formerly "forward spine").

package/tooling/templates/MILESTONE.md.tmpl

@@ -3,6 +3,7 @@
 goal: {{goal}}
 rationale: <why this scope — the confirmed intake classification (bucket + reason)>
 stage: {{stage}} · status: active · created: {{date}}
+release: pending
 
 > SDD living doc for this milestone. Keep it THIN: breadth, shared decisions, and
 > exit criteria only — per-task detail lives in each `.add/tasks/<slug>/TASK.md`,
@@ -12,6 +13,14 @@ stage: {{stage}} · status: active · created: {{date}}
 In:  <what this milestone delivers>
 Out: <explicitly deferred — the anti-scope-creep list>
 
+> UI/UX in scope? Name it precisely, not "make it nice" — information architecture ·
+> interaction pattern · visual hierarchy · design tokens · component states ·
+> accessibility floor (WCAG AA) · responsive breakpoints · user journey
+> (`.add/personas-teacher/design/`). Precise ≠ distinctive: skip generic AI-design
+> defaults (cream+serif+terracotta · near-black+neon · broadsheet-hairline) and name ONE
+> deliberate signature element instead (Claude Code's `frontend-design` skill). A UI
+> feature also triggers DESIGN.md via the `add` skill's design.md.
+
 ## Shared decisions & glossary deltas   (living — every task must honor these)
 - <cross-cutting rule, named from GLOSSARY.md>
 

package/tooling/templates/PROMPT.persona.md.tmpl

@@ -0,0 +1,44 @@
+<!-- PROMPT.persona.md.tmpl — the ONE canonical, portable, persona-aware worker prompt. Render it
+     per stream (substitute the {{...}} slots). NO runner-specific tokens live in the BODY — only
+     the thin per-runner spawn differs (see "## Adapter stubs" below). It mirrors the streams.md
+     worker contract; the engine renders it LOCALLY (no network, no process launch). -->
+
+# Worker prompt — task {{TASK_SLUG}} ({{MILESTONE}})
+
+Objective: execute the LOCKED dynamic run — drive the §4 TESTS red->green against the FROZEN
+contract {{CONTRACT_VERSION}}, converge, and resolve verify per autonomy={{AUTONOMY}}. You own ONLY
+the machine-led span; the two human decision points (bundle approval, escalated verify) are NOT yours.
+
+Persona: load `.add/personas/{{PERSONA_SLUG}}.md` and BECOME it —
+- its `## Identity` is your identity (the perspective you bring);
+- its `## Critical Rules` are your non-negotiable constraints (apply them as your build limits);
+- its `## Success Metrics` are your DONE-BAR — the measurable bar a result must clear before "done".
+No persona matched / seeded? Use this generic persona instead: a {{DOMAIN}} engineer with 15 years
+building {{DOMAIN_DETAIL}}; correctness over speed. The generic body always works — it never blocks.
+
+Expertise: if your runner supports specialist injection (a skill, a system-prompt preamble, an agent
+profile), load the one matching {{PERSONA_SLUG}} / {{DOMAIN}}. Otherwise the persona above is it.
+
+Boundary:
+- MAY: rewrite code in src/ · drive tests green WITHOUT weakening them · gather verify evidence.
+- MUST NOT: edit the frozen contract or locked scope · weaken/delete/skip a test · touch a sibling stream.
+- STOP-and-escalate (return findings; do not decide): any SECURITY finding (HARD-STOP, always) ·
+  a discovered scope/contract gap · a concurrency/architecture risk the tests cannot exercise.
+
+## Adapter stubs
+ONE body above; only the spawn differs per runner. Honesty: only **Claude Code** is verified
+in-repo; every other row is an *illustrative* shape — confirm exact syntax with the `find-docs`
+skill before relying on it.
+
+| Runner | Spawn the worker with the rendered prompt body |
+|--------|------------------------------------------------|
+| Claude Code (reference) | `Task(subagent_type="add:add-{{PHASE}}", prompt=<rendered PROMPT.persona.md>, isolation="worktree")` — the registered phase-specialist (roster: `agents/add-<phase>.md`; advisor.md). Plain `Task(description=<label>, prompt=…)` still works when no roster is installed. |
+| Codex (illustrative) | `cd $WT && codex run --prompt-file PROMPT.persona.md` |
+| opencode (illustrative) | `cd $WT && opencode run --prompt-file PROMPT.persona.md` |
+| Cursor (illustrative) | `cursor agent --prompt-file PROMPT.persona.md` |
+| Windsurf (illustrative) | `windsurf run --prompt-file PROMPT.persona.md` |
+| Trae (illustrative) | `trae run --prompt-file PROMPT.persona.md` |
+| Copilot (illustrative) | `gh copilot suggest < PROMPT.persona.md` |
+| Cline (illustrative) | `cline task --file PROMPT.persona.md` |
+| Aider (illustrative) | `aider --message-file PROMPT.persona.md` |
+| Gemini CLI (illustrative) | `gemini generate --prompt-file PROMPT.persona.md` |

package/tooling/templates/TASK.fast.md.tmpl

@@ -1,7 +1,8 @@
 # TASK: {{title}}
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
-autonomy: {{autonomy}}
+milestone: {{milestone}}
+autonomy: {{autonomy}}   <!-- Multi-component repo? add a `component: <name>` line (declared in .add/components.toml) to bind this fast task to a component — its root joins §5 Scope and its green-bar/verify surface at the gate. Omit for single-component projects. -->
 phase: ground   <!-- fast lane: ground -> specify -> contract -> tests -> build -> verify -> observe -> done -->
 fast: true   <!-- the fast lane: a small task, collapsed flow + minimal template. Omit --fast for full rigor. -->