@pilotspace/add 1.3.0 → 1.5.0

package/tooling/add.py

@@ -19,7 +19,8 @@ import os
 import re
 import sys
 import tempfile
-from datetime import date, datetime, timezone
+import urllib.request
+from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
 # --- constants ---------------------------------------------------------------
@@ -80,7 +81,23 @@ 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")
+SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md")
+
+# 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/,
+# milestones/, archive/). These are working state, not records: scope-snapshot.json
+# is the tests->build touch baseline the verify scope-gate reads from disk (the
+# durable scope declaration is the state.json anchor); pre-archive-state.bak.json is
+# archive-milestone's pre-delete recovery net — needed on disk, never in history;
+# .update-cache.json is the update-nudge's once-a-day registry throttle. All stay on
+# disk; git-ignoring them is hygiene, never deletion.
+_GITIGNORE_BODY = """\
+# ADD engine transient artifacts — local working state, never committed.
+# (Scaffolded by `add.py init`; edit freely — init never clobbers an existing copy.)
+scope-snapshot.json
+pre-archive-state.bak.json
+.update-cache.json
+"""
 
 # 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
@@ -370,6 +387,13 @@ def cmd_init(args: argparse.Namespace) -> None:
         _die(f"already initialised at {root} (use --force to reset state)")
 
     (root / "tasks").mkdir(parents=True, exist_ok=True)
+    # Keep the engine's transient local artifacts out of git. Never-clobber: a
+    # human may have customised .add/.gitignore, so an existing one is left as-is
+    # (mirrors the SETUP_FILES skip-not-clobber idiom). Writes ONLY this file — no
+    # scope-snapshot.json or .bak is created, deleted, or modified.
+    gitignore = root / ".gitignore"
+    if not gitignore.exists():
+        _atomic_write(gitignore, _GITIGNORE_BODY)
     today = date.today().isoformat()
     proj_name = args.name or base.name
 
@@ -456,7 +480,7 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     if _project_autonomy_token(root) == "?":
         print("warning: garbled_project_autonomy — PROJECT.md declares an unrecognized "
               f"autonomy token; new task seeded fail-safe '{autonomy}' "
-              "(set autonomy: manual|conservative|auto in PROJECT.md)", file=sys.stderr)
+              "(fix it with `add.py autonomy set <level> --project`)", file=sys.stderr)
 
     state["tasks"][slug] = {
         "title": title,
@@ -706,8 +730,8 @@ def cmd_gate(args: argparse.Namespace) -> None:
         hdr = _task_header(root, slug)
         if _RISK_HIGH_RE.search(hdr) and not _autonomy_lowered(hdr):
             _die(f"unguarded_high_risk_auto: task '{slug}' declares risk: high "
-                 "without a lowered autonomy level — set autonomy: manual or conservative in "
-                 "the TASK.md header; a human must own a high-risk gate (run.md guard)")
+                 "without a lowered autonomy level — run `add.py autonomy set conservative` "
+                 "(or manual); a human must own a high-risk gate (run.md guard)")
         # tamper tripwire (verify-integrity): the method's first mechanical cheat
         # block. A completing outcome is refused if the red suite or the frozen §3
         # changed since the tests->build snapshot. Placed BEFORE the waiver write so
@@ -738,6 +762,80 @@ def cmd_gate(args: argparse.Namespace) -> None:
     print(_next_footer(root, state))
 
 
+# the autonomy level as a first-class verb (task autonomy-command): autonomy was the ONLY mutable,
+# security-relevant task/project token WITHOUT a CLI verb — so an agent under `auto`, applying the
+# correct "first-class state has a command" model, hallucinated `add.py autonomy` and derailed.
+# `show` reads the resolved level; `set` is the FIRST writer of the header token — idempotent (one
+# declaration line, trailing comment preserved, NEVER appended), with the raise + risk:high guards
+# enforced BEFORE the write. state.json is untouched — autonomy stays a header token.
+_AUTONOMY_ORDER = {lvl: i for i, lvl in enumerate(_AUTONOMY_LEVELS)}   # manual(0) < conservative(1) < auto(2)
+
+
+def _autonomy_decl_line(text: str, level: str) -> str:
+    """Rewrite the SINGLE `autonomy:` declaration line to `level`, PRESERVING its trailing comment,
+    idempotently (replace in place, count=1 — never a second line). If absent, insert it: after the
+    `slug:` line for a task header, else after a leading `#` heading (PROJECT.md), else prepend. PURE
+    on the text; the caller does the atomic write."""
+    pat = re.compile(r"(?m)^(autonomy:[ \t]*)[^\s<#|]+(.*)$")
+    if pat.search(text):
+        return pat.sub(lambda m: f"{m.group(1)}{level}{m.group(2)}", text, count=1)
+    if re.search(r"(?m)^slug:", text):
+        return re.sub(r"(?m)^(slug:.*)$", r"\1\nautonomy: " + level, text, count=1)
+    lines = text.splitlines(keepends=True)
+    if lines and lines[0].lstrip().startswith("#"):
+        return lines[0] + f"autonomy: {level}\n" + "".join(lines[1:])
+    return f"autonomy: {level}\n" + text
+
+
+def _guard_autonomy_raise(current: str, target: str, yes: bool) -> None:
+    """RAISING the level toward `auto` is a human-owned trust escalation (run.md: the AI may LOWER
+    freely — RECOMMEND-only — but RAISING needs a human). Refuse a raise unless --yes confirms it."""
+    if _AUTONOMY_ORDER.get(target, -1) > _AUTONOMY_ORDER.get(current, -1) and not yes:
+        _die(f"autonomy_raise_unconfirmed: raising autonomy {current} -> {target} is a human-owned "
+             "trust escalation (the AI may LOWER freely; RAISING needs a human) — pass --yes to confirm")
+
+
+def _print_autonomy(root: Path, state: dict, slug: str) -> None:
+    """The read-only level view: declared · effective (fallback-resolved) · project default · the
+    verify-gate owner under it (the SAME _driver_stop the footer/guide render). Writes nothing."""
+    declared = _autonomy_level(_task_header(root, slug))
+    stop = _driver_stop(root, state, slug, "verify")
+    print(f"task        : {slug}")
+    print(f"declared    : {declared if declared in _AUTONOMY_LEVELS else 'unset'}")
+    print(f"effective   : {_effective_autonomy(root, state, slug)}")
+    print(f"project     : {_project_autonomy(root)}")
+    print(f"verify gate : {'human gate' if stop else 'you drive'}")
+
+
+def cmd_autonomy(args: argparse.Namespace) -> None:
+    """show / set the autonomy level — the verify-gate owner (task autonomy-command)."""
+    root = _require_root()                                   # reused -> "no .add/ project found …"
+    state = load_state(root)
+    if (getattr(args, "action", None) or "show") == "show":
+        _print_autonomy(root, state, _resolve_task(state, args.a1))   # reused -> "unknown task '<slug>'"
+        return
+    # action == "set"
+    level = args.a1
+    if level not in _AUTONOMY_LEVELS:
+        _die("autonomy_level_invalid: level must be one of "
+             f"{', '.join(_AUTONOMY_LEVELS)} (got {level!r})")
+    if getattr(args, "project", False):
+        target = root / "PROJECT.md"
+        _guard_autonomy_raise(_project_autonomy(root), level, getattr(args, "yes", False))
+        _atomic_write(target, _autonomy_decl_line(target.read_text(encoding="utf-8"), level))
+        print(f"project autonomy -> {level}")
+        return
+    slug = _resolve_task(state, args.a2)                     # reused -> "unknown task '<slug>'"
+    task_md = root / "tasks" / slug / "TASK.md"
+    if _RISK_HIGH_RE.search(_task_header(root, slug)) and level not in ("manual", "conservative"):
+        _die(f"unguarded_high_risk_auto: task '{slug}' declares risk: high — autonomy must stay "
+             f"lowered (manual|conservative); refusing '{level}' (a human must own a high-risk gate)")
+    _guard_autonomy_raise(_effective_autonomy(root, state, slug), level, getattr(args, "yes", False))
+    _atomic_write(task_md, _autonomy_decl_line(task_md.read_text(encoding="utf-8"), level))
+    print(f"task '{slug}' autonomy -> {level}")
+    _print_autonomy(root, state, slug)
+
+
 def cmd_reopen(args: argparse.Namespace) -> None:
     """Return an already-`done` task to an earlier phase with a never-silent record.
 
@@ -918,6 +1016,10 @@ def cmd_status(args: argparse.Namespace) -> None:
     # 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)")
+    # voice pointer — the AI's SOUL (tone · style · trust); read each session, edit freely.
+    # Existence-only: no open/parse, so the pointer adds no IO failure path (a non-file is no voice).
+    if (root / "SOUL.md").exists():
+        print("voice   : .add/SOUL.md  (how I sound & what keeps your trust — read each session)")
     # 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
@@ -1504,6 +1606,27 @@ def _udd_named_set_checks(root: Path) -> list[tuple[bool, str, str]]:
     return out
 
 
+_CAPTURE_EXTS = ("png", "svg", "jpg", "jpeg", "webp")
+
+
+def _missing_captures(root: Path) -> list[str]:
+    """Prototype names under `.add/design/prototypes/` lacking a design-confirm capture.
+
+    A prototype `<name>.json` is CAPTURED iff a file `.add/design/captures/<name>.<ext>`
+    exists (ext in _CAPTURE_EXTS). Returns the uncaptured names in document (sorted) order.
+    PURE · TOTAL (missing dirs -> []) · READ-ONLY (never writes, never renders): the engine
+    MEASURES capture presence; producing the image is the agent's tool-agnostic choice
+    (design.md beat 4; default `@json-render/image`). [] == every prototype captured / none exist.
+    """
+    proto_dir = root / "design" / "prototypes"
+    cap_dir = root / "design" / "captures"
+    if not proto_dir.is_dir():
+        return []
+    names = sorted(p.stem for p in proto_dir.glob("*.json") if p.is_file())
+    return [n for n in names
+            if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Read-only integrity check of the .add project. Exit 1 if anything fails."""
     as_json = getattr(args, "json", False)
@@ -1551,7 +1674,7 @@ def cmd_check(args: argparse.Namespace) -> None:
                        "unknown_autonomy_level (token outside manual|conservative|auto)"))
         if _alvl is None and t.get("phase") not in ("done", "observe"):
             warnings.append((f"task '{slug}'", "has no explicit autonomy level (implicit_autonomy) "
-                             "— set `autonomy: manual|conservative|auto` in the header"))
+                             "— run `add.py autonomy set <level>` to set it"))
         for dep in t.get("depends_on") or []:
             checks.append((dep in tasks or dep in archived_slugs,
                            f"task '{slug}' dep '{dep}' resolves", "unknown task"))
@@ -1670,6 +1793,16 @@ def cmd_check(args: argparse.Namespace) -> None:
     # Silent when absent; read-only; fail-closed on malformed JSON.
     checks.extend(_udd_named_set_checks(root))
 
+    # capture-evidence: a never-red WARN naming each prototype with no design-confirm capture
+    # at .add/design/captures/<name>.<ext>. Measure-never-block — rides `warnings`, NEVER
+    # `checks` (so never feeds `failed`); silent-when-absent (no prototypes -> []). The engine
+    # MEASURES capture presence; producing the image is the agent's tool-agnostic choice.
+    for _pname in _missing_captures(root):
+        warnings.append(("missing_capture",
+                         f"prototype '{_pname}' has no design-confirm capture at "
+                         f".add/design/captures/{_pname}.<png|svg|…> — render + confirm it "
+                         "before build (design.md beat 4)"))
+
     passed = sum(1 for ok, _, _ in checks if ok)
     failed = len(checks) - passed
     if as_json:
@@ -1903,6 +2036,144 @@ def cmd_ready(args: argparse.Namespace) -> None:
         print(f"  {slug}{suffix}")
 
 
+def _wave_schedule(state: dict, mslug: str) -> dict:
+    """Pure, total: derive the DAG schedule for milestone `mslug` from state — never
+    mutates, never raises on dict input. Returns one of:
+      {"cycle": [slug, ...]}                                       — unschedulable cycle
+      {"waves", "critical_path", "critical_path_len", "tiers", "blocked"}  — a schedule
+
+    A dep is SATISFIED (does not block) if it is archived or `_task_done` — the SAME
+    predicate cmd_ready uses. A not-done dep that is an OPEN MEMBER of this milestone
+    forces a later wave. A not-done dep that is NOT an open member (external/unknown)
+    is UNSATISFIABLE here -> the task is `blocked`, never scheduled. Critical path is the
+    longest chain (most tasks) through the scheduled sub-DAG; ties break by sorted slug.
+    Tier is advisory: `top` on the critical path, `mid` elsewhere (scheduled tasks only)."""
+    tasks = state.get("tasks") or {}
+    archived = _archived_task_slugs(state)
+
+    def _ok(d: str) -> bool:                       # satisfied externally / already done
+        return d in archived or (d in tasks and _task_done(tasks[d]))
+
+    open_members = {s: t for s, t in tasks.items()
+                    if t.get("milestone") == mslug and not _task_done(t)}
+
+    # partition open members into blocked vs schedulable — to a FIXED POINT, so blocking
+    # propagates transitively: a task is blocked if any dep is unsatisfiable here, where
+    # unsatisfiable = not _ok AND not a STILL-schedulable member. A dep on an already-blocked
+    # member is itself unsatisfiable, so the dependent blocks too (it would otherwise be
+    # mis-reported as wave-1-ready while its only dep can never complete).
+    blocked: dict[str, list[str]] = {}
+    changed = True
+    while changed:
+        changed = False
+        for s, t in open_members.items():
+            if s in blocked:
+                continue
+            bad = [d for d in (t.get("depends_on") or [])
+                   if not _ok(d) and not (d in open_members and d not in blocked)]
+            if bad:
+                blocked[s] = sorted(set(bad))
+                changed = True
+    schedulable = {s for s in open_members if s not in blocked}
+    blocked_sorted = {k: blocked[k] for k in sorted(blocked)}
+    if not schedulable:
+        # nothing to schedule (all-done, empty, or every open task externally blocked)
+        return {"waves": [], "critical_path": [], "critical_path_len": 0,
+                "tiers": {}, "blocked": blocked_sorted}
+
+    def _member_deps(s: str) -> set[str]:          # deps that are open members forcing order
+        return {d for d in (open_members[s].get("depends_on") or []) if d in schedulable}
+
+    # Kahn waves over the schedulable sub-DAG
+    waves: list[list[str]] = []
+    placed: set[str] = set()
+    remaining = set(schedulable)
+    while remaining:
+        wave = sorted(s for s in remaining if _member_deps(s) <= placed)
+        if not wave:                               # no progress => a cycle among the remaining
+            sub = {s: tasks[s] for s in remaining}
+            cyc = _find_cycle(sub) or sorted(remaining)
+            return {"cycle": cyc}
+        waves.append(wave)
+        placed.update(wave)
+        remaining -= set(wave)
+
+    # critical path = longest chain by memoized depth over member-deps
+    depth: dict[str, int] = {}
+    pick: dict[str, str | None] = {}
+
+    def _depth(s: str) -> int:
+        if s in depth:
+            return depth[s]
+        best_d, best_dep = 0, None
+        for d in sorted(_member_deps(s)):
+            dd = _depth(d)
+            if dd > best_d or (dd == best_d and (best_dep is None or d < best_dep)):
+                best_d, best_dep = dd, d
+        depth[s] = 1 + best_d
+        pick[s] = best_dep
+        return depth[s]
+
+    leaf = min(schedulable, key=lambda s: (-_depth(s), s))  # deepest, tie -> smallest slug
+    chain: list[str] = []
+    cur: str | None = leaf
+    while cur is not None:
+        chain.append(cur)
+        cur = pick.get(cur)
+    critical = list(reversed(chain))               # root -> leaf order
+    crit_set = set(critical)
+    tiers = {s: ("top" if s in crit_set else "mid") for s in sorted(schedulable)}
+    return {"waves": waves, "critical_path": critical, "critical_path_len": len(critical),
+            "tiers": tiers, "blocked": blocked_sorted}
+
+
+def cmd_waves(args: argparse.Namespace) -> None:
+    """READ-ONLY DAG scheduler: print the active milestone's topological waves, critical
+    path, advisory tier hint, and blocked set. Writes nothing; emits no `next:` footer."""
+    is_json = getattr(args, "json", False)
+    if is_json:
+        _, state = _load_state_for_json()
+    else:
+        state = load_state(_require_root())
+    mslug = getattr(args, "milestone", None) or state.get("active_milestone")
+    if not mslug:
+        _die("no_active_milestone: no active milestone and no --milestone given")
+    if mslug not in (state.get("milestones") or {}):
+        _die(f"unknown_milestone: '{mslug}' is not a milestone in this project")
+    sched = _wave_schedule(state, mslug)
+    if "cycle" in sched:
+        _die(f"dependency_cycle: not-done deps form a cycle "
+             f"({' -> '.join(sched['cycle'])}) — no valid schedule")
+
+    if is_json:
+        print(json.dumps({"milestone": mslug, **sched}))
+        return
+
+    print(f"milestone: {mslug}")
+    if not sched["waves"]:
+        if sched["blocked"]:
+            for s in sched["blocked"]:
+                print(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+        else:
+            print("all tasks done — nothing to schedule")
+        return
+    scheduled_set = {x for w in sched["waves"] for x in w}
+    for i, wave in enumerate(sched["waves"], start=1):
+        parts = []
+        for s in wave:
+            md = sorted(d for d in (state["tasks"][s].get("depends_on") or [])
+                        if d in scheduled_set)
+            parts.append(f"{s} (deps: {', '.join(md)})" if md else s)
+        print(f"wave {i}: {', '.join(parts)}")
+    crit = sched["critical_path"]
+    print(f"critical path: {' → '.join(crit)}  ({sched['critical_path_len']} tasks)")
+    tops = [s for s, tier in sched["tiers"].items() if tier == "top"]
+    mids = [s for s, tier in sched["tiers"].items() if tier == "mid"]
+    print(f"tier hint: top → {', '.join(tops)}; mid → {', '.join(mids) or '(none)'}")
+    for s in sched["blocked"]:
+        print(f"blocked: {s} (waiting on {', '.join(sched['blocked'][s])})")
+
+
 def cmd_milestone_done(args: argparse.Namespace) -> None:
     root = _require_root()
     state = load_state(root)
@@ -4019,6 +4290,13 @@ def build_parser() -> argparse.ArgumentParser:
     pr.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pr.set_defaults(func=cmd_ready)
 
+    pwa = sub.add_parser("waves", help="read-only DAG schedule of a milestone: topological "
+                                       "waves + critical path + advisory tier hint")
+    pwa.add_argument("--milestone", default=None,
+                     help="milestone slug to schedule (default: the active milestone)")
+    pwa.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    pwa.set_defaults(func=cmd_waves)
+
     pmd = sub.add_parser("milestone-done", help="exit-gate a milestone (all tasks must PASS)")
     pmd.add_argument("slug")
     pmd.set_defaults(func=cmd_milestone_done)
@@ -4060,6 +4338,16 @@ def build_parser() -> argparse.ArgumentParser:
     pg.add_argument("--expires", help="RISK-ACCEPTED waiver: expiry date")
     pg.set_defaults(func=cmd_gate, _opt_positionals=("slug",))
 
+    pan = sub.add_parser("autonomy", help="show or set the autonomy level (the verify-gate owner)")
+    pan.add_argument("action", nargs="?", choices=("show", "set"), default="show")
+    pan.add_argument("a1", nargs="?", default=None, help="set: <level>; show: [slug]")
+    pan.add_argument("a2", nargs="?", default=None, help="set: [slug]")
+    pan.add_argument("--project", action="store_true",
+                     help="set the PROJECT.md default instead of a task header")
+    pan.add_argument("--yes", action="store_true",
+                     help="confirm a RAISE toward auto (a human-owned trust escalation)")
+    pan.set_defaults(func=cmd_autonomy, _opt_positionals=("a1", "a2"))
+
     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
@@ -4171,11 +4459,120 @@ def _rebind_optional_positionals(parser: argparse.ArgumentParser,
     return args
 
 
+# --- agent-agnostic update nudge --------------------------------------------
+# ADD is agent-agnostic: ANY agent (Claude Code · Gemini CLI · Codex) is told by the
+# guideline block to run `add.py status`/`guide` FIRST, every session. That is the one
+# universal chokepoint to tell a stale install to refresh — a plain line on STDERR the
+# agent reads and acts on. Bounded + fail-open by design (see _maybe_nudge_update).
+#
+# This is the engine's ONE deliberate, isolated network touch. It is justified narrowly:
+# an agent that is offline cannot run at all, so when the network is unreachable this
+# silently does nothing and nothing is lost. It NEVER changes a command's stdout or exit.
+_UPDATE_CACHE = ".update-cache.json"
+_UPDATE_TTL = timedelta(hours=24)          # hit the registry at most once / day
+_REGISTRY_LATEST = "https://registry.npmjs.org/@pilotspace/add/latest"
+
+
+def _read_json_safe(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _write_json_safe(path: Path, obj) -> None:
+    try:
+        path.write_text(json.dumps(obj, indent=2) + "\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def _version_gt(a: str, b: str) -> bool:
+    """True if version a is newer than b (dotted numeric; prerelease suffix dropped)."""
+    def key(v: str):
+        out = []
+        for part in str(v).split("."):
+            part = part.split("-", 1)[0]
+            out.append((0, int(part)) if part.isdigit() else (1, part))
+        return out
+    try:
+        return key(a) > key(b)
+    except Exception:
+        return False
+
+
+def _fetch_latest_version(timeout: float = 1.5):
+    """GET the registry's latest version. Returns a string, or None on ANY failure
+    (offline, timeout, bad payload) — the caller treats None as 'unknown, skip'."""
+    try:
+        req = urllib.request.Request(_REGISTRY_LATEST, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        v = data.get("version")
+        return v if isinstance(v, str) and v else None
+    except Exception:
+        return None
+
+
+def _cached_latest(add_dir: Path):
+    """The registry's latest version, throttled: served from .update-cache.json within
+    the TTL, else refreshed over the network (fail-open). None when unknown."""
+    cache = _read_json_safe(add_dir / _UPDATE_CACHE)
+    if cache and cache.get("latest") and cache.get("checked_at"):
+        try:
+            ts = datetime.fromisoformat(cache["checked_at"])
+            if datetime.now(timezone.utc) - ts < _UPDATE_TTL:
+                return cache["latest"]                     # fresh -> no network
+        except ValueError:
+            pass
+    latest = _fetch_latest_version()
+    if latest:
+        _write_json_safe(add_dir / _UPDATE_CACHE, {
+            "checked_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "latest": latest,
+        })
+        return latest
+    return cache.get("latest") if cache else None          # stale beats nothing
+
+
+def _maybe_nudge_update(args: argparse.Namespace) -> None:
+    """If the tooling is stale, print an ACTION-REQUIRED line to STDERR so the agent
+    updates before the user's task. Fully bounded + fail-open — never raises, never
+    touches stdout or the exit code."""
+    try:
+        if os.environ.get("ADD_NO_UPDATE_CHECK"):
+            return
+        fn = getattr(args, "func", None)
+        # orientation reads only — never a mid-run mutating verb (gate/advance/...)
+        if getattr(fn, "__name__", "") not in ("cmd_status", "cmd_guide"):
+            return
+        add_dir = find_root()
+        if add_dir is None:
+            return
+        stamp = _read_json_safe(add_dir / ".add-version")
+        current = (stamp or {}).get("version")
+        if not current:
+            return            # no launcher stamp -> inert (engine-only/test projects)
+        latest = _cached_latest(add_dir)
+        if not latest or not _version_gt(latest, current):
+            return
+        cmd = ("pipx run pilotspace-add update"
+               if (stamp or {}).get("channel") == "pip"
+               else "npx @pilotspace/add@latest update")
+        sys.stderr.write(
+            f"\n⚠ ADD is out of date: this project is on {current}, latest is {latest}.\n"
+            f"  ACTION REQUIRED before the user's task: run `{cmd}`, then re-read the "
+            f"guide from disk, then continue.\n\n")
+    except Exception:
+        return                # a nudge must NEVER break a command (design-for-failure)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args, extras = parser.parse_known_args(argv)
     if extras:
         args = _rebind_optional_positionals(parser, args, extras)
+    _maybe_nudge_update(args)        # advisory preamble; stderr-only, fail-open
     args.func(args)
     return 0
 

package/tooling/templates/GLOSSARY.md.tmpl

@@ -30,3 +30,7 @@ lowest-confidence flag: the AI's ranked declaration of the 1–2 points most lik
 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").
 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).
+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.

package/tooling/templates/SOUL.md.tmpl

@@ -0,0 +1,40 @@
+# SOUL — Trusting
+
+> The AI's **voice** for {{project}}: how it sounds, how it communicates, and what keeps your trust.
+> This is a **living doc** and it is **human-owned**. The prose below is a **starter** — a proposed
+> default you can rewrite at any time. It is **overridable**, never a frozen claim about who the AI is.
+> The AI proposes voice changes from how you actually talk and work; **your confirm is the only writer**.
+> The observe→confirm→rewrite loop that tunes this file is the `add` skill's `soul-self-improve` path.
+> Edit freely — the engine never clobbers your SOUL.md.
+
+## Name
+**Trusting** — the voice earns trust by showing its work, not by sounding confident.
+
+## Tone
+- Plain and direct; first-principles over jargon. Say the thing, then the why.
+- Calm under uncertainty: name what you don't know instead of writing past it.
+- Warm but not performative — no flattery, no filler, no congratulating the human for asking.
+
+## Communication style
+- Lead with the summary: intent + target first, then the detail.
+- Show before you ask: render the diff / result / artifact, THEN ask the human to decide.
+- Surface tradeoffs and the single lowest-confidence flag; don't hide confusion.
+- Keep it lean: the smallest message that moves the work forward, not more than the work needs.
+
+## Trust
+- Never pre-stamp a human decision — freeze / gate / lock only AFTER the human has answered.
+- Close a disclosed gap before recording a PASS; a security finding is always a hard stop.
+- Report outcomes faithfully: failing tests stay failing in the telling, skipped steps are named.
+- Identity decisions (voice, naming, brand) are the human's — ask open, don't offer a menu of guesses.
+
+## Learns from
+- The human's **wordings** — the words they reach for, and the words they correct you on — and the
+  **flow** of how they actually work (what they skip, what they double-check). NOT their private memory.
+- Each session: read this file when orienting, and notice where your voice diverged from theirs.
+
+## Voice deltas
+The self-improve loop (the `add` skill's `soul.md`) proposes a confirmable **voice delta** when it sees
+a gap between this voice and the human's. Lifecycle `open → confirmed`, like a foundation delta; the
+human's confirm rewrites the sections above (the human is the only writer). Until confirmed, the starter
+voice stands. New confirmed deltas are recorded here newest-first.
+- (no confirmed voice deltas yet)

package/tooling/templates/TASK.md.tmpl

@@ -1,7 +1,7 @@
 # TASK: {{title}}
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
-autonomy: {{autonomy}}   <!-- inherited from the project default (PROJECT.md); explicit level: manual < conservative < auto (visible · overridable) — lower below if a high-risk task needs it. -->
+autonomy: {{autonomy}}   <!-- inherited from the project default (PROJECT.md); explicit level: manual < conservative < auto (visible · overridable) — lower below if a high-risk task needs it, or run `add.py autonomy set`. -->
 phase: ground   <!-- ground -> specify -> scenarios -> contract -> tests -> build -> verify -> observe -> done -->
 <!-- high-risk/method-defining scope? declare `risk: high` on the slug line above and lower the
      autonomy level to `manual` or `conservative` — the engine refuses an unguarded completion

package/tooling/templates/kit.sample.css

@@ -0,0 +1,53 @@
+/* kit.sample.css — one class per catalog.sample.json component (the reusable kit).
+   Every visual value resolves a var(--…) from tokens.sample.css — no literals here, so
+   a token flip in tokens.sample.css restyles every screen that composes from this kit.
+   Screens use these classes and style nothing inline. */
+
+/* Screen — the root viewport container */
+.screen {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-height: 100vh;
+  gap: var(--semantic-space-inset-md);
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+}
+
+/* Card — a surface that groups related content */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--semantic-space-inset-sm);
+  width: 100%;
+  max-width: 360px;
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  border-radius: var(--semantic-space-inset-sm);
+}
+
+/* Text — a run of styled text */
+.text {
+  margin: 0;
+  line-height: 1.5;
+  color: var(--semantic-color-text);
+  font-family: var(--primitive-font-family-sans);
+}
+.text--bold { font-weight: var(--primitive-font-weight-bold); }
+.text--regular { font-weight: var(--primitive-font-weight-regular); }
+
+/* Button — a primary call-to-action */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--semantic-space-inset-sm) var(--semantic-space-inset-md);
+  border: 0;
+  border-radius: var(--semantic-space-inset-sm);
+  background: var(--semantic-color-accent);
+  color: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+  font-weight: var(--primitive-font-weight-bold);
+  cursor: pointer;
+}

package/tooling/templates/settings.sample.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<!-- settings.sample.html — a SECOND screen that proves REUSE. It composes from the SAME
+     kit classes (screen/card/text/button) and links the SAME tokens.sample.css +
+     kit.sample.css as welcome. It redefines nothing — no per-screen stylesheet, no inline
+     styles — so a single semantic-token flip in tokens.sample.css re-renders BOTH screens
+     identically. This is consistency by construction. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Settings — design mock</title>
+  <link rel="stylesheet" href="tokens.sample.css">
+  <link rel="stylesheet" href="kit.sample.css">
+</head>
+<body>
+  <!-- reuses the welcome kit: Screen > Card > {Text, Text, Button} -->
+  <main class="screen">
+    <section class="card">
+      <h1 class="text text--bold">Settings</h1>
+      <p class="text text--regular">Manage your workspace preferences.</p>
+      <button class="button" type="button">Save changes</button>
+    </section>
+  </main>
+</body>
+</html>