@pilotspace/add 1.17.0 → 2.1.0

package/tooling/add_engine/io_state.py

@@ -117,17 +117,32 @@ def _atomic_write_many(writes: list[tuple[Path, str]]) -> None:
 # --- root finding + state load/save + the shared error primitive ------------
 
 def find_root(start: Path | None = None) -> Path | None:
-    """Walk up from cwd to find a .add/ project root."""
+    """Walk up from cwd to find a .add/ project root.
+
+    Opt-in boundary: when `ADD_ROOT_CEILING` is set, the walk stops at that dir
+    (inclusive) and never ascends above it — so a workspace nested under an
+    ancestor project resolves ONLY its own root (or None before init), never the
+    parent's. Unset (every normal invocation) is the legacy walk to fs-root,
+    byte-identical. Both paths are resolved so a symlinked ceiling still matches.
+    """
     cur = (start or Path.cwd()).resolve()
+    _ceil = os.environ.get("ADD_ROOT_CEILING")
+    ceil = Path(_ceil).resolve() if _ceil else None
     for d in (cur, *cur.parents):
         if (d / ROOT_DIRNAME / STATE_FILE).exists():
             return d / ROOT_DIRNAME
+        if ceil is not None and d == ceil:
+            break
     return None
 
 def _require_root() -> Path:
     root = find_root()
     if root is None:
-        _die("no .add/ project found. Run `add.py init` first.")
+        # skip-error-ergonomics M2: hand the exact command with its flags — the
+        # bare "run init first" hint made every fresh headless agent read
+        # `init --help` before its first real call (LOOP-2 re-measure, all reps).
+        _die('no .add/ project found — run: add.py init --name "<project>" '
+             "--stage <prototype|poc|mvp|production>")
     return root
 
 def _migrate_state(state: dict) -> dict:
@@ -170,8 +185,60 @@ def _state_text_or_die(root: Path) -> str:
              f"`git checkout --ours/--theirs {STATE_FILE}`), then run `add.py doctor` to verify")
     return text
 
+# kickoff-truth M3 (contract v2): the dup-failure short-circuit. The 2026-07-13
+# transcript audit measured 12-21% of all engine calls as byte-identical repeats of
+# a call that had just failed the same way — the agent re-issues the command
+# unchanged instead of reading the error. The sig sidecar lives OUTSIDE the project
+# tree (OS tmp dir, keyed by md5(root path)): the engine's reject-writes-nothing
+# floor pins that a REJECTED command leaves the .add tree byte-identical, so the
+# hint state is ephemeral per-project cache, never a tree write. add.main()
+# registers each invocation and clears the sidecar on any successful exit, so only
+# CONSECUTIVE identical failures short-circuit. Fail-open everywhere: no root /
+# unreadable sidecar / any OSError -> no hint, never a block — a hint helper must
+# never change an error's outcome.
+_INVOCATION: list[str] | None = None    # set by add.main() per dispatch
+
+def _register_invocation(argv: list[str]) -> None:
+    global _INVOCATION
+    _INVOCATION = list(argv)
+
+def _last_fail_path() -> Path | None:
+    root = find_root()
+    if root is None:
+        return None
+    key = hashlib.md5(str(root.resolve()).encode("utf-8")).hexdigest()[:12]
+    return Path(tempfile.gettempdir()) / f"add-last-fail-{key}.json"
+
+def _clear_last_fail() -> None:
+    try:
+        side = _last_fail_path()
+        if side is not None:
+            side.unlink(missing_ok=True)
+    except OSError:
+        pass                            # hygiene only — success must never fail on it
+
+def _dup_fail_hint(msg: str) -> str | None:
+    try:
+        side = _last_fail_path()
+        if side is None:
+            return None
+        argv = _INVOCATION if _INVOCATION is not None else sys.argv[1:]
+        code_head = msg.split(":", 1)[0].strip()
+        sig = hashlib.md5((" ".join(argv) + "\n" + code_head).encode("utf-8")).hexdigest()
+        hint = None
+        if side.exists() and json.loads(side.read_text(encoding="utf-8")).get("sig") == sig:
+            hint = ("hint: this exact call already failed with the same error — change "
+                    "the command or input before retrying (add.py status shows the true state)")
+        side.write_text(json.dumps({"sig": sig}), encoding="utf-8")
+        return hint
+    except (OSError, ValueError):
+        return None
+
 def _die(msg: str, code: int = 1) -> None:
+    hint = _dup_fail_hint(msg)          # kickoff-truth M3 — fail-open, never raises
     print(f"add: error: {msg}", file=sys.stderr)
+    if hint:
+        print(hint, file=sys.stderr)
     raise SystemExit(code)
 
 
@@ -203,9 +270,9 @@ def _md5_file(p: Path) -> str | None:
 
 def _personas_unseeded(root: Path) -> bool:
     """True when `.add/personas/` has no REAL (non-template) authored persona: the
-    directory is absent, empty, or holds only the seeded `_template.md` scaffold
-    (persona-seed-nudge). Fail-soft: an unreadable directory counts as unseeded
-    rather than raising — this feeds a `note:`/INFO hint, never a gate."""
+    directory is absent, empty, or holds only a `_template.md` scaffold (personas are
+    authored via the persona-author skill, not seeded). Fail-soft: an unreadable directory
+    counts as unseeded rather than raising — this feeds a `note:`/INFO hint, never a gate."""
     d = root / "personas"
     if not d.is_dir():
         return True

package/tooling/add_engine/predicates.py

@@ -10,7 +10,8 @@ from __future__ import annotations
 import re
 
 from add_engine.constants import (
-    PHASE_OWNER, PERSONA_FRONTMATTER_KEYS, PERSONA_REQUIRED_SECTIONS,
+    PHASE_OWNER, PHASE_GROUPS, PERSONA_FLOW_VALUES, PERSONA_FRONTMATTER_KEYS, PERSONA_REQUIRED_SECTIONS,
+    TASK_KINDS,
     _MUST_ID_RE, _REJECT_CODE_RE, _SCENARIO_TAG_RE, _COVERS_LINE_RE, _TAG_TOKEN_RE,
 )
 from add_engine.io_state import _die
@@ -23,6 +24,59 @@ def _phase_owner(phase: str) -> str:
         _die("unmapped_phase")
     return owner
 
+def _phase_bundle(phase: str) -> str | None:
+    """Map a phase to its PHASE_GROUPS bundle name (DIRECTION|BUILD|VERIFY); `None` for
+    the terminal "done" phase (a deliberate, documented non-crash — done is a human-led
+    terminal state, not work any of the three roster agents drive); `_die
+    ("unmapped_phase_bundle")` for any other token absent from PHASE_GROUPS (fail closed,
+    mirrors `_phase_owner`'s exact idiom)."""
+    if phase == "done":
+        return None
+    for bundle, phases in PHASE_GROUPS.items():
+        if phase in phases:
+            return bundle
+    _die("unmapped_phase_bundle")
+
+def _ai_freeze_allowed(gate_mode: str | None, sensitivity: str | None, autonomy: str) -> tuple[bool, str | None]:
+    """The ai-plan-verify-gate predicate: may an AI agent perform the §3 contract freeze in
+    place of a human? PURE, fail-closed. A BLOCK-list (not an allow-list of one, human freeze
+    decision 2026-07-09): the human floor is exactly {security, data, architecture} plus a
+    malformed "?" token; undeclared sensitivity (None), the literal "mechanical" token, and any
+    other valid project-GLOSSARY class all qualify — the double opt-in (gate_mode: ai-plan-verify
+    AND autonomy: auto, both human-declared) IS the sign-off. Sibling of advisor-gate-relax (a
+    DIFFERENT, narrower allow-list-of-"mechanical" floor at the VERIFY/completion boundary) —
+    related but not identical floors, never interchangeable."""
+    if gate_mode != "ai-plan-verify":
+        return False, "ai_freeze_not_opted_in"
+    if autonomy != "auto":
+        return False, "ai_freeze_requires_auto"
+    if sensitivity in ("security", "data", "architecture"):
+        return False, "ai_freeze_blocked_sensitivity"
+    if sensitivity == "?":
+        return False, "ai_freeze_unknown_sensitivity"
+    return True, None
+
+
+def _skip_lane_eligible(fast: bool, oneshot: bool, benchmark_mode: bool) -> bool:
+    """fast-lane-skips: may a task declare a scenarios/observe skip at all? PURE. True iff
+    ANY of the three independent triggers MILESTONE.md Scope(3) names is set — the existing
+    fast lane, the new --oneshot flag, or a project-wide benchmark_mode:true opt-in. Does not
+    itself validate the declared token set (see _skip_set_allowed) — single responsibility."""
+    return fast or oneshot or benchmark_mode
+
+
+def _skip_set_allowed(skip_tokens: frozenset[str], eligible: bool) -> tuple[bool, str | None]:
+    """fast-lane-skips: may THIS declared (already closed-set-validated) skip-set be honored?
+    PURE, fail-closed. `skip_tokens` is assumed already validated by _task_skip_set — this
+    predicate's single responsibility is the LANE-ELIGIBILITY axis, not set-membership (two
+    distinct error codes for two distinct failure shapes, mirrors _ai_freeze_allowed's split
+    from _task_gate_mode). An EMPTY skip-set is always permitted (nothing declared, nothing to
+    gate) regardless of eligibility."""
+    if skip_tokens and not eligible:
+        return False, "skip_lane_required"
+    return True, None
+
+
 def _setup_locked(state: dict) -> bool:
     """True when the project's setup is locked — i.e. the build-boundary gate is OPEN.
 
@@ -48,7 +102,7 @@ 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 contract-fill gate uses at confirm.
     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
@@ -91,6 +145,40 @@ def _persona_missing(md_text: str) -> list[str]:
     return missing
 
 
+def _persona_quality_warnings(md_text: str) -> list[str]:
+    """Quality findings the presence-based schema check can't see (persona-schema-hardening).
+    `[]` == clean. WARN-only at the caller (measure-not-block); never a gate. Two findings:
+    (A) a `flow:` frontmatter value outside PERSONA_FLOW_VALUES — no apply-surface loads an
+    unknown flow, so a typo otherwise fails silently; an ABSENT `flow:` line is conformant
+    (that is `_persona_missing` territory, and flow is only RECOMMENDED). (B) a bare `<…>`
+    placeholder outside backtick code spans and HTML comments — a half-filled template copy
+    passes the presence check. PURE; NO-EXEC — text in, list of strings out."""
+    findings: list[str] = []
+    fm = re.match(r"\s*---\s*\n(.*?)\n---\s*\n", md_text, re.S)
+    fm_body = fm.group(1) if fm else ""
+    m = re.search(r"(?m)^\s*flow\s*:\s*(.+)$", fm_body)
+    if m:
+        for v in (tok.strip() for tok in m.group(1).split(",")):
+            if v and v not in PERSONA_FLOW_VALUES:
+                findings.append(f"flow value '{v}' not one of " + "|".join(PERSONA_FLOW_VALUES))
+    # (C) persona-task-kinds: a `task-kinds:` value outside the closed taxonomy scores as
+    # NOTHING on the persona scoreboard (the trace join key never matches), so a typo would
+    # otherwise fail silently — same shape as Finding A; an ABSENT line is conformant.
+    m = re.search(r"(?m)^\s*task-kinds\s*:\s*(.+)$", fm_body)
+    if m:
+        for v in (tok.strip() for tok in m.group(1).split(",")):
+            if v and v not in TASK_KINDS:
+                findings.append(f"task-kinds value '{v}' not one of " + "|".join(TASK_KINDS))
+    # strip comments FIRST (a backtick inside a comment is already gone), then ```-fenced
+    # blocks (a Playbook skeleton legitimately carries <placeholder> lines), then inline spans
+    no_comments = re.sub(r"<!--.*?-->", "", md_text, flags=re.S)
+    no_fences = re.sub(r"(?ms)^```.*?^```\s*$", "", no_comments)
+    no_code = re.sub(r"`[^`\n]*`", "", no_fences)
+    for ph in re.findall(r"<[^>\n]+>", no_code):
+        findings.append(f"bare <…> placeholder remains: '{ph[:40]}'")
+    return findings
+
+
 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."""

package/tooling/add_engine/search.py

@@ -1,6 +1,6 @@
 """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,
+prose — title/goal/rationale (MILESTONE.md) or title/Feature (PLAN.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
@@ -69,7 +69,7 @@ def _milestone_fields(text: str) -> dict[str, str]:
 
 
 def _task_fields(text: str) -> dict[str, str]:
-    """{'title', 'feature'} from raw TASK.md text — H1 title + §1 `Feature:`
+    """{'title', 'feature'} from raw PLAN.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."""
@@ -77,7 +77,7 @@ def _task_fields(text: str) -> dict[str, str]:
     if _PLACEHOLDER_RE.match(feature.strip()):
         feature = ""
     return {
-        "title": _line_field(text, "# TASK:"),
+        "title": _line_field(text, "# PLAN:"),
         "feature": feature,
     }
 
@@ -108,13 +108,13 @@ 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
+    `archive/*/PLAN.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),
+        ("tasks/*/PLAN.md", "task", False),
         (f"archive/*/{MILESTONE_FILE}", "milestone", True),
-        ("archive/*/tasks/*/TASK.md", "task", True),
+        ("archive/*/tasks/*/PLAN.md", "task", True),
     ):
         for p in sorted(root.glob(pattern)):
             yield p, kind, archived

package/tooling/add_engine/taskdoc.py

@@ -1,4 +1,4 @@
-"""add_engine.taskdoc — TASK.md structural readers (engine-modularization 15/N).
+"""add_engine.taskdoc — PLAN.md structural readers (engine-modularization 15/N).
 
 Header, prose, test-count, phase-span, raw phase bodies, and the §7 spec-delta entries —
 the pure parsers that read a task document's shape. A closed, unpatched cluster
@@ -14,12 +14,17 @@ from pathlib import Path
 from add_engine.constants import _DELTA_RE, _EVIDENCE_RE, _SPEC_DELTA_RE
 from add_engine.components import _confined
 
+# The ONE canonical §-heading scanner (`^##\s*<n>\s*·`). Static pattern hoisted to
+# module load — _phase_spans is on the busiest task-doc read path (check/status/gate),
+# so it never re-compiles per call. Behaviour byte-identical.
+_HEADING_RE = re.compile(r"^##\s*(\d+)\s*·")
+
 
 def _task_header(root: Path, slug: str) -> str:
-    """The TASK.md header region — where declared tokens (risk · autonomy)
+    """The PLAN.md header region — where declared tokens (risk · autonomy)
     live — with HTML comments stripped. Missing file -> '' (no tokens)."""
     try:
-        text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+        text = (root / "tasks" / slug / "PLAN.md").read_text(encoding="utf-8")
     except OSError:
         return ""
     return re.sub(r"<!--.*?-->", "", text.split("\n## ", 1)[0], flags=re.S)
@@ -97,11 +102,11 @@ def _tests_info(root: Path, slug: str) -> tuple[int, bool]:
     return (declared, True) if declared > 0 else (0, False)
 
 def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
-    """(observe_delta, [delta lines]) from the task's TASK.md §7 — captured at FULL
+    """(observe_delta, [delta lines]) from the task's PLAN.md §7 — captured at FULL
     fidelity: both fields wrap across physical lines in real files, so continuation
     lines are JOINED. Scoped to the OBSERVE section so we read the FIELD, not §1 prose
     that names it. Fail-closed to '(unknown)' on a missing file / `<...>` placeholder."""
-    f = root / "tasks" / slug / "TASK.md"
+    f = root / "tasks" / slug / "PLAN.md"
     if not f.exists():
         return "(unknown)", []
     text = f.read_text(encoding="utf-8")
@@ -157,14 +162,14 @@ def _task_prose(root: Path, slug: str) -> tuple[str, list[str]]:
     return observe, deltas
 
 def _phase_spans(text: str) -> dict[int, str]:
-    """Split a TASK.md into RAW §1–§7 bodies keyed by section number — the ONE
+    """Split a PLAN.md into RAW §1–§7 bodies keyed by section number — the ONE
     canonical heading scan (`^##\\s*<n>\\s*·`, case/locale-proof); a body runs from
     its heading to the next `## `/`---`/EOF. RAW = byte-faithful lines, no cleaning:
     the decision-marker extractor (decide-digest) depends on byte-verbatim text.
     KNOWN LIMIT: a §body containing a line-start `## ` or bare `---` truncates early —
-    today's TASK.md bodies don't (box-chars ─═, `### ` sub-heads)."""
+    today's PLAN.md bodies don't (box-chars ─═, `### ` sub-heads)."""
     lines = text.splitlines()
-    head = re.compile(r"^##\s*(\d+)\s*·")
+    head = _HEADING_RE
     starts: dict[int, int] = {}
     for idx, ln in enumerate(lines):
         m = head.match(ln)
@@ -184,8 +189,8 @@ def _phase_spans(text: str) -> dict[int, str]:
 
 def _raw_phase_bodies(root: Path, slug: str) -> dict[int, str]:
     """RAW §bodies for one task (byte-faithful, for marker extraction). PURE.
-    Missing/unreadable TASK.md -> {} (fail-closed, like task_phases)."""
-    f = root / "tasks" / slug / "TASK.md"
+    Missing/unreadable PLAN.md -> {} (fail-closed, like task_phases)."""
+    f = root / "tasks" / slug / "PLAN.md"
     try:
         return _phase_spans(f.read_text(encoding="utf-8"))
     except OSError:

package/tooling/templates/CONVENTIONS.md.tmpl

@@ -1,7 +1,7 @@
 # CONVENTIONS  (living documentation — set once, kept for the whole project)
 
 Language/framework: <e.g. Python 3.12 / FastAPI>
-Folders: .add/tasks/<slug>/{TASK.md, tests/, src/}
+Folders: .add/tasks/<slug>/{PLAN.md, tests/, src/}
 Naming: <file case>, <type case>, verbs for functions
 Lint/format: <tools>, enforced in CI
 Errors: machine-readable error codes (string enums), never free text

package/tooling/templates/GLOSSARY.md.tmpl

@@ -9,6 +9,9 @@ DOMAIN classes (the AI keeps these current as the domain is learned — see the
 
 Base (always apply): security · data · architecture · mechanical
 
+Datetime, money, or timezone arithmetic ⇒ declare `data` (full lane) — value formats are the
+risk surface (a naive-timestamp suite stays green through an aware-timestamp crash: bench wm2).
+
 <!-- 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
@@ -36,7 +39,7 @@ failing-first suite: the test suite written before code, confirmed red for the r
 non-functional review: the deliberate post-evidence check of what tests rarely catch — concurrency, security, architecture (formerly "blind-spot checks").
 change scope: the files a locked run may and may not touch (formerly "touch-boundary"; the <touch_boundary> XML prompt tag keeps its name).
 automated quality gate: the evidence-based Verify resolver under autonomy auto — may auto-PASS on complete evidence; security always escalates (formerly "evidence auto-gate").
-autonomy level: the explicit per-task Verify resolver setting on an ordered ladder — manual | conservative | auto (manual < conservative < auto): auto (the seeded default) auto-PASSes on complete evidence, conservative keeps a human at the gate, manual is the strict floor (the human owns the gate; nothing auto-resolves); declared in the TASK.md header, human-reviewed at the freeze (formerly "autonomy dial").
+autonomy level: the explicit per-task Verify resolver setting on an ordered ladder — manual | conservative | auto (manual < conservative < auto): auto (the seeded default) auto-PASSes on complete evidence, conservative keeps a human at the gate, manual is the strict floor (the human owns the gate; nothing auto-resolves); declared in the PLAN.md header, human-reviewed at the freeze (formerly "autonomy dial").
 auto-ready goal: a milestone goal whose every exit criterion CITES a verifier `(verify: <test|command|metric>)` — so the engine can self-verify the result against the goal without human judgement. This is the prerequisite by which autonomy is EARNED by goal-clarity (the autonomy level then governs who resolves Verify, but a clarified goal is what makes a self-verifying run meaningful). `add.py check` WARNs (never red) the active milestone until its goal is auto-ready (total >= 1 AND every criterion cited) and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal is NOT auto-ready and is milestone-shaping's nudge, not this WARN's. The lint forces a citation slot per criterion (raising the floor) but cannot PROVE the citation is real — the human still owns whether it is honest (citation-theater is the accepted, irreducible floor; the freeze gate and autonomy behavior are unchanged by it).
 living documentation: the durable project artifacts — conventions, glossary, frozen contracts — that outlive any particular code (formerly "survivor layer").
 scope level: the granularity a decision lives at — intake level (request -> versioned scope), milestone level, setup/foundation level, task level (formerly "altitude").
@@ -44,11 +47,14 @@ baseline approval: the one human gate that freezes the AI-drafted foundation, fi
 lesson learned: a single learning a loop produces, tagged by the competency it improves — the `- [DDD · open]` grammar and deltas.md/`add.py deltas` machine names stay (formerly "competency delta").
 lowest-confidence flag: the AI's ranked declaration of the 1–2 points most likely to be wrong in what a human is asked to approve — each with why + cost-if-wrong; the ⚠ glyph keeps its name as the machine marker (formerly "least-sure flag").
 decision point: a stop for human judgment — the contract-freeze approval, an escalated verify gate, intake confirmation, milestone close; the machine names seam (--json owner enum, decide key) and seam-audit (CI job) keep their names (formerly "seam").
-retrospective consolidation: gathering confirmed lessons learned at milestone close and writing them append-only into the versioned foundation — human-confirmed, never self-approved; the machine names fold.md, the folded status, and add.py deltas keep their names (formerly "the fold / fold ritual").
+depends-on: a DECLARED, BLOCKING relation — a task/milestone that must be DONE before this one starts; drives the wave schedule (the only relation the scheduler reads). Declared via `new-task --depends-on` (task) or a MILESTONE.md header `depends-on:` line (milestone).
+extends: a DECLARED, NON-BLOCKING relation — this task/milestone builds on a prior one's shipped surface; a legibility edge, never gates the schedule. Declared via `new-task --extends` (task) or a MILESTONE.md header `extends:` line (milestone).
+relates-to: a DECLARED, NON-BLOCKING relation — this task/milestone shares context with another (informational); never gates the schedule. Declared via `new-task --relates-to` (task) or a MILESTONE.md header `relates-to:` line. All three relations are validated (dangling/self) by `add.py check` + `status`, never inferred.
+retrospective consolidation: lessons learned land in-flight in the living specs (`add.py delta-append`); the human confirms what binds — never self-approved; the `folded` status and `add.py deltas` keep their names (formerly "the fold / fold ritual").
 specification bundle: a task's spec, scenarios, contract, and failing tests drafted as one piece and approved by a person once at the contract freeze (formerly "the one-approval front").
-foundation compaction: the retrospective shrink — collapse a foundation spec's stable, shipped, zero-residue tail into one rolled-up settled line; the AI proposes and the human confirms; summarize and point, never delete; a SEPARATE step from the retrospective consolidation; distinct from the engine `add.py compact` (which archives finished-milestone files).
+foundation compaction: the retrospective shrink — collapse a living spec's stable, shipped, zero-residue tail into one rolled-up settled line; the AI proposes and the human confirms; summarize and point, never delete.
 rolled-up settled line: the single line left when a stable run is collapsed — lossy on prose, lossless on traceability (carries a `see git` pointer).
 per-spec shape: each foundation spec's own tailored rolled-line format (PROJECT §Spec bullets · §Key-Decisions rows · CONVENTIONS learnings · GLOSSARY definition · MODEL_REGISTRY rows), all sharing one eligibility rule: shipped + zero open residues.
 newest-first append-only: every append-only foundation sequence prepends the newest record at the top; the rolled-up settled line anchors at the bottom (the oldest end), so compaction collapses upward.
 ship review: the whole-milestone, cross-task evidence the AI fills at milestone close (ship-by-domain · cross-task evidence · goal-met map), read before the exit-criteria boxes are checked — evidence, not a new gate; the ritual lives in the `add` skill's loop.md.
-release steps: the AI-defined, per-milestone ordered hints to ship a closed milestone, merge being one small step (a PR · an exported hand-off doc · a tag or publish are others); defined at close and fed into the release scope (release.md), never a second flow.
+release steps: the AI-defined, per-milestone ordered hints to ship a closed milestone, merge being one small step (a PR · an exported hand-off doc · a tag or publish are others); defined at close; the human runs the cut, never a second flow.

package/tooling/templates/MILESTONE.md.tmpl

@@ -3,23 +3,29 @@
 goal: {{goal}}
 rationale: <why this scope — the confirmed intake classification (bucket + reason)>
 stage: {{stage}} · status: active · created: {{date}}
-release: pending
+relations: <cross-MILESTONE edges — `depends-on:` / `extends:` / `relates-to:` header lines, comma-sep slugs; omit if none; `add.py check` validates>
 
 > 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`,
+> exit criteria only — per-task detail lives in each `.add/tasks/<slug>/PLAN.md`,
 > written just-in-time. Update this doc whenever a task reveals a milestone gap.
 
 ## Scope
 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.
+> UI/UX in scope? Name it precisely, not "make it nice" — IA · interaction pattern ·
+> visual hierarchy · tokens · component states · WCAG AA · breakpoints · user journey.
+> Skip generic AI-design defaults; name ONE deliberate signature element. A UI feature
+> also triggers DESIGN.md via the `add` skill's design.md.
+
+## Ground   (shared real-code context — gathered ONCE; every task's specify projects from this)
+Touches (shared files · symbols): <the code every task in this milestone lands in — gathered once, task-delta>
+Anchors: <the shared symbols tasks may cite — the floor each task's contract builds on>
+Honors (conventions): <PROJECT.md · CONVENTIONS.md · SEAMS.md rules every task honors>
+Issues/Risks (shared): <traps in the shared code that feed each task's §1 expectations>
+
+> Gathered ONCE per milestone (`scope.md`); each task's specify PROJECTS its §1 from
+> here + the specific request — light, never re-grounded per task.
 
 ## Shared decisions & glossary deltas   (living — every task must honor these)
 - <cross-cutting rule, named from GLOSSARY.md>
@@ -27,16 +33,15 @@ Out: <explicitly deferred — the anti-scope-creep list>
 ## Shared / risky contracts (freeze these first)
 - <contract name> -> owning task <slug>
 
-## Tasks (breadth-first decomposition; detail lives in each TASK.md)
+## Tasks (breadth-first decomposition; detail lives in each PLAN.md)
 - [ ] <slug>   depends-on: none     — <one line>
 - [ ] <slug>   depends-on: <slug>   — <one line>
 
 ## Exit criteria (observable; map each to the task that delivers it)
-- [ ] User can <observable behavior>        (← <slug>)
+- [ ] User can <observable behavior — the SEEN outcome only, NOT the task's plan line>        (← <slug>)
 
 ## Close — ship review   (AI fills when every task is done — the evidence behind the engine gate, read before the boxes are checked)
-> Whole-milestone, cross-task review the AI fills in. It is the evidence behind the EXISTING engine
-> gate (milestone-done / checking the Exit-criteria boxes) — NOT a new approval. Tool-agnostic.
+> Cross-task review the AI fills — the evidence behind the EXISTING milestone-done gate, NOT a new approval.
 
 ### Ship by domain   (what changed, per bounded context)
 - tooling : <add.py / state.json / templates — what shipped, or "untouched">
@@ -51,8 +56,7 @@ Out: <explicitly deferred — the anti-scope-creep list>
 - goal: <restate the milestone goal — and the one evidence line that proves the ship meets it>
 
 ## Release steps   (AI-DEFINED — fill the ordered steps to ship this milestone; engine records, human gate)
-> The AI writes the release steps for THIS milestone here (hints, not engine commands). MERGE is one
-> small step among them. These feed the release scope (release.md) when the cut is bundled.
+> AI-written steps for THIS milestone (hints, not engine commands); MERGE is one small step; the human runs the cut.
 - [ ] <step — e.g. open a PR from the Close ship-review above; the human reviews + merges>
 - [ ] <step — e.g. export the ship-review to a hand-off doc, e.g. `pandoc CLOSE.md -o close.docx`>
-- [ ] <step — e.g. tag / publish / deploy  (human-run, per release.md)>
+- [ ] <step — e.g. tag / publish / deploy  (human-run)>

package/tooling/templates/PLAN.md.tmpl

@@ -0,0 +1,129 @@
+# PLAN: {{title}}
+
+slug: {{slug}} · created: {{date}} · stage: {{stage}}
+milestone: {{milestone}}
+autonomy: {{autonomy}}   <!-- manual<conservative<auto — lower for high-risk (`add.py autonomy set`); a `component: <name>` line joins that root to §3 Scope; task edges: `--depends-on`/`--extends`/`--relates-to`; high-risk/method-defining? declare `risk: high` on the slug line; headless agent-crossed freeze? declare `gate_mode: ai-plan-verify` here (human floor: security|data|architecture never AI-frozen) -->
+phase: direction   <!-- direction→build→verify→done; direction drafts §1–§4 (rules · scenarios · change plan · red suite) to the ONE freeze -->
+
+> One file = one task — an ATOMIC node: persist the interface (contract · red suite · scope · verdict); reason everything else in-context, don't write essays. The phase marker above is the single source of truth (`add.py phase`).
+
+---
+
+## 1 · SPECIFY — the rules ▸ docs/03-step-1-specify.md
+
+Feature: <name — one-line description of the behavior this task ships>
+Framings weighed: <chosen> (chosen — why) · <alternative>
+Must:
+<must>
+  - <required behavior>
+</must>
+Reject:
+<reject>
+  - <bad input / situation> -> "<error_code>"
+</reject>
+After:
+<after>
+  - <state that is true once it succeeds>
+</after>
+Boundary: <one format-variant per external input shape the tests must speak — e.g. aware vs naive timestamp · or "none — no external input">
+<assumptions>
+  ⚠ <the ONE assumption most likely to be wrong — if wrong: <cost>>
+</assumptions>
+
+---
+
+## 2 · SCENARIOS — pass/fail cases ▸ docs/04-step-2-scenarios.md
+
+<scenarios>
+</scenarios>
+<!-- The §4 test_plan is the canonical encoding of every scenario (one test per Must/Reject). Add gherkin above ONLY when a human stakeholder needs readable cases — never as ceremony. -->
+
+---
+
+## 3 · PLAN — the change plan: ground · contract · build-strategy ▸ docs/05-step-3-plan.md
+
+### Contract (freeze the shape — the HARD, tamper-guarded core; ground it in the REAL code in-context, cite symbols not line numbers)
+
+```
+<METHOD> <path>   body: { <fields> }
+  200 -> { <success fields> }
+  4xx -> { error: "<code>" | "<code>" }
+Schema: <tables/fields touched, and access pattern>
+```
+
+Target (measurable): <the success bar §6 evidence must hit — numbers, not adjectives — judged at the gate via --target-hit; name any outcome tests can't show (boots · renders) + how it's confirmed>
+Status: DRAFT
+Reported: <yes — the freeze report (banner/ARC/SHAPE) rendered before this froze | no>
+
+### Build-strategy (SOFT: preferred; the builder self-improves and records actual at verify)
+Scope (may touch): `./src/`   <fill before the freeze — the file write-set, single source of truth; every file the build may write; scope-lock source>
+Regression floor: <the existing suite(s) that must stay green — the host repo's own tests are ALWAYS a floor; run them before the gate — or "none — greenfield">
+Persona (required): <persona file under `.add/personas/` this build embodies — advisory, never lowers a gate; "generic" if none fits>
+
+### AI-verify record (required when gate_mode: ai-plan-verify)
+- [ ] §3 PLAN grounding anchors resolve in the current tree
+- [ ] §1 every Must + every Reject present, each Reject paired with an error code
+- [ ] §3 Contract shape is concrete (no template placeholder text remains)
+- [ ] Lowest-confidence flag surfaced and substantive (mirrors unflagged_freeze's own bar)
+Verified by: <agent-id> · at: <ISO-8601 UTC timestamp>
+
+<!-- The freeze IS the one approval, led by the bundle's lowest-confidence flag — Contract = HARD (tamper-guarded); Build-strategy = SOFT. Approved -> Status: FROZEN @ vN — approved by <name>; changing a frozen Contract = change request back to SPECIFY. Scope tokens, backticked: `./…` = this task dir · a "/" token = project root · a bare name = sibling of the previous token's dir · a directory covers its whole subtree · outside-root drops fail-closed · absent line = UNDECLARED (grandfathered, never retro-red). -->
+
+---
+
+## 4 · TESTS — failing-first suite or acceptance checks (red) ▸ docs/06-step-4-tests.md
+
+<test_plan>
+  - test_<name>: arrange / act / assert behavior not internals · covers: <M#, R:code>
+</test_plan>
+
+Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
+<!-- declare paths as backticked tokens on this line: `./…` = this task dir · a token with "/" = the project root · a bare name = a sibling of the previous token's dir · a directory counts its *.py files (non-recursive) · declared counts marked † · outside the project root counts 0. The test_plan bullets' `covers:` tails are machine-read too: `add.py locate path::test_name` resolves a failing test to the frozen §3 clause it proves -->
+<!-- NON-CODING task (kind: docs · release · infra, or a non-coding project)? §4 is a failing-first ACCEPTANCE CHECK, not a script — verifiable pass/fail evidence (mkdocs build succeeds · §X covers A/B/C · every internal link resolves), red before the artifact exists and green after. Set `Tests live in: evidence` (no `./tests/`). The red→green discipline holds; only the must-be-executable-code requirement is lifted. -->
+
+---
+
+## 5 · BUILD — AI writes the code (execution) ▸ docs/07-step-5-build.md
+
+Strategy actually used: <fill at VERIFY — what you ACTUALLY did (or "as planned"); harvested into §7 Decisions (ADR)>
+Code lives in: `./src/`
+Spawn (multi-agent): build/verify subagent spawns default `isolation: worktree`; cross-agent advisor — spawn `add-advisor` (an agent OTHER than the builder) for the freeze `--cross` and the §6 refute-read; `self` only when solo.
+Constraints: do NOT change any test or the frozen §3 contract; stay inside §3 Scope (an out-of-scope build fails the gate: scope_violation); keep the §3 Regression floor green; allow-list packages only; ask if unclear.
+
+---
+
+## 6 · VERIFY — evidence + non-functional review ▸ docs/08-step-6-verify.md
+
+- [ ] all tests (or §4 acceptance checks) pass — including the §3 Regression floor (host suite)
+- [ ] coverage did not decrease
+- [ ] no test or contract was altered during build
+- [ ] the green was EARNED, not gamed — no overfit to fixtures, vacuous asserts, or stubbed-away logic (a confirmed cheat is HARD-STOP)
+- [ ] concurrency / timing of the risky operation is safe
+- [ ] no exposed secrets, injection openings, or unexpected dependencies
+- [ ] layering & dependencies follow CONVENTIONS.md
+- [ ] a person reviewed and approved the change
+
+### Refute-read verdict — the earned-green check (record it; required for an auto-PASS)
+Verdict: <EARNED | NOT-EARNED>
+By: <self | agent-id> · adversarially checked: <what was probed>
+
+### GATE RECORD
+Reported: <yes — the gate report (banner/ARC) rendered before this outcome recorded | no>
+Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
+If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)
+Reviewed by: <name> · date: <date>
+
+<!-- Security is ALWAYS HARD-STOP; record exactly one outcome — no silent pass. The Refute-read verdict is recorded, never engine-blocked; a human spot-audit backstops anything unrecorded. -->
+
+---
+
+## 7 · OBSERVE — feed the next loop ▸ docs/09-the-loop.md
+
+### Decisions (ADR)
+<harvested at done from §1/§3/§5/§6 — do not hand-edit; one actor-tagged line per decision, refilled only while this placeholder stands>
+
+### Spec delta
+One line per forward change, tagged `[SPEC · open|seeded|dropped]` + evidence — each re-enters at Specify (`deltas.md`).
+
+### Competency deltas
+One lesson per line: `[DDD|SDD|UDD|TDD|ADD · open] the learning (evidence: …)` — see `deltas.md`.

package/tooling/templates/PROJECT.md.tmpl

@@ -7,13 +7,16 @@
 > that is the re-entrant arrow from the engine down to the foundation.
 
 slug: {{project}} · stage: {{stage}} · updated: {{date}}
-autonomy: auto   <!-- project default — new tasks inherit this rung (manual < conservative < auto); lower a single task in its TASK.md header when it needs a human gate. -->
+autonomy: auto   <!-- project default — new tasks inherit this rung (manual < conservative < auto); lower a single task in its PLAN.md header when it needs a human gate. -->
 goal:
 <!-- set at setup — the outcome this project runs toward; status/guide surface it every session -->
 
 ---
 
 ## Domain (DDD) — the language and the boundaries
+invariants:
+<!-- never deferred — pin the run/entry contract + the one domain invariant at setup; every task §0 re-states these -->
+<!-- living: fill on first touch — grown by milestones/tasks; lessons land in .add/specs/ via `add.py delta-append` -->
 <!-- One name per concept (the GLOSSARY holds the full term list). What are the
      core entities, the bounded contexts/modules, and the invariants that MUST
      always hold? This is the ubiquitous language the spec and code share. -->
@@ -22,6 +25,7 @@ goal:
 - Invariants that must always hold:
 
 ## Spec / Living Document (SDD) — what we are building, now
+<!-- living: fill on first touch — grown by milestones/tasks; lessons land in .add/specs/ via `add.py delta-append` -->
 <!-- The spec is a living document, not a frozen plan. This section POINTS to the
      active milestone + frozen contracts; it does not duplicate them. -->
 - Active milestone → `.add/milestones/<slug>/MILESTONE.md`  (see `add.py status`)
@@ -29,6 +33,7 @@ goal:
 - Settled vs still open: <frozen contracts · open questions>
 
 ## Users (UDD) — UI/UX: design before code
+<!-- living: fill on first touch — grown by milestones/tasks; lessons land in .add/specs/ via `add.py delta-append` -->
 <!-- UI/UX-Driven Development: users use the interface, not the spec. Capture the
      experience BEFORE code. Per-feature design detail lives in a DESIGN.md /
      clickable prototype; keep here the cross-cutting UX stance + the source of truth.