@pilotspace/add 1.10.0 → 1.12.0

package/tooling/add_engine/predicates.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""add_engine.predicates — pure state/markdown predicates for the ADD engine.
+
+Phase ownership, setup/milestone gating checks, and section-filled detection.
+Extracted from add.py (engine-modularization 5/N); add.py re-exports them as module
+globals so `add._phase_owner` etc. resolve unchanged.
+"""
+from __future__ import annotations
+
+import re
+
+from add_engine.constants import PHASE_OWNER
+from add_engine.io_state import _die
+
+
+def _phase_owner(phase: str) -> str:
+    """Map a phase to its owner (human|seam|ai); `unmapped_phase` if absent (fail closed)."""
+    owner = PHASE_OWNER.get(phase)
+    if owner is None:
+        _die("unmapped_phase")
+    return owner
+
+def _setup_locked(state: dict) -> bool:
+    """True when the project's setup is locked — i.e. the build-boundary gate is OPEN.
+
+    A state with NO "setup" key is GRANDFATHERED-locked: plain `init` and every legacy
+    project are never gated (the lock is opt-in via `init --await-lock`). The gate is
+    therefore active in exactly one case: "setup" present AND locked is False."""
+    return ("setup" not in state) or (state["setup"].get("locked") is True)
+
+def _milestone_confirmed(state: dict, mslug: str) -> bool:
+    """True when milestone `mslug` is confirmed — i.e. the new-task gate is OPEN.
+
+    Mirrors `_setup_locked` one level down. A milestone record with NO "confirmed" key is
+    GRANDFATHERED-confirmed: every milestone created WITHOUT `--await-confirm` (and every
+    pre-existing one) is never gated. Opt-in: `new-milestone --await-confirm` seeds confirmed:false,
+    so the gate is active in exactly one case: the record is present AND confirmed is False. An
+    unknown milestone is treated as confirmed here (existence is cmd_new_task's separate check)."""
+    m = (state.get("milestones") or {}).get(mslug)
+    if not isinstance(m, dict) or "confirmed" not in m:
+        return True
+    return m["confirmed"] is True
+
+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)."""
+    body, in_sec, present = [], False, False
+    for ln in md_text.splitlines():
+        if ln.startswith(header):
+            in_sec, present = True, True
+            continue
+        if in_sec:
+            if ln.startswith("#"):          # ANY next header (## or ###) ends our section
+                break
+            if ln.lstrip().startswith(">"):  # skip blockquote GUIDANCE — it is not content
+                continue
+            body.append(ln)
+    if not present:
+        return False                        # absent -> grandfather
+    text = "\n".join(body).strip()
+    if not text:
+        return True                         # present but empty
+    return bool(re.search(r"<[^>\n]+>", text))   # a <…> placeholder remains
+
+
+def _task_done(t: dict) -> bool:
+    # Matrix 3: a task is done when Verify reads PASS *or a signed RISK-ACCEPTED*.
+    # Both completing gates advance phase to "done" (cmd_gate), and a waiver is
+    # signed at gate time — so a verdict gate is enough here; we need not re-read
+    # the waiver. HARD-STOP never reaches "done". A bare `phase done` (escape
+    # hatch, gate still "none") deliberately does NOT count: completion needs a
+    # recorded verdict, not just a phase marker.
+    return t.get("phase") == "done" and t.get("gate") in ("PASS", "RISK-ACCEPTED")

package/tooling/add_engine/release.py

@@ -0,0 +1,86 @@
+"""add_engine.release — the RELEASE-pillar render helpers (engine-modularization 14/N).
+
+Render the CHANGELOG block and the append-only RELEASES.md attribution row, locate the
+ledger, find closed milestones / key decisions for a cut, and summarise the in-flight build.
+A closed, unpatched cluster (transitive-closure AST = zero outbound). Deps: constants + stdlib.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from add_engine.constants import RELEASES_FILE
+
+
+def _releases_path(root: Path) -> Path:
+    """The append-only release ledger — at the PROJECT ROOT (root IS the .add dir, so its
+    parent), a sibling of CHANGELOG.md. NOT inside .add/."""
+    return root.parent / RELEASES_FILE
+
+def _closed_milestones(state: dict) -> list[dict]:
+    """Every CLOSED milestone (its milestone-done gate passed): LIVE done milestones
+    (status == 'done', still in state) + ARCHIVED milestones (all were PASS-done before
+    archive — see _archived_task_slugs). Each: {slug, title, tier}."""
+    out: list[dict] = []
+    for slug, m in (state.get("milestones") or {}).items():
+        if m.get("status") == "done":
+            out.append({"slug": slug, "title": m.get("title", slug), "tier": "live"})
+    for rec in state.get("archived") or []:
+        if rec.get("slug"):
+            out.append({"slug": rec["slug"], "title": rec.get("title", rec["slug"]),
+                        "tier": "archived"})
+    return out
+
+def _key_decisions_for(root: Path, slug: str) -> list[str]:
+    """Best-effort §Key-Decisions rows from PROJECT.md that NAME this milestone slug — the
+    consolidated decisions the changelog can cite. Fail-open: a missing section / unreadable
+    foundation / no slug match -> [] (a gather never raises). READ-ONLY."""
+    try:
+        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+    except OSError:
+        return []
+    m = re.search(r"^#{1,6}[^\n]*key decision[^\n]*$(.*?)(?=^#{1,6}\s|\Z)", text, re.S | re.M | re.I)
+    if not m:
+        return []
+    return [st.lstrip("-* ").strip() for st in (ln.strip() for ln in m.group(1).splitlines())
+            if st.startswith(("-", "*")) and slug in st]
+
+def _build_in_flight(state: dict) -> bool:
+    """release_tests_red proxy (PURE): is any ACTIVE task mid-build without a recorded green gate
+    — phase ∈ {build, verify} AND gate == 'none'? The tool-agnostic engine never runs the suite,
+    so an entered-but-ungated build is the recorded-evidence stand-in for 'the suite is red'."""
+    return any(t.get("phase") in ("build", "verify") and t.get("gate") == "none"
+               for t in (state.get("tasks") or {}).values())
+
+def _render_changelog_block(version: str, day: str, bundle: list[dict],
+                            changed_by_slug: dict) -> str:
+    """A CHANGELOG block: `## <version> — <date>` + one bullet per bundled milestone (title +
+    carried-delta / key-decision counts from release_data['changed'])."""
+    lines = [f"## {version} — {day}", ""]
+    if bundle:
+        for m in bundle:
+            c = changed_by_slug.get(m["slug"], {})
+            lines.append(f"- {m['title']} — {c.get('carried_deltas', 0)} carried · "
+                         f"{len(c.get('key_decisions', []))} key decision(s)")
+    else:
+        lines.append("- (no milestone bundled)")
+    return "\n".join(lines) + "\n\n"
+
+def _render_releases_row(version: str, day: str, bundle: list[dict],
+                         waiver_slugs: list[str], evidence: str | None,
+                         actor: str | None = None, loose: list[dict] | None = None) -> str:
+    """One append-only RELEASES.md row — the attribution source (`milestones:` membership +,
+    additively, `loose tasks:` membership for done milestone-free standalones). The `actor:`
+    line records WHO cut the release (structured-actor stamping); absent on a legacy row
+    (back-compat) when no actor is supplied. `loose` defaults to None so existing callers keep
+    working; the `loose tasks:` line always renders (`none` when empty), the other lines unchanged."""
+    ms = ", ".join(m["slug"] for m in bundle) if bundle else "none"
+    lt = ", ".join(t["slug"] for t in loose) if loose else "none"
+    wv = ", ".join(waiver_slugs) if waiver_slugs else "none"
+    actor_line = f"actor: {actor}\n" if actor else ""
+    return (f"## {version} — {day}\n"
+            f"milestones: {ms}\n"
+            f"loose tasks: {lt}\n"
+            f"waivers: {wv}\n"
+            f"{actor_line}"
+            f"evidence: {evidence or 'recorded by add.py release'}\n\n")

package/tooling/add_engine/render.py

@@ -0,0 +1,90 @@
+"""add_engine.render — terminal-render primitives (engine-modularization 9/N).
+
+Progress bars, the phase track, ASCII/Unicode + color tiers, clip/wrap. A closed,
+unpatched cluster (transitive-closure AST = zero outbound calls). The render-private
+_ANSI palette lives here; the SHARED _DEFAULT_WIDTH is imported from constants (its
+single source — the staying report default-args use it too).
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+
+from add_engine.constants import PHASES, _DEFAULT_WIDTH
+
+_ANSI = {"green": "\x1b[32m", "yellow": "\x1b[33m", "red": "\x1b[31m",
+         "dim": "\x1b[2m", "reset": "\x1b[0m"}
+
+
+def _bar(num: int, den: int, cells: int, g: dict) -> str:
+    """A progress bar; 0/0 -> all-empty (no divide-by-zero)."""
+    filled = 0 if den <= 0 else round(num / den * cells)
+    filled = max(0, min(cells, filled))
+    return g["reached"] * filled + g["pending"] * (cells - filled)
+
+def _phase_track(phase: str, g: dict) -> str:
+    """Compact 9-cell pipeline (no labels — a single legend explains it):
+    reached · current · pending. A done task -> all reached."""
+    try:
+        ci = PHASES.index(phase)
+    except ValueError:
+        ci = 0
+    cells = []
+    for i in range(len(PHASES)):
+        if phase == "done" or i < ci:
+            cells.append(g["reached"])
+        elif i == ci:
+            cells.append(g["current"])
+        else:
+            cells.append(g["pending"])
+    return "".join(cells)
+
+def _use_ascii() -> bool:
+    """ASCII tier when the terminal can't render Unicode (non-UTF-8 / dumb)."""
+    enc = (getattr(sys.stdout, "encoding", "") or "").lower()
+    return ("utf" not in enc) or (os.environ.get("TERM") == "dumb")
+
+def _color_enabled() -> bool:
+    """Color only on an interactive tty, honoring NO_COLOR and TERM."""
+    return (sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+            and os.environ.get("TERM", "") not in ("dumb", ""))
+
+def _term_width() -> int:
+    try:
+        import shutil
+        return min(max(shutil.get_terminal_size().columns, 64), 100)
+    except Exception:
+        return _DEFAULT_WIDTH
+
+def _colorize(s: str) -> str:
+    """Apply ANSI to status tokens — redundant to the text, never the sole signal.
+    Applied ONLY to tty stdout; the persisted RETRO.md string stays plain."""
+    c = _ANSI
+    s = re.sub(r"\bDONE\b", c["green"] + "DONE" + c["reset"], s)
+    s = re.sub(r"\bBLOCKED\b", c["red"] + "BLOCKED" + c["reset"], s)
+    s = re.sub(r"\bPASS\b", c["green"] + "PASS" + c["reset"], s)
+    s = re.sub(r"\bRISK\b", c["yellow"] + "RISK" + c["reset"], s)
+    s = re.sub(r"\bSTOP\b", c["red"] + "STOP" + c["reset"], s)
+    return s
+
+def _clip(s: str, maxlen: int) -> str:
+    """Trim a string to fit a fixed-width frame, ellipsizing if it overruns."""
+    return s if len(s) <= maxlen else s[:maxlen - 1].rstrip() + "…"
+
+def _wrap(text: str, width: int, label: str) -> list[str]:
+    """Wrap `text` to `width`; the first line carries `label`, continuations are
+    blank-indented to the same width (so a multi-line goal shows 'goal' once)."""
+    cont = " " * len(label)
+    lines, cur = [], ""
+    for w in text.split():
+        if cur and len(cur) + 1 + len(w) > width:
+            lines.append(cur)
+            cur = w
+        else:
+            cur = f"{cur} {w}".strip()
+    if cur:
+        lines.append(cur)
+    lines = lines or ["(unknown)"]
+    return [(label if i == 0 else cont) + ln for i, ln in enumerate(lines)]

package/tooling/add_engine/taskdoc.py

@@ -0,0 +1,217 @@
+"""add_engine.taskdoc — TASK.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
+(transitive-closure AST = zero outbound). The 3 delta-parsing regexes are SHARED with the
+deltas-web lint, so they live in constants.py (single source). Deps: constants + components
+(_confined) + stdlib; no add.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from add_engine.constants import _DELTA_RE, _EVIDENCE_RE, _SPEC_DELTA_RE
+from add_engine.components import _confined
+
+
+def _task_header(root: Path, slug: str) -> str:
+    """The TASK.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")
+    except OSError:
+        return ""
+    return re.sub(r"<!--.*?-->", "", text.split("\n## ", 1)[0], flags=re.S)
+
+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."""
+    try:
+        return len(re.findall(r"^\s*def test_", f.read_text(encoding="utf-8"), re.M))
+    except OSError:
+        return 0
+
+def _primary_test_files(root: Path, slug: str) -> list[Path]:
+    """The PRIMARY test set — *.py directly in the task's tests/ dir (the stable
+    path). A list so the tamper tripwire can hash exactly what the engine counts."""
+    d = root / "tasks" / slug / "tests"
+    if not d.is_dir():
+        return []
+    return sorted(d.glob("*.py"))
+
+def _tests_count(root: Path, slug: str) -> int:
+    return sum(_count_test_defs(f) for f in _primary_test_files(root, slug))
+
+def _declared_test_files(root: Path, slug: str) -> list[Path]:
+    """Resolve the §4 'Tests live in:' declared path(s) to a deduped file list. PURE.
+    Tokens are the backticked spans on the FIRST declaring line of the raw §4 body.
+    Resolution: './…' -> task dir · contains '/' -> project root (parent of .add) ·
+    bare name -> sibling of the previous resolved token (else task dir). A directory
+    token yields the *.py files directly inside it; resolved files are deduped.
+    v2 confinement: every path must resolve inside the project root — '..' traversal,
+    absolute tokens, and symlink escapes are all dropped, fail-closed."""
+    body = _raw_phase_bodies(root, slug).get(4, "")
+    m = re.search(r"^\s*Tests live in:.*$", body, re.M)
+    if not m:
+        return []
+    tdir = root / "tasks" / slug
+    rootp = root.parent.resolve()
+    files: list[Path] = []
+    prev_dir = None
+    for tok in re.findall(r"`([^`]+)`", m.group(0)):
+        tok = tok.strip()
+        if tok.startswith("./"):
+            p = tdir / tok[2:]
+        elif "/" in tok:
+            p = root.parent / tok
+        else:
+            p = (prev_dir or tdir) / tok
+        try:
+            if not _confined(p, rootp):
+                continue
+            if p.is_dir():
+                cand, prev_dir = sorted(f for f in p.glob("*.py")
+                                        if _confined(f, rootp)), p
+            elif p.is_file() and p.suffix == ".py":
+                cand, prev_dir = [p], p.parent
+            else:
+                continue
+        except OSError:
+            continue
+        files.extend(f for f in cand if f not in files)
+    return files
+
+def _declared_tests_count(root: Path, slug: str) -> int:
+    """Count tests at the §4 'Tests live in:' declared path(s). PURE, fail-closed 0."""
+    return sum(_count_test_defs(f) for f in _declared_test_files(root, slug))
+
+def _tests_info(root: Path, slug: str) -> tuple[int, bool]:
+    """(count, declared). The tests/ dir count ALWAYS wins when > 0; otherwise the
+    §4-declared fallback — flagged True only when it supplied a non-zero count, so
+    a true zero stays a bare, honest 0."""
+    primary = _tests_count(root, slug)
+    if primary > 0:
+        return primary, False
+    declared = _declared_tests_count(root, slug)
+    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
+    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"
+    if not f.exists():
+        return "(unknown)", []
+    text = f.read_text(encoding="utf-8")
+    m7 = re.search(r"##\s*7\s*·\s*OBSERVE.*\Z", text, re.S)
+    section = m7.group(0) if m7 else text
+    lines = section.splitlines()
+    # observe: prefer the first OPEN SPEC delta from the "### Spec delta" block; fall
+    # back to the legacy "Spec delta for the next loop:" free-text field (archived
+    # tasks predate the block); else "(unknown)".
+    observe = "(unknown)"
+    for unit in _spec_delta_entries(section):
+        m = _SPEC_DELTA_RE.match(unit[0])
+        if m.group(2) != "open":
+            continue
+        tail = " ".join([m.group(3).strip(), *unit[1:]]).strip()
+        em = _EVIDENCE_RE.match(tail)
+        first = (em.group(1).strip() if em else tail)
+        if first and not first.startswith("<"):
+            observe = first
+            break
+    if observe == "(unknown)":
+        for i, ln in enumerate(lines):
+            m = re.match(r"\s*Spec delta for the next loop:\s*(.*)", ln)
+            if not m:
+                continue
+            parts = [m.group(1).strip()]
+            for nxt in lines[i + 1:]:
+                t = nxt.strip()
+                if not t or t.startswith("#") or t.startswith("- ") or t.startswith("Watch"):
+                    break
+                parts.append(t)
+            joined = " ".join(p for p in parts if p).strip()
+            if joined and not joined.startswith("<"):
+                observe = joined
+            break
+
+    # deltas: each "- [COMP · status] ..." plus its indented continuation lines
+    deltas, i = [], 0
+    while i < len(lines):
+        m = _DELTA_RE.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        parts, j = [m.group(3).strip()], i + 1
+        while j < len(lines):
+            t = lines[j].strip()
+            if not t or t.startswith("#") or _DELTA_RE.match(lines[j]):
+                break
+            parts.append(t)
+            j += 1
+        deltas.append(f"{m.group(1)} · {m.group(2)} · {' '.join(parts).strip()}")
+        i = j
+    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
+    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)."""
+    lines = text.splitlines()
+    head = re.compile(r"^##\s*(\d+)\s*·")
+    starts: dict[int, int] = {}
+    for idx, ln in enumerate(lines):
+        m = head.match(ln)
+        if m:
+            n = int(m.group(1))
+            if 0 <= n <= 7 and n not in starts:
+                starts[n] = idx
+    out: dict[int, str] = {}
+    for n, idx in starts.items():
+        body_lines = []
+        for ln in lines[idx + 1:]:
+            if re.match(r"^##\s", ln) or re.match(r"^---\s*$", ln):
+                break
+            body_lines.append(ln)
+        out[n] = "\n".join(body_lines)
+    return out
+
+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"
+    try:
+        return _phase_spans(f.read_text(encoding="utf-8"))
+    except OSError:
+        return {}
+
+def _spec_delta_entries(text: str) -> list[list[str]]:
+    """Group a "### Spec delta" block into entries (tag line + continuation lines).
+
+    Same grouping discipline as _collect_open_deltas' competency pass, keyed on
+    _SPEC_DELTA_RE: a tag line starts an entry; a non-"- " line continues it; a
+    blank/comment or a new "- " item ends it. Returns [] when the block is absent."""
+    bm = re.search(r"###\s*Spec delta\s*\n(.*?)(?=\n##|\Z)", text, re.S)
+    if not bm:
+        return []
+    entries: list[list[str]] = []
+    current: list[str] | None = None
+    for line in bm.group(1).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("<!--"):
+            current = None
+            continue
+        if _SPEC_DELTA_RE.match(stripped):
+            current = [stripped]
+            entries.append(current)
+        elif current is not None and not stripped.startswith("-"):
+            current.append(stripped)         # genuine wrap of the current entry
+        else:
+            current = None                   # a new / malformed list item ends the run
+    return entries

package/tooling/add_engine/version.py

@@ -0,0 +1,45 @@
+"""add_engine.version — the npm/PyPI update-nudge version helpers (engine-modularization 13/N).
+
+Safe JSON read, semantic-ish version compare, and a fail-soft registry fetch (timeout-bounded,
+never raises into the nudge path). A closed cluster: the three functions don't call each other.
+The cluster-private _REGISTRY_LATEST (the npm 'latest' URL) lives here. Deps: stdlib only.
+"""
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+_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 _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

package/tooling/templates/DESIGN.md.tmpl

@@ -31,6 +31,17 @@ The design intent the AI drafts UI against — the persona, the one job, the fee
 - **Design principles** — <!-- 3–5 lines, e.g. "one primary action per screen" · "never hide state" -->
 - **Accessibility floor** — <!-- e.g. WCAG AA contrast · focus-visible · hit-target ≥ 44px -->
 
+## Design intake
+
+The per-design picks the `design-intake` beat collects (see the `add` skill's `design.md`).
+These are project **defaults**; a screen records only its **overrides** in its prototype note.
+VISUAL DESIGN draws its color/type from **## Identity** above — don't restate the brand here.
+
+- **Fidelity** — <!-- lo-fi wireframe | hi-fi mockup | production — how far this design renders -->
+- **Concept** — <!-- the design idea / mood / direction, in a line -->
+- **Layout** — <!-- the structure / grid / hierarchy the screens lean on -->
+- **Visual design** — <!-- spacing scale · imagery style (color · type come from ## Identity) -->
+
 ## Screens
 
 An index of the app's screens — one `design/prototypes/<name>.json` per screen (a flat

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

@@ -14,6 +14,8 @@ fast: true   <!-- the fast lane: a small task, collapsed flow + minimal template
 ## 0 · GROUND — the real codebase
 
 Touches (files · symbols): <path:symbol — what it is / how it is keyed>
+Context (working folder): <docs · config · data the task touches — task-delta only>
+Honors (patterns / conventions): <PROJECT.md / CONVENTIONS.md anchors — task-delta>
 Anchors the contract cites: <the symbols §3 will name>
 
 ---

package/tooling/templates/gitignore.tmpl

@@ -0,0 +1,6 @@
+# ADD engine transient artifacts — local working state, never committed.
+# (Scaffolded by `add.py init`; refreshed additively by the installer on update.)
+scope-snapshot.json
+pre-archive-state.bak.json
+pre-update-state.bak.json
+.update-cache.json