@pilotspace/add 1.1.0 → 1.2.0

package/tooling/add.py

@@ -26,7 +26,14 @@ from pathlib import Path
 ROOT_DIRNAME = ".add"
 STATE_FILE = "state.json"
 MILESTONE_FILE = "MILESTONE.md"
+# The project GOAL (v20) is read live from PROJECT.md — never copied into state.json
+# (single-source; the foundation is the truth). A missing/blank source degrades to
+# this sentinel so the read-only orientation surfaces never blank or crash.
+GOAL_UNSET = "(unset — add a 'goal:' line to PROJECT.md)"
 STAGES = ("prototype", "poc", "mvp", "production")
+# v22 stage-graduation: the read-only cue `status` shows when the MVP is covered.
+# Worded as the ACTION (never a file) so it stands before graduate.md exists.
+GRADUATION_CUE = "MVP covered → propose graduation"
 PHASES = ("specify", "scenarios", "contract", "tests", "build", "verify", "observe", "done")
 GATES = ("none", "PASS", "RISK-ACCEPTED", "HARD-STOP")
 
@@ -38,7 +45,7 @@ def _phase_index(name: str) -> int:
 # `add.py guide` copy: per-phase (concrete next action, book chapter to read).
 # Keep the action wording aligned with each phase's EXIT line in the TASK template.
 PHASE_GUIDE = {
-    "specify":   ("state every rule — Must / Reject (+ named code) / After; rank assumptions least-sure first and flag the biggest risk",
+    "specify":   ("state every rule — Must / Reject (+ named code) / After; rank assumptions lowest-confidence first and flag the biggest risk",
                   "03-step-1-specify.md"),
     "scenarios": ("write one Given/When/Then per Must AND per Reject; every result observable",
                   "04-step-2-scenarios.md"),
@@ -48,7 +55,7 @@ PHASE_GUIDE = {
                   "06-step-4-tests.md"),
     "build":     ("write the minimum code to pass the tests; change no test and no contract",
                   "07-step-5-build.md"),
-    "verify":    ("run the suite + blind-spot checks, then record the gate",
+    "verify":    ("run the suite + non-functional checks, then record the gate",
                   "08-step-6-verify.md"),
     "observe":   ("note what to watch + the spec delta for the next loop",
                   "09-the-loop.md"),
@@ -85,8 +92,8 @@ Framings weighed:
 Must:
 Reject:
 After:
-Assumptions — least-sure first:
-  ⚠ <most likely wrong> — least sure because <why>; if wrong: <cost>
+Assumptions — lowest-confidence first:
+  ⚠ <most likely wrong> — lowest confidence because <why>; if wrong: <cost>
 
 ## 2 · SCENARIOS
 ## 3 · CONTRACT
@@ -244,7 +251,7 @@ def _guideline_block() -> str:
         "   guide ends with its exit gate and the command to move on.\n"
         "\n"
         "The flow: INTAKE sizes a request into a milestone; each task runs the\n"
-        "**one-approval front** — Spec+Scenarios+Contract+Tests as one bundle,\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"
         "Never weaken a test or edit a frozen contract to make a build pass; a security\n"
@@ -332,7 +339,7 @@ def _is_brownfield(base: Path) -> bool:
     """True when `base` already holds project content beyond the tool's own scaffolding.
 
     Judgment-free: a mechanical fact (does the dir hold a non-excluded entry?), so the
-    autonomous-onboarding flow knows to map existing code into the survivors. INTERPRETING
+    autonomous-onboarding flow knows to map existing code into the living documentation. INTERPRETING
     that code stays with the AI (skill/add/adopt.md) — the engine only detects + signals."""
     if not base.is_dir():
         return False
@@ -515,6 +522,20 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # into build/verify/observe/done is refused until `add.py lock`.
     if not _setup_locked(state) and nxt in ("build", "verify", "observe", "done"):
         _die("setup_unlocked: lock the foundation first — add.py lock")
+    # flag-first freeze guard (task unflagged-freeze): a FROZEN §3 may not cross
+    # into build without a WELL-FORMED lowest-confidence flag. On pass, stamp the
+    # verified marker so `audit` enforces the flag on THIS record only (open/new
+    # freezes — the unmarked predecessors are never retro-redded). REFUSE writes
+    # nothing (fail-closed); below the build boundary the flag is never checked.
+    if nxt == "build":
+        raw3 = _raw_phase_bodies(root, slug).get(3, "")
+        if _contract_frozen(raw3):
+            if not _flag_well_formed(raw3):
+                _die("unflagged_freeze: a frozen §3 must surface a well-formed "
+                     "'Least-sure flag surfaced at freeze:' unit (>=1 [part] tag "
+                     "+ substantive content; bare 'none' only as 'none material — "
+                     "biggest risk: X') before crossing into build")
+            state["tasks"][slug]["flag_verified"] = True
     state["tasks"][slug]["phase"] = nxt
     state["tasks"][slug]["updated"] = _now()
     _sync_task_marker(root, slug, nxt)
@@ -569,7 +590,7 @@ def cmd_gate(args: argparse.Namespace) -> None:
         hdr = _task_header(root, slug)
         if _RISK_HIGH_RE.search(hdr) and not _AUTONOMY_CONSERVATIVE_RE.search(hdr):
             _die(f"unguarded_high_risk_auto: task '{slug}' declares risk: high "
-                 "without autonomy: conservative — lower the dial in the TASK.md "
+                 "without autonomy: conservative — lower the autonomy level in the TASK.md "
                  "header; a human must own a high-risk gate (run.md guard)")
     if args.outcome == "RISK-ACCEPTED":
         # A waiver must be SIGNED: owner, ticket, expiry (glossary). Stored in state
@@ -592,10 +613,49 @@ def cmd_gate(args: argparse.Namespace) -> None:
         print("HARD-STOP recorded: return to BUILD; nothing ships on a failing/security gate.")
 
 
+def cmd_reopen(args: argparse.Namespace) -> None:
+    """Return an already-`done` task to an earlier phase with a never-silent record.
+
+    The flow already permits backward correction (book ch02: "any phase may return
+    to an earlier one"); `done` is terminal EXCEPT via this recorded action. reopen
+    sets the phase back, resets the gate to "none" (the task must re-earn its
+    verdict), and appends an append-only `reopens` entry recording WHY. A done task
+    done via RISK-ACCEPTED carries a live `waiver`; reopen records it inside the entry
+    (prior_gate / prior_waiver) and drops the live key, so no signed waiver lingers
+    without a verdict. Judgement of WHEN to reopen stays the resolver's; the engine
+    only enforces the recorded, coherent transition.
+    """
+    root = _require_root()
+    state = load_state(root)
+    slug = _resolve_task(state, args.slug)
+    t = state["tasks"][slug]
+    if t.get("phase") != "done":
+        _die(f"reopen_not_done: task '{slug}' is at '{t.get('phase')}', not done — "
+             "backward correction inside a live run is `add.py phase` / HARD-STOP, not reopen")
+    reason = (args.reason or "").strip()
+    if not reason:
+        _die("reopen_reason_required: reopen records WHY — supply a non-empty --reason")
+    target = args.to
+    if target not in PHASES[:7]:        # specify..observe; never "done", never an unknown name
+        _die(f"reopen_target_invalid: --to must be one of {', '.join(PHASES[:7])} (got {target!r})")
+    now = _now()
+    entry = {"from": "done", "to": target, "reason": reason, "at": now,
+             "prior_gate": t.get("gate", "none")}
+    if t.get("waiver"):                 # void verdict's waiver -> history, drop the live key
+        entry["prior_waiver"] = t.pop("waiver")
+    t.setdefault("reopens", []).append(entry)
+    t["phase"] = target
+    t["gate"] = "none"
+    t["updated"] = now
+    _sync_task_marker(root, slug, target)
+    save_state(root, state)
+    print(f"task '{slug}' reopened: done -> {target} (reason recorded); gate reset to none")
+
+
 def cmd_lock(args: argparse.Namespace) -> None:
-    """The human lock-down: freeze the autonomously-drafted setup in ONE atomic write.
+    """The human baseline approval: freeze the autonomously-drafted setup in ONE atomic write.
 
-    Setup-altitude analog of the contract freeze — the only new human action onboarding
+    Setup-level analog of the contract freeze — the only new human action onboarding
     needs. `add.py lock` is judgment-free (it records the signature; it does NOT inspect
     the artifacts): the human's signature IS the gate."""
     root = _require_root()
@@ -622,19 +682,42 @@ def cmd_lock(args: argparse.Namespace) -> None:
         print(f"locked setup ({','.join(layers)}) by {who} @ {when}")
 
 
+def _has_production_roadmap(state: dict) -> bool:
+    """True iff ≥1 milestone in state has stage == "production" (STATUS-AGNOSTIC).
+    The single source of the stage-graduation floor (v22 graduate-guide): the guard counts
+    that a production-roadmap RECORD exists — it never judges whether those milestones are
+    done/good/sufficient (gather-not-judge). An archived-out-of-state roadmap falls to --force."""
+    return any(m.get("stage") == "production"
+               for m in state.get("milestones", {}).values())
+
+
 def cmd_stage(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
     if args.stage not in STAGES:
         _die(f"stage must be one of: {', '.join(STAGES)}")
+    # v22 stage-graduation guard: the →production TRANSITION refuses without a roadmap — a tally
+    # check (≥1 production milestone exists), never a readiness judgment. Scoped to production
+    # ONLY; every other flip is the existing bare flip, byte-unchanged. --force overrides
+    # (precedent: lock --force). The flip is graduate.md's FINAL, confirmed-roadmap step.
+    forced = getattr(args, "force", False)
+    bypassing = False
+    if args.stage == "production":
+        roadmap = _has_production_roadmap(state)
+        if not roadmap and not forced:
+            _die("stage_no_roadmap: no production milestone drafted. Draft ≥1 via "
+                 "graduate.md (new-milestone --stage production), or use --force to override.")
+        bypassing = forced and not roadmap
     state["stage"] = args.stage
     save_state(root, state)
     print(f"project stage -> {args.stage}")
+    if bypassing:
+        print("(--force: bypassed roadmap check — no production milestone drafted)")
 
 
 def cmd_status(args: argparse.Namespace) -> None:
     if getattr(args, "json", False):
-        _, state = _load_state_for_json()
+        root, state = _load_state_for_json()
         tasks = state.get("tasks") or {}
         milestones = state.get("milestones") or {}
         ms_list = []
@@ -643,12 +726,15 @@ def cmd_status(args: argparse.Namespace) -> None:
             ms_list.append({"slug": mslug, "status": m.get("status", "active"),
                             "done": sum(1 for t in members if _task_done(t)),
                             "total": len(members)})
+        grad_ready, grad_met, grad_total = _graduation_ready(root, state)
         print(json.dumps({
             "project": state.get("project"), "stage": state.get("stage"),
             "active_task": state.get("active_task"),
             "milestones": ms_list,
             "tasks": [{"slug": s, "phase": t.get("phase"), "gate": t.get("gate"),
-                       "milestone": t.get("milestone")} for s, t in tasks.items()]}))
+                       "milestone": t.get("milestone")} for s, t in tasks.items()],
+            "graduation_ready": grad_ready,
+            "stage_criteria": {"met": grad_met, "total": grad_total}}))
         return
     root = _require_root()
     state = load_state(root)
@@ -659,9 +745,24 @@ def cmd_status(args: argparse.Namespace) -> None:
     unlocked = not _setup_locked(state)
     print(f"project : {state.get('project', '(unknown)')}")
     print(f"stage   : {state.get('stage', '(unknown)')}")
+    # project GOAL + active-milestone goal (v20) — the loop's orientation anchor, read
+    # LIVE from PROJECT.md / MILESTONE.md (never state.json). Additive: every existing
+    # line stays put. A missing source degrades to a sentinel — one never blanks the other.
+    print(f"goal    : {_project_goal(root)}")
+    _active_ms = state.get("active_milestone")
+    if _active_ms:
+        print(f"m-goal  : {_milestone_doc(root, _active_ms)[1]}   (← {_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)")
+    # wave resume hint — a live ledger outranks memory (streams.md "Wave ledger").
+    # Existence-only: no open/read/parse, so the hint adds no IO failure path; a
+    # non-file at the path is not a ledger. One line PER live ledger — more than
+    # one live wave is an anomaly the orchestrator must see, never a line we hide.
+    for _wave in sorted((root / "milestones").glob("*/WAVE.md")):
+        if _wave.is_file():
+            print(f"wave    : LIVE — .add/milestones/{_wave.parent.name}/WAVE.md"
+                  "  (wave resume point — re-orient from the ledger first)")
 
     # milestone rollup (only when milestones are in use)
     milestones = state.get("milestones") or {}
@@ -674,6 +775,12 @@ def cmd_status(args: argparse.Namespace) -> None:
             mark = "*" if mslug == active_ms else " "
             print(f"  {mark} {mslug:<20} {done}/{len(members)} tasks done"
                   f"   status={m.get('status', 'active')}")
+        # 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).
+        grad_ready, _gm, _gt = _graduation_ready(root, state)
+        if grad_ready:
+            print(f"  → {GRADUATION_CUE}")
 
     # archived rollup — one line keeps state visible without re-bloating status
     archived = state.get("archived") or []
@@ -691,7 +798,7 @@ def cmd_status(args: argparse.Namespace) -> None:
         print("tasks   : (none yet)")
         print()
         if unlocked:
-            print("setup   : UNLOCKED — review .add/SETUP-REVIEW.md (least-sure first),"
+            print("setup   : UNLOCKED — review .add/SETUP-REVIEW.md (lowest-confidence first),"
                   " then sign: add.py lock")
             print("          (the build-boundary gate is closed until the foundation is locked)")
         else:
@@ -710,11 +817,11 @@ def cmd_status(args: argparse.Namespace) -> None:
     # 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())
     if open_deltas:
-        print(f"deltas  : {open_deltas} open — fold at milestone close (add.py deltas)")
+        print(f"deltas  : {open_deltas} open — consolidate at milestone close (add.py deltas)")
     # When the setup is unlocked, the only terminal guidance that matters is
     # review+lock; suppress the generic resume block so it does not compete.
     if unlocked:
-        print("\nsetup   : UNLOCKED — review .add/SETUP-REVIEW.md (least-sure first),"
+        print("\nsetup   : UNLOCKED — review .add/SETUP-REVIEW.md (lowest-confidence first),"
               " then sign: add.py lock")
         print("          (the build-boundary gate is closed until the foundation is locked)")
     elif active and active in tasks:
@@ -791,6 +898,7 @@ def cmd_guide(args: argparse.Namespace) -> None:
         _die(f"task '{slug}' has unknown phase '{phase}' (state.json corrupted?)")
     action, chapter = entry
     print(f"active : {slug}  (phase: {phase})")
+    print(f"goal   : {_project_goal(root)}")   # v20 — the next-step surface still shows what the work is FOR
     print(f"next   : {action}")
     print(f"read   : .add/docs/{chapter}")
     gp = _phase_guide_path(root.parent, phase)
@@ -1001,6 +1109,17 @@ def cmd_milestone_done(args: argparse.Namespace) -> None:
             t = members[s]
             print(f"  - {s} (phase={t.get('phase')}, gate={t.get('gate')})", file=sys.stderr)
         _die("milestone_incomplete")
+    # Goal-gate (v20 dynamic-task-loop): a milestone holds until its exit criteria are
+    # met. The engine READS the checkbox tally (the human's goal-met affirmation, like a
+    # gate=PASS) — it never judges the goal. Fires ONLY when criteria exist, so a
+    # criteria-less milestone and every pre-v20 close path stay valid. milestone-done is
+    # the SOLE status->done transition; archive-milestone/compact already refuse a
+    # non-done milestone, so this single gate has no back door. Refuse BEFORE any write.
+    met, total = _exit_criteria(root, slug)
+    if total > 0 and met < total:
+        _die(f"milestone_goal_unmet: milestone '{slug}' has {met}/{total} exit criteria met "
+             f"— check the remaining boxes in MILESTONE.md (the goal-gate holds the loop "
+             f"open) or propose the next tasks (add.py deltas)")
     # Fail-closed: render+persist the exit report (RETRO.md) BEFORE committing the
     # status flip, so a write failure rolls back naturally (status never commits ->
     # no done-without-retro state). The retro step is read-only on state.json.
@@ -1020,7 +1139,7 @@ def cmd_milestone_done(args: argparse.Namespace) -> None:
     open_deltas = sum(len(v) for v in _collect_open_deltas(root).values())
     if open_deltas:
         noun = "delta" if open_deltas == 1 else "deltas"
-        print(f"note: {open_deltas} open competency {noun} to fold into the foundation "
+        print(f"note: {open_deltas} open {noun} to consolidate into the foundation "
               f"— review with: add.py deltas")
 
 
@@ -1076,6 +1195,70 @@ def cmd_archive_milestone(args: argparse.Namespace) -> None:
     print("files on disk are untouched; see `add.py status` for the archived rollup.")
 
 
+def cmd_compact(args: argparse.Namespace) -> None:
+    """Heavy archive (step two, after `archive-milestone`): move a light-archived
+    milestone's files — MILESTONE.md + siblings + every rollup-member task dir — into
+    one recovery bundle `.add/archive/<slug>/`. Validate-all-then-move: any reject
+    leaves the tree AND state.json byte-for-byte unchanged. Compact never deletes,
+    only renames; recovery = reverse move, no state edit (state already dropped these
+    at light archive). Preserves the _archived_task_slugs invariant: `task_slugs` is
+    never touched — archived ⇒ was PASS-done keeps resolving cross-milestone deps."""
+    root = _require_root()
+    state = load_state(root)
+    slug = args.slug
+    # validate before any mutation — a reject must leave tree + state byte-for-byte unchanged
+    if slug in state.get("milestones", {}):
+        _die(f"milestone_not_archived: '{slug}' is still active — "
+             f"run `add.py archive-milestone {slug}` first (light archive is step one)")
+    entry = next((e for e in state.get("archived", []) if e.get("slug") == slug), None)
+    if entry is None:
+        _die("unknown_milestone")
+    if entry.get("compacted"):
+        _die(f"already_compacted: '{slug}' was compacted {entry['compacted']} — "
+             f"see .add/archive/{slug}/")
+    dest = root / "archive" / slug
+    if dest.exists():
+        _die(f"archive_destination_exists: .add/archive/{slug}/ exists without a "
+             "compacted stamp — resolve the collision by hand before compacting")
+    ms_dir = root / "milestones" / slug
+    members = list(entry.get("task_slugs") or [])
+    missing = [str(p.relative_to(root)) for p in
+               [ms_dir, *(root / "tasks" / t for t in members)] if not p.is_dir()]
+    if missing:
+        _die("source_files_missing: " + " · ".join(missing))
+    # deltas folded first: an `open` lesson inside the bundle would silently vanish
+    # from `add.py deltas` (_collect_open_deltas globs tasks/*/TASK.md) once moved.
+    member_set = set(members)
+    offenders = sorted({e["task"] for v in _collect_open_deltas(root).values()
+                        for e in v if e["task"] in member_set})
+    if offenders:
+        _die("open_deltas_unfolded: consolidate the open lessons first (`add.py deltas`) — "
+             "open in: " + " · ".join(offenders))
+    # every precondition passed — move (same-filesystem renames, never a delete)
+    def _files(d: Path) -> int:
+        return sum(1 for f in d.rglob("*") if f.is_file())
+    moved: list[tuple[str, int]] = []
+    (root / "archive").mkdir(exist_ok=True)
+    n = _files(ms_dir)
+    ms_dir.rename(dest)                       # the milestone dir becomes the bundle root
+    moved.append((f"milestones/{slug}/", n))
+    (dest / "tasks").mkdir(exist_ok=True)
+    for t in members:
+        src = root / "tasks" / t
+        n = _files(src)
+        src.rename(dest / "tasks" / t)
+        moved.append((f"tasks/{t}/", n))
+    # state write is the LAST step: additive stamp only — task_slugs untouched
+    entry["compacted"] = date.today().isoformat()
+    save_state(root, state)
+    total = sum(n for _, n in moved)
+    print(f"compacted milestone '{slug}' -> .add/archive/{slug}/ "
+          f"({len(members)} task dirs, {total} files moved)")
+    for path, n in moved:
+        print(f"  moved {path} ({n} files)")
+    print("recovery: reverse the moves (mv the bundle's parts back) — state needs no edit.")
+
+
 def cmd_set_milestone(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
@@ -1236,6 +1419,21 @@ def _colorize(s: str) -> str:
     return s
 
 
+def _project_goal(root: Path) -> str:
+    """The project GOAL — the value of the first `goal:` line in PROJECT.md, else
+    GOAL_UNSET. Read-only and fail-closed: a missing/unreadable foundation or a
+    blank value degrades to the sentinel (orientation never raises). Mirrors how
+    _milestone_doc reads the milestone goal — the foundation is the single source."""
+    f = root / "PROJECT.md"
+    try:
+        for line in f.read_text(encoding="utf-8").splitlines():
+            if line.startswith("goal:"):
+                return line.split(":", 1)[1].strip() or GOAL_UNSET
+    except OSError:
+        pass
+    return GOAL_UNSET
+
+
 def _milestone_doc(root: Path, mslug: str) -> tuple[str, str]:
     """(title, goal) from MILESTONE.md; ('(unknown)','(unknown)') if the doc is gone."""
     f = root / "milestones" / mslug / MILESTONE_FILE
@@ -1265,6 +1463,41 @@ def _exit_criteria(root: Path, mslug: str) -> tuple[int, int]:
     return met, total
 
 
+def _stage_criteria(root: Path) -> tuple[int, int]:
+    """(met, total) checkbox tally inside PROJECT.md's 'Stage goal criteria' section — the
+    PROJECT.md analog of _exit_criteria (v22): the human's stage-covered affirmation. Read-only
+    and fail-closed to (0, 0): a missing file, a missing section, or any read error never raises
+    and never fabricates a cue (so an unreadable foundation withholds graduation, design-for-failure)."""
+    try:
+        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+    except OSError:
+        return 0, 0
+    m = re.search(r"## Stage goal criteria.*?(?=\n## |\Z)", text, re.S)
+    if not m:
+        return 0, 0
+    sec = m.group(0)
+    met = len(re.findall(r"- \[x\]", sec))
+    total = met + len(re.findall(r"- \[ \]", sec))
+    return met, total
+
+
+def _all_milestones_done(state: dict) -> bool:
+    """True when the project HAS milestones and EVERY one is status=done (v22). Archived
+    milestones are absent from state['milestones'] (removed by the archive lifecycle), so they
+    do not count; a project with zero milestones is not 'covered' and returns False."""
+    ms = state.get("milestones") or {}
+    return bool(ms) and all(m.get("status") == "done" for m in ms.values())
+
+
+def _graduation_ready(root: Path, state: dict) -> tuple[bool, int, int]:
+    """(ready, met, total) for the stage-graduation cue (v22): every milestone done AND the
+    human's stage-goal-criteria all checked (total>0 and met==total). The SINGLE source the
+    text and --json status branches share, so the cue and the json signal can never disagree."""
+    met, total = _stage_criteria(root)
+    ready = _all_milestones_done(state) and total > 0 and met == total
+    return ready, met, total
+
+
 def _count_test_defs(f: Path) -> int:
     """`def test_` occurrences in one file — the ONE counting regex (primary and
     §4-declared fallback share it by construction). OSError -> 0, fail-closed."""
@@ -1748,8 +1981,39 @@ def _contract_frozen(raw3: str) -> bool:
     return any(re.match(r"\s*Status:\s*FROZEN", ln) for ln in raw3.splitlines())
 
 
+_FLAG_LABEL_RE = re.compile(r"Least-sure flag surfaced at freeze\s*:", re.I)
+_FLAG_PART_RE = re.compile(
+    r"\[(?:spec|scenario|contract|test)(?:/(?:spec|scenario|contract|test))*\]")
+_FLAG_NONE_ESCAPE_RE = re.compile(
+    r"none material\s*[—-]+\s*biggest risk\s*:\s*\S", re.I)
+
+
+def _flag_well_formed(raw3: str) -> bool:
+    """A FROZEN §3 must surface a WELL-FORMED lowest-confidence flag — the unit
+    that NAMES which part of the bundle is least certain. Well-formed := the label
+    phrase + a unit carrying >=1 [part] tag (part in spec/scenario/contract/test,
+    slash-joinable like [spec/contract]) + substantive content. A bare 'none' is
+    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)
+    m = _FLAG_LABEL_RE.search(body)
+    if not m:
+        return False
+    unit = body[m.end():].strip()
+    if not unit:
+        return False
+    if _FLAG_NONE_ESCAPE_RE.search(unit):    # the honest-none escape — no tag needed
+        return True
+    if not _FLAG_PART_RE.search(unit):       # must name WHICH part is uncertain
+        return False
+    residue = _FLAG_PART_RE.sub("", unit).replace("⚠", "").strip(" -—·\n\t")
+    return len(residue) >= 3                  # substantive content beyond the tag(s)
+
+
 def decide_data(root: Path, state: dict, mslug: str, slug: str) -> dict:
-    """FACTS for the task-level decision-seam digest (frozen shape). The seam comes
+    """FACTS for the task-level decision-point digest (frozen shape). The decision comes
     from STATE ONLY: recorded (gate set / observe / done) · front (specify→tests) ·
     gate (build/verify). judgment = extracted markers, byte-verbatim. PURE."""
     tasks = state.get("tasks") or {}
@@ -1786,7 +2050,7 @@ def decide_data(root: Path, state: dict, mslug: str, slug: str) -> dict:
         decide = "approve -> freeze §3 (Status: FROZEN @ v1) -> auto run"
     elif seam == "front":
         unlocks = "none"
-        decide = "no decision pending — frozen; the run owns it. next seam: verify gate"
+        decide = "no decision pending — frozen; the run owns it. next decision point: verify gate"
     else:
         unlocks = "none"
         decide = f"no decision pending — recorded gate: {gate}"
@@ -1797,7 +2061,7 @@ def decide_data(root: Path, state: dict, mslug: str, slug: str) -> dict:
 
 def render_decide(root: Path, state: dict, mslug: str, slug: str, *,
                   width: int = _DEFAULT_WIDTH, ascii: bool = False) -> str:
-    """Text view of the decision-seam digest — decisive facts FIRST: NEEDS YOUR
+    """Text view of the decision-point digest — decisive facts FIRST: NEEDS YOUR
     JUDGMENT (markers byte-verbatim, section-tagged) -> [front: §3 verbatim] ->
     ENGINE FACTS -> UNLOCKS -> DECIDE. PURE — no writes; plain text (color is a
     tty-only skin in cmd_report, like every report view)."""
@@ -1806,7 +2070,7 @@ def render_decide(root: Path, state: dict, mslug: str, slug: str, *,
     banner = g["h"] * width
     seam_label = {"gate": "VERIFY GATE", "front": "CONTRACT APPROVAL",
                   "recorded": "RECORDED"}[d["seam"]]
-    L = [banner, f" DECIDE · {mslug or '—'} · {slug} · seam: {seam_label}", banner]
+    L = [banner, f" DECIDE · {mslug or '—'} · {slug} · decision point: {seam_label}", banner]
     if d["decide"].startswith("no decision pending"):
         L.append(f" {d['decide']}")
         L.append(f" GATE  {d['gate']}")
@@ -1853,8 +2117,8 @@ def _planned_unscaffolded(root: Path, mslug: str) -> list[str]:
 
 
 def _decide_next(state: dict, d: dict) -> str:
-    """The rollup's DECIDE NEXT line (frozen precedence): HARD-STOP -> fold+archive
-    -> first seam-blocked task (ACTIVE task first, then state order) -> run-in-
+    """The rollup's DECIDE NEXT line (frozen precedence): HARD-STOP -> consolidate+archive
+    -> first decision-blocked task (ACTIVE task first, then state order) -> run-in-
     progress. v2: when d carries planned_unscaffolded, the line gains a
     plan-vs-state suffix — precedence itself stays state-only."""
     return _decide_next_base(state, d) + _planned_hint(d)
@@ -1880,7 +2144,15 @@ def _decide_next_base(state: dict, d: dict) -> str:
         return f"resolve HARD-STOP on {stopped[0]['slug']}"
     s = d["summary"]
     if s["tasks_done"] == s["tasks_total"]:
-        return f"fold learnings + archive-milestone {ms}"
+        # tasks complete — but the milestone holds while the goal (exit criteria) is
+        # unmet (v20). Point at the feed-forward inventory the loop draws from, instead
+        # of "archive". Fires only when criteria exist; else the prompt is unchanged.
+        ec = s.get("exit_criteria") or {}
+        met, total = ec.get("met", 0), ec.get("total", 0)
+        if total > 0 and met < total:
+            return (f"goal not met ({met}/{total} exit criteria) — propose next tasks "
+                    f"from open deltas / the unscaffolded plan (add.py deltas)")
+        return f"consolidate learnings + archive-milestone {ms}"
     active = state.get("active_task")
     order = sorted(rows, key=lambda r: 0 if r["slug"] == active else 1)  # stable
     for r in order:
@@ -2037,7 +2309,7 @@ def _lint_task_deltas(root: Path, slug: str) -> tuple[bool, str] | None:
 
 
 def _collect_open_deltas(root: Path) -> dict[str, list[dict]]:
-    """Scan every .add/tasks/*/TASK.md for open competency deltas.
+    """Scan every .add/tasks/*/TASK.md for open lessons learned.
 
     Returns a dict keyed by competency in canonical order; each value is a list
     of {task, text, evidence} dicts. READ-ONLY — never mutates any file."""
@@ -2099,7 +2371,7 @@ _AUDIT_REVIEWED_RE = re.compile(r"^Reviewed by:(.*)$", re.M)
 
 
 def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
-    """The gate-audit core: verify that human seams left WELL-FORMED records.
+    """The gate-audit core: verify that human decision points left WELL-FORMED records.
     Judgment-free — checks record SHAPE (a named human at the freeze, exactly one
     gate outcome, prose ≡ state, a marked security note never auto-reviewed),
     never re-decides an outcome. Scope: active tasks done/observe or gated; open
@@ -2122,6 +2394,15 @@ def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
         if not _AUDIT_STAMP_RE.search(s3):
             f(slug, "unstamped_freeze",
               "§3 lacks 'Status: FROZEN @ vN — approved by <name>'")
+        # verified-marker discriminator (task unflagged-freeze): enforce the
+        # lowest-confidence flag ONLY on records that crossed the guard (flag_verified).
+        # A marked record whose flag was deleted/corrupted post-freeze is
+        # tampering; unmarked predecessors are skipped — the board is never
+        # retro-redded.
+        if t.get("flag_verified") and not _flag_well_formed(s3):
+            f(slug, "unflagged_freeze",
+              "flag_verified record lost its well-formed "
+              "'Least-sure flag surfaced at freeze:' unit")
         outcomes = _AUDIT_OUTCOME_RE.findall(s6)
         if len(outcomes) != 1:
             f(slug, "malformed_gate_record",
@@ -2158,8 +2439,8 @@ def _audit_findings(root: Path, state: dict) -> tuple[int, list[dict]]:
 
 
 def cmd_audit(args: argparse.Namespace) -> None:
-    """Read-only: audit recorded human seams for well-formedness. Exit 0 clean,
-    exit 1 with findings — the enforcement seam CI consumes (audit-ci). Writes
+    """Read-only: audit recorded human decision points for well-formedness. Exit 0 clean,
+    exit 1 with findings — the enforcement gate CI consumes (audit-ci). Writes
     NOTHING; every other command is byte-identical."""
     root = _require_root()
     checked, findings = _audit_findings(root, load_state(root))
@@ -2176,8 +2457,146 @@ def cmd_audit(args: argparse.Namespace) -> None:
         sys.exit(1)
 
 
+def _retro_carried(path: Path) -> int:
+    """Parse the 'LEARNINGS (N carried)' count from a RETRO.md; absent/unreadable -> 0.
+    READ-ONLY (the graduation harvest's carried-delta facet for the consolidated tier)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return 0
+    m = re.search(r"LEARNINGS \((\d+) carried\)", text)
+    return int(m.group(1)) if m else 0
+
+
+def graduation_data(root: Path, state: dict) -> dict:
+    """The single source of FACTS for the graduation harvest — PURE, NO writes (mirrors
+    report_data). Both the `graduation-report` text dashboard and `--json` render from this
+    one dict, so the human view and the machine view can never disagree.
+
+    GATHER, never JUDGE: every value is a RECORD the human verifies by looking; there is no
+    readiness/score/ranking field by construction (would_be_judging is structurally impossible).
+    Two tiers: LIVE = in-state (state + on-disk TASK.md); CONSOLIDATED = compacted milestones,
+    a RETRO record only. A missing/unreadable source is SKIPPED, never a crash (fail-closed)."""
+    tasks = state.get("tasks") or {}
+    milestones = state.get("milestones") or {}
+    archived = state.get("archived") or []
+
+    # a — open deltas by competency (reuse the project-wide harvester; compacted folded out)
+    by_comp = _collect_open_deltas(root)
+    open_deltas = {"total": sum(len(v) for v in by_comp.values()),
+                   "by_competency": {c: v for c, v in by_comp.items() if v}}
+
+    # b — open RISK-ACCEPTED waivers, soonest expiry first (missing/unparseable expiry sorts LAST)
+    waivers = []
+    for slug, t in tasks.items():
+        if t.get("gate") == "RISK-ACCEPTED" and t.get("waiver"):
+            w = t["waiver"]
+            waivers.append({"slug": slug, "owner": w.get("owner", "?"),
+                            "ticket": w.get("ticket", "?"), "expires": w.get("expires", "?")})
+
+    def _exp_key(wv):
+        try:
+            return (0, date.fromisoformat(wv["expires"]).isoformat())
+        except (ValueError, TypeError):
+            return (1, "")          # unparseable/missing -> after every real date
+    waivers.sort(key=_exp_key)
+
+    # c — RETRO records: LIVE under milestones/, CONSOLIDATED under archive/ (the compacted backbone)
+    retros = []
+    for sub_dir, tier in ((root / "milestones", "live"), (root / "archive", "consolidated")):
+        if sub_dir.is_dir():
+            for retro in sorted(sub_dir.glob("*/RETRO.md")):
+                if retro.is_file():     # a directory at the path is not a ledger (fail-closed)
+                    retros.append({"milestone": retro.parent.name,
+                                   "path": str(retro.relative_to(root)),
+                                   "carried_deltas": _retro_carried(retro), "tier": tier})
+
+    # d-i — residue gate records: the residue-class facet (RISK-ACCEPTED shares the waivers[] record)
+    residue_gates = [{"slug": s, "gate": t.get("gate")} for s, t in tasks.items()
+                     if t.get("gate") in ("RISK-ACCEPTED", "HARD-STOP")]
+
+    # d-ii — §6 disclosed residue: in-state tasks' '- [⚠]' VERIFY list items (the pinned rule)
+    # e   — coverage-gaps proxy: in-state §7 Watch still the '<error rate' placeholder head
+    residue_disclosed, coverage_gaps = [], []
+    for slug in tasks:
+        try:
+            text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+        except OSError:
+            continue                 # unreadable TASK.md -> skip this task's prose records
+        m = re.search(r"##\s*6\b.*?(?=\n##\s*\d|\Z)", text, re.S)   # the VERIFY section only
+        for line in (m.group(0) if m else "").splitlines():
+            st = line.strip()
+            if st.startswith("- [⚠]"):
+                residue_disclosed.append({"slug": slug, "line": st[len("- [⚠]"):].strip()})
+        for line in text.splitlines():
+            if line.startswith("Watch") and "<error rate" in line:  # unfilled <…> template head
+                coverage_gaps.append({"slug": slug})
+                break
+
+    return {
+        "open_deltas": open_deltas,
+        "waivers": waivers,
+        "retros": retros,
+        "residue_gates": residue_gates,
+        "residue_disclosed": residue_disclosed,
+        "coverage_gaps": coverage_gaps,
+        "summary": {
+            "open_deltas": open_deltas["total"], "waivers": len(waivers), "retros": len(retros),
+            "residue_gates": len(residue_gates), "residue_disclosed": len(residue_disclosed),
+            "coverage_gaps": len(coverage_gaps),
+            "milestones_live": len(milestones), "milestones_consolidated": len(archived),
+        },
+    }
+
+
+def cmd_graduation_report(args: argparse.Namespace) -> None:
+    """Read-only: GATHER the MVP loop's evidence into five labeled record-sets for the
+    graduate.md interview. text (default) or --json (the frozen JSON facts interface). Exit 0 ALWAYS —
+    a gather, not a gate; the ONLY non-zero exit is no_project. Judges nothing. NO writes."""
+    root = find_root()
+    if root is None:                 # frozen contract: fail-closed with a no_project signal
+        _die("no_project: no .add/ project found. Run `add.py init` first.")
+    state = load_state(root)
+    d = graduation_data(root, state)
+
+    if getattr(args, "json", False):
+        print(json.dumps(d, ensure_ascii=False, indent=2))
+        return
+
+    s = d["summary"]
+    L = ["GRADUATION REPORT — MVP-loop evidence (gather, not judge)", ""]
+    L.append(f"Open deltas ({s['open_deltas']}) — unfolded lessons by competency:")
+    for comp, entries in d["open_deltas"]["by_competency"].items():
+        for e in entries:
+            L.append(f"  - [{comp}] {e['text']}  [{e['task']}]")
+    L.append("")
+    L.append(f"Waivers ({s['waivers']}) — open RISK-ACCEPTED, soonest expiry first:")
+    for w in d["waivers"]:
+        L.append(f"  - {w['slug']}: {w['owner']} · {w['ticket']} · expires {w['expires']}")
+    L.append("")
+    _live_retros = sum(1 for r in d["retros"] if r["tier"] == "live")
+    _cons_retros = s["retros"] - _live_retros
+    L.append(f"RETRO records ({s['retros']}: {_live_retros} live · {_cons_retros} consolidated) — "
+             f"milestones: {s['milestones_live']} live · "
+             f"{s['milestones_consolidated']} represented by RETRO record:")
+    for r in d["retros"]:
+        L.append(f"  - {r['milestone']} [{r['tier']}]: {r['path']} ({r['carried_deltas']} carried)")
+    L.append("")
+    L.append(f"Verify residue — gate records ({s['residue_gates']}, RISK-ACCEPTED/HARD-STOP):")
+    for g in d["residue_gates"]:
+        L.append(f"  - {g['slug']}: {g['gate']}")
+    L.append(f"Verify residue — disclosed §6 lines ({s['residue_disclosed']}):")
+    for r in d["residue_disclosed"]:
+        L.append(f"  - {r['slug']}: {r['line']}")
+    L.append("")
+    L.append(f"Coverage gaps ({s['coverage_gaps']}) — PROXY (monitor not declared; §7 Watch unfilled):")
+    for c in d["coverage_gaps"]:
+        L.append(f"  - {c['slug']}")
+    print("\n".join(L))
+
+
 def cmd_deltas(args: argparse.Namespace) -> None:
-    """Read-only: report all open competency deltas grouped by competency.
+    """Read-only: report all open lessons learned grouped by competency.
 
     Scans every .add/tasks/*/TASK.md '### Competency deltas' block for lines
     matching the delta grammar; shows only `open` entries in canonical competency
@@ -2199,7 +2618,7 @@ def cmd_deltas(args: argparse.Namespace) -> None:
         print("no open deltas.")
         return
 
-    print(f"open competency deltas ({total} total):")
+    print(f"open lessons learned ({total} total):")
     for comp in _COMPETENCY_ORDER:
         entries = by_comp[comp]
         if not entries:
@@ -2324,7 +2743,7 @@ def build_parser() -> argparse.ArgumentParser:
     pi.set_defaults(func=cmd_init)
 
     pl = sub.add_parser("lock",
-                        help="freeze the autonomous setup (the human lock-down) and open the build")
+                        help="freeze the autonomous setup (the human baseline approval) and open the build")
     pl.add_argument("--by", default=None, help="who is locking (default: current OS user)")
     pl.add_argument("--layers", default=None,
                     help="comma-separated lock layers (default: foundation,scope,contract)")
@@ -2371,6 +2790,12 @@ def build_parser() -> argparse.ArgumentParser:
     pam.add_argument("slug")
     pam.set_defaults(func=cmd_archive_milestone)
 
+    pco = sub.add_parser("compact",
+                         help="heavy archive: move an archived milestone's files into "
+                              ".add/archive/<slug>/ (recoverable reverse move)")
+    pco.add_argument("slug")
+    pco.set_defaults(func=cmd_compact)
+
     pp = sub.add_parser("phase", help="set a task's phase explicitly")
     pp.add_argument("phase", choices=PHASES)
     pp.add_argument("slug", nargs="?", default=None)
@@ -2388,8 +2813,18 @@ def build_parser() -> argparse.ArgumentParser:
     pg.add_argument("--expires", help="RISK-ACCEPTED waiver: expiry date")
     pg.set_defaults(func=cmd_gate)
 
+    pr = sub.add_parser("reopen", help="return a done task to an earlier phase with a recorded reason")
+    pr.add_argument("slug", nargs="?", default=None)
+    # --to / --reason are validated in-body (not argparse choices) so the named reject
+    # codes fire (reopen_target_invalid / reopen_reason_required), not a bare exit-2.
+    pr.add_argument("--to", default=None, help="target phase (specify..observe)")
+    pr.add_argument("--reason", default="", help="why the task is reopened (required, non-empty)")
+    pr.set_defaults(func=cmd_reopen)
+
     ps = sub.add_parser("stage", help="set the project stage")
     ps.add_argument("stage", choices=STAGES)
+    ps.add_argument("--force", action="store_true",
+                    help="override the →production roadmap guard (stage_no_roadmap)")
     ps.set_defaults(func=cmd_stage)
 
     pst = sub.add_parser("status", help="print where the project is (resume point)")
@@ -2424,19 +2859,26 @@ def build_parser() -> argparse.ArgumentParser:
     prp.add_argument("--plain", action="store_true",
                      help="ASCII, no color, fixed width (pipe / CI / screen-reader safe)")
     prp.add_argument("--decide", action="store_true",
-                     help="decision-seam digest: what needs the human's judgment NOW "
-                          "(task -> seam digest; milestone -> DECIDE NEXT only; "
+                     help="decision-point digest: what needs the human's judgment NOW "
+                          "(task -> decision digest; milestone -> DECIDE NEXT only; "
                           "bare -> the active task)")
     prp.set_defaults(func=cmd_report)
 
     pdt = sub.add_parser("deltas",
-                         help="read-only report: open competency deltas grouped by competency")
+                         help="read-only report: open lessons learned grouped by competency")
     pdt.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pdt.set_defaults(func=cmd_deltas)
 
+    pgr = sub.add_parser("graduation-report",
+                         help="read-only: gather the MVP loop's evidence (deltas · waivers · RETROs · "
+                              "residue · coverage gaps) for a graduation interview — gathers, never judges")
+    pgr.add_argument("--json", action="store_true", help="emit the frozen JSON facts interface")
+    pgr.add_argument("--plain", action="store_true", help="ASCII/pipe-safe text (output is plain by default)")
+    pgr.set_defaults(func=cmd_graduation_report)
+
     pau = sub.add_parser("audit",
-                         help="read-only: verify human seams left well-formed records "
-                              "(exit 1 on findings — the CI enforcement seam)")
+                         help="read-only: verify recorded human decision points left well-formed records "
+                              "(exit 1 on findings — the CI enforcement gate)")
     pau.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pau.set_defaults(func=cmd_audit)