@pilotspace/add 1.16.1 → 2.0.0

package/skill/add/streams.md

@@ -1,268 +0,0 @@
-# Parallel streams — pipelining independent tasks
-
-Load this when a milestone has more than one task and you want to run them concurrently.
-**Default:** when a project confirms `parallel + auto` as its run mode at setup
-(`phases/0-setup.md` "Run mode"), parallel streaming is the project default — an **opt-out**, not
-the opt-in it once was; downgrade in one step (`add.py autonomy set conservative --project`, or
-just run tasks one at a time). A project that kept the conservative run mode still treats this
-rubric as the opt-in escape hatch.
-
-It changes **no `add.py` code and no phase semantics**. It is a way *you, the orchestrator*,
-drive several tasks at once by reading the dependency DAG `add.py status` already prints and
-spawning one worker per ready task.
-
-## The honest frame — this is pipelining, not N× speed
-
-With **one human reviewer** you cannot beat `review_time × N_tasks` (decision points are serial).
-The win: the reviewer is **never blocked waiting on a build** — builds for B·C·D run behind *their*
-frozen contracts while the human reviews A. Build latency hides under human latency.
-
-## The two queues
-
-Both from one `add.py status` — no new state:
-
-- **READY-QUEUE** — tasks where `phase ≠ done` **and** every `deps=` task shows `gate=PASS`.
-  Unmet deps stay queued; a PASS unblocks dependents.
-- **REVIEW-QUEUE** — the serial part: **bundle approval** (contract freeze) + any **Verify
-  escalation**. One human, one queue; present one at a time, never batched.
-
-```
-  add.py status ─► READY-QUEUE ──spawn workers──► builds run ──► REVIEW-QUEUE ──► done
-  (deps=PASS?)     (machine span)                 (concurrent)   (decision points, serial)
-       ▲
-       └──────── a task gating PASS unblocks its dependents ──────────────────────────┘
-```
-
-## The DAG strategy — let the engine schedule the waves (`add.py waves`)
-
-Do **not** eyeball the READY-QUEUE by hand once a milestone has more than a couple of tasks.
-`add.py waves` (read-only) groups not-done tasks into **topological waves**, names the **critical
-path**, and emits an advisory **tier hint**:
-
-```
-$ add.py waves
-milestone: v13-onboarding-polish
-wave 1: dag-scheduler, setup-suggest-milestone, setup-domain-deepdive, soul-artifact
-wave 2: setup-run-mode (deps: dag-scheduler), soul-self-improve (deps: soul-artifact)
-critical path: dag-scheduler → setup-run-mode  (2 tasks)
-tier hint: top → dag-scheduler, setup-run-mode; mid → the rest
-```
-
-- **Wave = a fan-out batch.** Every task in a wave has all in-milestone deps PASS, so the whole
-  wave is spawnable at once (`isolation="worktree"`). Finish a wave, gate tasks PASS, then
-  `add.py waves` again — the next wave is unblocked.
-- **Run the widest wave first** to hide the most build latency under human review latency.
-- **Spend your strongest model on the critical path.** Critical-path tasks gate the most
-  downstream work; off-path tasks take **mid**. The tier hint is advisory — override when you
-  know a task is harder than its position suggests.
-- **Prefer the named roster per worker** — `add-build` for a tests/build-phase worker, `add-design`
-  for design-phase, `add-verify` for verify-phase (full roster + when-to-spawn in advisor.md) — over
-  a generic ad-hoc spawn.
-- **`--json`** (`{ milestone, waves, critical_path, critical_path_len, tiers, blocked }`) feeds
-  a runner that spawns programmatically. `blocked` lists tasks whose dep cannot be satisfied
-  within this milestone; a `dependency_cycle` is refused with the offending members named.
-
-The irreducible floor holds — `waves` decides *order and model*, never *whether the human gate fires*.
-
-## The autonomy level is the throttle (not a new flag)
-
-| `autonomy` (TASK.md) | What serializes on the human | Concurrency |
-|----------------------|------------------------------|-------------|
-| `conservative` / `manual` | bundle approval **+** every Verify | pure pipelining — builds overlap, both gates queue |
-| `auto` (default) | bundle approval **only**; Verify auto-PASSes on evidence | real concurrency — only the decision point + residue escalations queue |
-| `auto` but **high-risk** | refused → must lower (`unguarded_high_risk_auto`) | back to pipelining, by design |
-
-The irreducible floor is **one human approval per task at the contract decision point** — that
-floor never drops to zero (`run.md:22`). Do not engineer around it.
-
-## Who writes what — the hard boundary
-
-<constraints>
-- **You (orchestrator)** own all shared writes: `MILESTONE.md`, and every `add.py advance <slug>` /
-  `add.py gate <outcome> <slug>` call. Always pass the explicit `<slug>` — **name the task every time** —
-  omitting it falls back to the single `active_task`, which races once more than one stream is live.
-  Workers never run these.
-- **A worker** owns only its own `.add/tasks/<slug>/` — it builds `src/`, drives tests green,
-  gathers evidence, and writes `SUMMARY.md` + OBSERVE deltas. It touches **no sibling stream and
-  no shared file** — never write shared state (state.json, MILESTONE.md, a sibling's files).
-- **Isolation**: spawn each worker with `isolation="worktree"` so concurrent builds cannot
-  collide. The worktree is discarded on failure; the task resets to its last-good phase.
-</constraints>
-
-## Design for failure (required)
-
-- **Fresh worktree base (verify base == HEAD)** — cut each worktree from current `HEAD` **after**
-  committing the frozen bundle; confirm `git -C <worktree> rev-parse HEAD` equals the orchestrator's
-  `HEAD` (drifted → `git merge` first). On a pool runner (e.g. Claude Code) the check **shifts** to
-  the worker's **step-0** (sync + re-echo `rev-parse HEAD`), verified at **merge-time**. The engine
-  gates this (`engine-merge-base-enforcement`): `add.py wave-verify` before the first merge-back
-  refuses a mismatched/pending echo (`unverified_fork_base`) or off-template ledger
-  (`wave_ledger_malformed`); `add.py check` is the standing monitor.
-- **Materialize gitignored engine content** — `git worktree add` checks out TRACKED files only;
-  `.add/tooling` (engine) and `.add/docs` (book) are gitignored and will be ABSENT even when the
-  worktree's HEAD matches — copy them in before the worker's first `add.py` call, or its
-  `phase`/`advance` commands have no engine to run at all (confirmed 3-for-3 this session).
-- **Lease + timeout** — record which worker holds which task (wave ledger); a dead worker releases
-  its claim back to READY.
-- **Failure isolates** — a worker's STOP-and-escalate blocks only its own task; siblings run on, the
-  escalation joins the REVIEW-QUEUE.
-- **Circuit-breaker** — if N workers fail in a wave, stop fanning out and fall back to sequential.
-  Repeated failure means the scope was wrong, not the parallelism.
-
-## Wave ledger — the wave's resume point
-
-**The file** — `.add/milestones/<m>/WAVE.md`, orchestrator-owned. ONE live wave per milestone;
-opening a second while one is live is refused (`wave_already_live`). **Workers never read
-WAVE.md** — the orchestrator copies relevant decisions into each worker's PROMPT.md at spawn.
-
-```markdown
-# WAVE.md — transient wave ledger (orchestrator-owned · one live wave per milestone)
-wave: <n> · opened: <date> · status: live|merging
-base: <orchestrator HEAD at spawn — the sha every fork must equal>
-
-### Roster (lease ledger)
-| task   | lease (worker) | fork-base (pasted)                          | autonomy | spawned | timeout |
-|--------|----------------|---------------------------------------------|----------|---------|---------|
-| <slug> | wt-a           | <paste `git -C <wt> rev-parse HEAD` output> | auto     | <time>  | <dur>   |
-
-### Mid-wave decisions
-- <date> <decision a later or respawned worker must honor — copy it into that worker's PROMPT.md>
-
-### Merge order (serial; integration Verify per merge)
-1. <slug> → 2. <slug>
-```
-
-**Evidence cells, not ticks.** The fork-base cell holds the PASTED output of
-`git -C <worktree> rev-parse HEAD` and must equal `base:`. Filling the row requires running the
-command — words-exist ≠ method-works. Spawning a worker whose roster row lacks that evidence is
-refused (`unverified_fork_base`). On a pool runner the cell holds the worker's **step-0**
-post-sync echo (still `== base:`) and the refusal **shifts to merge-time**.
-
-**Lifecycle — open → consume → digest → delete.** Open when the first worker spawns. At wave
-close, absorb the evidence digest — base · roster fork-base · merge order · integration-Verify
-outcome — into `MILESTONE.md` as an append-only `## Wave log` block, then remove the file.
-Removing WAVE.md before the digest is absorbed is refused (`digest_not_absorbed`).
-
-**Resume rule.** On session start, a live WAVE.md is the wave's resume point: re-orient from the
-file — roster, bases, decisions, merge order — never from conversational memory.
-
-## Merge is serial — integration Verify
-
-Parallel build, **serial integration**. After workers return, merge worktrees one at a time and
-run the **integration** Verify — the concurrency / architecture / layering checks automation
-cannot judge. Two green tasks in isolation can still conflict when merged. Never auto-pass it.
-
-Each worktree carries a full copy of `.add/`. Merge back **only** `src/`, `tests/`, and the
-worker's own `.add/tasks/<slug>/` (TASK.md · SUMMARY.md) — `.add/state.json`, `MILESTONE.md`,
-and the live `WAVE.md` stay orchestrator-owned.
-
-## The worker contract — portable across coding agents
-
-A worker **is** the dynamic run (`run.md`) for one task. The contract below is **agent-agnostic**:
-no vendor tool, no model, no spawn API — a durable ADD artifact. The adapter (next sections) is
-the thin, swappable mapping for one runner. Fill every `{{...}}` per stream.
-
-```xml
-<!-- PROMPT.md — dropped into the worker's worktree, or passed inline. No runner-specific tokens. -->
-<objective>
-Execute the LOCKED dynamic run for task '{{TASK_SLUG}}' in milestone {{MILESTONE}}:
-drive §4 TESTS red→green against the FROZEN contract {{CONTRACT_VERSION}}, converge, and
-resolve verify per autonomy={{AUTONOMY}}. You own ONLY the machine-led span — the two human
-decision points (bundle approval · escalated Verify) are NOT yours.
-</objective>
-
-<persona>
-Load `.add/personas/{{PERSONA_SLUG}}.md` (Identity→you · Critical Rules→constraints · Success
-Metrics→done-bar); no match → the generic default below. Portable body + per-runner spawn stubs:
-`templates/PROMPT.persona.md.tmpl` (one canonical body; Claude Code verified, the rest illustrative).
-You are a {{DOMAIN}} engineer with 15 years building {{DOMAIN_DETAIL}}.
-A wrong-but-plausible result here is expensive; correctness over speed.
-Work step by step:
-1. Load the context files. Confirm the start gate: §3 CONTRACT FROZEN @ {{CONTRACT_VERSION}}
-   AND §4 TESTS RED for the right reason. If not → STOP and escalate (forward-skip forbidden).
-2. Build in small batches in src/ until the red tests pass — never weaken or skip a test.
-3. Converge: loop-until-dry · adversarial-verify every 'done' claim · completeness-critic.
-4. Resolve verify per the boundary. Write SUMMARY.md + OBSERVE deltas (deltas.md grammar).
-Score confidence (0-1) on Completeness · Clarity · Practicality · Optimization · EdgeCases ·
-Self-Eval; if any < 0.9, refine before returning.
-</persona>
-
-<strategy>
-The task's §5 plan — the Strategy (ordered batches) order and the Known-problem fixes — is
-your PREFERRED starting path, not a hard rule. Improve on it when a better strategy emerges
-as you build; on done, report the strategy you ACTUALLY used so the orchestrator can update
-§5 for the audit trail.
-</strategy>
-
-<touch_boundary>   <!-- from run.md; the worker's contract, identical on every runner -->
-MAY:  rewrite code in src/ · drive tests green WITHOUT weakening them · gather verify evidence.
-MUST NOT: edit the frozen CONTRACT or locked scope · weaken/delete/skip any test ·
-          touch §1–§3 bundle artifacts · write MILESTONE.md / state.json / any sibling stream.
-STOP-and-escalate (return your findings; do not decide):
-  • a discovered scope/contract gap  → backward-correction, reopen Specify (principle 4)
-  • any SECURITY finding              → HARD-STOP, always
-  • a concurrency/timing OR architecture/layering risk the tests cannot exercise
-  • [include this bullet when autonomy is conservative OR manual] the verify gate itself — STOP for the human
-Auto-PASS only if autonomy=auto AND: all tests green · coverage not decreased · no test weakened ·
-  no contract edited · loops dry · completeness-critic clean · no residue above. Log it as
-  auto-resolved, naming this run as owner — never forge a human signature.
-</touch_boundary>
-
-<context_files>   <!-- paths relative to the worktree root -->
-.add/PROJECT.md · .add/milestones/{{MILESTONE}}/MILESTONE.md (READ-ONLY) ·
-.add/tasks/{{TASK_SLUG}}/TASK.md · .claude/skills/add/run.md · .claude/skills/add/deltas.md
-</context_files>
-
-<expertise>
-If your runner supports specialist injection (a Claude Code skill, a system-prompt preamble, an
-agent profile), load the one matching {{DOMAIN}}. Otherwise the persona above IS your expertise.
-</expertise>
-
-<tools>
-Navigate with your runner's code-intelligence: mcp__serena under Claude Code; LSP / ctags /
-ripgrep otherwise. Design every IO path for failure — timeouts, retries, rollback.
-</tools>
-
-<return>   <!-- the worker PROPOSES; the orchestrator RECORDS. A worker never runs add.py. -->
-End with a structured verdict AND write the same into SUMMARY.md in the task dir, then
-**commit SUMMARY.md + deltas.md** in the worktree (uncommitted files survive only by harness
-courtesy — commit them so the serial-integration merge-back carries your report):
-{ task, outcome: PASS|RISK-ACCEPTED|HARD-STOP|ESCALATE, evidence: <tests+coverage>,
-  residue: [security|concurrency|architecture findings], deltas: [open lessons learned] }.
-Do NOT touch add.py or any shared file — the orchestrator gates on your verdict.
-</return>
-```
-
-## Choosing the model — vendor-neutral tiers
-
-ADD picks a **tier** from the scope's nature; the adapter maps the tier to the runner's model id.
-
-| Tier | When | Claude Code | Any other runner |
-|------|------|-------------|------------------|
-| **mid** | ordinary, well-tested scope; clear contract | `sonnet` | the runner's balanced model |
-| **top** | complex / ambiguous / cross-cutting / broad scope of impact | `opus` | the runner's strongest reasoning model |
-
-Two rules sit **above** model choice: **high-risk ⇒ a lowered rung (`conservative` or `manual`),
-regardless of model** — a stronger model does not buy back the human gate. And **security residue
-always escalates** — no tier auto-passes it.
-
-## The spawn adapter — one thin mapping per runner
-
-ADD needs six capabilities from any runner. **Isolation ADD owns itself** (a git worktree), so
-streams stay portable even without a native sandbox.
-
-| ADD needs | Abstract | Claude Code (verified reference) | Any CLI agent — Codex · opencode · pi-mono · … |
-|-----------|----------|----------------------------------|-----------------------------------------------|
-| spawn a worker | prompt + label | `Task(description=…, prompt=…)` | `cd $WT && <agent> run --prompt-file PROMPT.md` |
-| pick the model | tier → id | `model="opus"\|"sonnet"` | a `--model <id>` flag |
-| isolate | worktree | `isolation="worktree"` | `git worktree add $WT HEAD` (after committing the bundle; verify base == HEAD), then run inside it |
-| load context | files / cwd | `<context_files>` + repo cwd | run inside `$WT`; paths are relative |
-| domain expertise | skill / preamble | a Claude skill in `<expertise>` | a system-prompt / profile preamble |
-| return a verdict | structured | final message (optionally a schema) | stdout JSON the orchestrator parses |
-
-> **Honesty:** only the Claude Code column is verified. The CLI forms for Codex/opencode/pi-mono
-> are *illustrative shapes* — confirm exact syntax with the `find-docs` skill.
-
-When workers return, **you** record each outcome with the explicit slug — `add.py advance <slug>`
-as evidence lands, `add.py gate PASS|RISK-ACCEPTED|HARD-STOP <slug>` at verify — then re-read
-`status` to refill the READY-QUEUE. The worker proposes; the orchestrator records.

package/tooling/add_engine/release.py

@@ -1,86 +0,0 @@
-"""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_build_in_flight 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/templates/TASK.fast.md.tmpl

@@ -1,77 +0,0 @@
-# TASK: {{title}}
-
-slug: {{slug}} · created: {{date}} · stage: {{stage}}
-milestone: {{milestone}}
-autonomy: {{autonomy}}   <!-- Multi-component repo? add a `component: <name>` line (declared in .add/components.toml) to bind this fast task to a component — its root joins §5 Scope and its green-bar/verify surface at the gate. Omit for single-component projects. -->
-phase: ground   <!-- fast lane: ground -> specify -> contract -> tests -> build -> verify -> observe -> done -->
-fast: true   <!-- the fast lane: a small task, collapsed flow + minimal template. Omit --fast for full rigor. -->
-
-> Fast lane — one small task, minimal sections, filled top-to-bottom. The trust floor still
-> holds: a FROZEN §3 contract · ≥1 red test before build · a recorded §6 gate (security = HARD-STOP).
-> The acceptance scenario collapses into §1 `Accept:`; OBSERVE is one optional line at the gate.
-
----
-
-## 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>
-
----
-
-## 1 · SPECIFY — the rules
-
-Feature: <name>
-Must:
-  - <required behavior>
-Reject:
-  - <bad input / situation> -> "<error_code>"
-Accept: <the one acceptance scenario, Given/When/Then condensed to one line — it drives the §4 test>
-Assumptions: ⚠ <the one most likely wrong> — why; if wrong: <cost>   (or "none material — biggest risk: X")
-
----
-
-## 3 · CONTRACT — freeze the shape
-
-```
-<the shape that freezes: signature / fields · success + each rejection's response>
-```
-
-`Least-sure flag surfaced at freeze:` <[spec|contract|test] the point most likely wrong — why; if wrong: cost>
-Status: DRAFT
-<!-- The freeze IS the one approval. Approved -> Status: FROZEN @ vN — approved by <name>.
-     Changing a frozen contract = change request back to SPECIFY. -->
-
----
-
-## 4 · TESTS — failing-first (red)
-
-Plan: test_<accept> — assert the §1 Accept line's Then (behavior, not internals).
-Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
-
----
-
-## 5 · BUILD — AI writes code
-
-Scope (may touch): `./src/`   <every file the build may write — declared before the §3 freeze>
-Strategy & known-problem fixes: <ordered build steps · the trap each known problem must dodge>
-Strategy actually used: <fill at verify — what you ACTUALLY did, or "as planned"; harvested into §7 Decisions>
-Code lives in: `./src/`   ·   Constraints: change no test, no contract; allow-list packages only.
-
----
-
-## 6 · VERIFY — evidence + gate
-
-- [ ] all tests pass · coverage held · no test or contract altered during build
-- [ ] green was EARNED — no overfit / vacuous asserts / stubbed-away logic
-- [ ] no exposed secrets, injection openings, or unexpected dependencies (security = HARD-STOP)
-
-Build expectations (from §1 Accept + §3 CONTRACT): <the observable outcome a correct build must produce — confirmed by <how / where>>
-
-### GATE RECORD
-Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
-Reviewed by: <name> · date: <date>
-<!-- A security finding is ALWAYS HARD-STOP. Record exactly one outcome — no silent pass.
-     OBSERVE (optional): one `[SPEC · open]` or competency-delta line here if the loop taught the foundation something. -->

package/tooling/templates/TASK.md.tmpl

@@ -1,216 +0,0 @@
-# TASK: {{title}}
-
-slug: {{slug}} · created: {{date}} · stage: {{stage}}
-milestone: {{milestone}}
-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`. Multi-component repo (monorepo/multi-repo)? add a `component: <name>` line (declared in `.add/components.toml`) to ADD that component's root to your §5 Scope; omit for single-component projects (byte-identical default). -->
-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
-     (`unguarded_high_risk_auto`, run.md guard). A comment is never a declaration. -->
-
-> One file = one task. Fill sections top-to-bottom; the `add` skill drives each phase.
-> When a phase is unclear, read its book chapter in `.add/docs/` (linked per section).
-> The phase marker above is the single source of truth — keep it in sync via `add.py phase`.
-
----
-
-## 0 · GROUND — the real codebase ▸ docs/02-the-flow.md
-
-Touches (files · symbols · signatures): <path:symbol — what it is / how it is keyed>
-Context (working folder): <docs · todos · config · data the task touches — task-delta only>
-Honors (patterns / conventions): <PROJECT.md / CONVENTIONS.md anchors — task-delta only, never a re-scan>
-Seams consulted: <SEAMS.md entry cited instead of re-deriving, e.g. .add/SEAMS.md#scope-token-grammar — optional, omit if none apply>
-Anchors the contract cites: <the symbols §3 will name>
-Issues/Risks (→ feed §1): <problems · traps · untestable risks found in the real code — task-delta; §1 builds on these>
-Related intent: <PROJECT.md § · GLOSSARY term(s) · originating request/milestone rationale — the WHY; task-delta>
-Ground SHA: <`git rev-parse --short HEAD` at ground time — cite symbols, not bare line numbers; any line ref is "as of" this commit>
-
----
-
-## 1 · SPECIFY — the rules ▸ docs/03-step-1-specify.md
-
-Feature: <name>
-Framings weighed: <chosen> (chosen) · <alternative> · <alternative>
-Must:
-<must>
-  - <required behavior>
-</must>
-Reject:
-<reject>
-  - <bad input / situation> -> "<error_code>"
-</reject>
-After:
-<after>
-  - <state that is true once it succeeds>
-</after>
-Assumptions — lowest-confidence first:
-<assumptions>
-  ⚠ <the one assumption most likely to be wrong> — lowest confidence because <why>; if wrong: <cost>
-  - [ ] <next assumption, ranked> — confirm or deny; never carry an open one forward
-</assumptions>
-
-<!-- EXIT: every rule stated, every rejection named; assumptions ranked lowest-confidence first, the top one or two ⚠-flagged with why + cost (or, for trivial scope, an honest "none material" that still names the single biggest risk). -->
-
----
-
-## 2 · SCENARIOS — pass/fail cases ▸ docs/04-step-2-scenarios.md
-
-<scenarios>
-
-```gherkin
-Scenario: <short name>   # <Must/Reject item this covers, e.g. M1 or R1>
-  Given <starting situation>
-  When <action>
-  Then <expected result>
-  And <what must remain unchanged>   # required for every rejection
-```
-
-</scenarios>
-
-<!-- EXIT: one scenario per Must AND per Reject; each result is observable. -->
-
----
-
-## 3 · CONTRACT — freeze the shape ▸ docs/05-step-3-contract.md
-
-```
-<METHOD> <path>   body: { <fields> }
-  200 -> { <success fields> }
-  4xx -> { error: "<code>" | "<code>" }
-Schema: <tables/fields touched, and access pattern>
-```
-
-Glossary deltas: <new domain term(s) this task introduces, `Term: definition` — or "none">
-Status: DRAFT
-Reported: <yes — the freeze report (banner/ARC/SHAPE) rendered before this froze | no>
-<!-- The freeze IS the one approval — lead it with the bundle's lowest-confidence flag: the 1–2
-     points most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], each
-     with why + cost (the §1 ⚠ assumptions feed it; a flag may point at a scenario or the contract
-     too — see run.md). Approved -> Status: FROZEN @ vN — approved by <name>. Changing a frozen
-     contract = change request back to SPECIFY.
-     EXIT: frozen + every spec rejection has a contracted response + names match GLOSSARY (new
-     terms declared as a Glossary delta) + the bundle's lowest-confidence flag was surfaced at
-     the freeze (or an honest "none material"). -->
-
----
-
-## 4 · TESTS — failing-first suite (red) ▸ docs/06-step-4-tests.md
-
-Coverage target: <e.g. 90%>
-Plan (one test per scenario, asserting behavior not internals):
-<test_plan>
-  - test_<scenario>: arrange <Given> / act <When> / assert <Then> + assert <unchanged> · covers: <M#, R:code — optional>
-</test_plan>
-
-Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
-<!-- declare paths as backticked tokens on this line: `./…` = this task dir ·
-     a token with "/" = project root · a bare name = sibling of the previous
-     token's dir · a directory counts its *.py files (non-recursive); reports
-     mark declared counts with † · anything resolving outside the project root counts 0 -->
-
-<!-- EXIT: one test per scenario; suite red for the RIGHT reason; target recorded. -->
-
----
-
-## 5 · BUILD — AI writes code ▸ docs/07-step-5-build.md
-
-Scope (may touch): `./src/`   <fill before the §3 freeze — every file the build may write>
-Strategy (ordered batches): <1. … 2. … — the planned build order; guidance, not enforced; preferred architecture/pattern strategies; advise solution/method to resolve issues/implement features>
-
-Persona (optional): <name the persona file under `.add/personas/` this build embodies as a domain stance atop SOUL.md — advisory, never lowers a gate; absent = generic>
-Spawn isolation (default): <prefer isolation: "worktree" for any subagent build/verify spawn, not only explicit parallel mode; shared-tree needs a stated reason — see worktree-isolated-spawn-default>
-Known-problem fixes: <trap → planned fix — the failure modes this build must dodge; guidance, not enforced>
-Strategy actually used: <fill at VERIFY — the strategy you ACTUALLY used (or "as planned"); harvested into the §7 Decisions (ADR) block as the [AI] build decision>
-Safety rule (feature-specific): <e.g. debit+credit in one atomic transaction>
-Code lives in: `./src/`
-Constraints: do NOT change any test or the contract; allow-list packages only; ask if unclear.
-
-<!-- Scope tokens, backticked, FIRST declaring line: `./…` = this task dir · a token
-     with "/" = project root · a bare name = sibling of the previous token's dir ·
-     outside-root resolutions are dropped fail-closed · a DIRECTORY token covers its
-     whole subtree (containment — diverges from §4's non-recursive counting) ·
-     absent line = UNDECLARED (pre-existing tasks grandfathered, never retro-red) ·
-     engine enforcement (touched ⊆ declared) is live: a completing verify gate refuses an
-     out-of-scope build (scope_violation → self-heal) and add.py check surfaces it.
-     EXIT: all green; coverage held; no test/contract touched; no unlisted dependency. -->
-
----
-
-## 6 · VERIFY — evidence + non-functional review ▸ docs/08-step-6-verify.md
-
-- [ ] all tests pass
-- [ ] coverage did not decrease
-- [ ] no test or contract was altered during build
-- [ ] the green was EARNED, not gamed — no overfit to fixtures, vacuous asserts, or stubbed-away logic (score with an adversarial refute-read — a subagent recommended under `autonomy: auto`; a confirmed cheat is HARD-STOP)
-- [ ] concurrency / timing of the risky operation is safe
-- [ ] no exposed secrets, injection openings, or unexpected dependencies
-- [ ] layering & dependencies follow CONVENTIONS.md
-- [ ] a person reviewed and approved the change
-
-### Build expectations — what "correct" looks like (fill BEFORE build; confirm each at the gate)
-> Pre-declare the OBSERVABLE outcomes a correct build must produce — derived from §2 SCENARIOS
-> + §3 CONTRACT — so this gate checks the build is RIGHT, not merely that tests are green. Each
-> row is evidence you can SEE, not a restatement of a test name.
-- [ ] <observable outcome a correct build must produce> — confirmed by <how / where>
-- [ ] <another observable outcome> — confirmed by <evidence seen>
-
-### Deep checks — do not skim (fill the path that applies; the resolver judges which)
-- [ ] WIRING (code) — every new symbol is referenced; record where / how confirmed
-- [ ] DEAD-CODE (code) — no new unused or orphaned symbol introduced
-- [ ] SEMANTIC (prose / non-code) — read in full, not skimmed: <what read · what confirmed>
-
-### Live-verify evidence — confirm the §0 GROUND anchors still resolve (fill at the gate)
-> §0's Ground SHA anchors the symbols cited at ground time to that commit — code moves during
-> build. Before the gate, re-resolve every symbol §3 CONTRACT cites against the CURRENT tree
-> (not the Ground SHA) so a stale anchor is caught here, not by a future reader chasing a moved
-> line.
-- [ ] every symbol §3 CONTRACT cites still resolves in the current tree — confirmed by <how / where>
-- [ ] any anchor that moved/renamed since Ground SHA is named here, not left silent
-
-### Refute-read verdict — the earned-green check (record it; required for an auto-PASS)
-> Under autonomy: auto the AI auto-resolves Verify, so the earned-green refute-read MUST be
-> recorded here (the engine never spawns it — you do; NOT-EARNED -> `add.py heal`). The engine
-> MEASURES it is filled (`audit: refute_unrecorded`); it never auto-blocks — a human spot-audit
-> is the backstop. A human-gated (conservative/manual) task may leave it for the human's judgment.
-Verdict: <EARNED | NOT-EARNED>
-By: <self | agent-id> · adversarially checked: <what was probed>
-
-### Advisor 3-lens verdict — sequential (security → concurrency → architecture)
-> Under autonomy: auto run the 3-lens checklist and record the verdict here. Lenses run in
-> order; a Security HARD-STOP ends the checklist (leave remaining lenses blank). Binding for
-> sensitivity: mechanical (advisor-gate-relax reads it); advisory for all other sensitivities.
-> The engine MEASURES this block is filled (audit: advisor_verdict_unrecorded); it never blocks.
-Advisor: <agent-id | self>
-1. Security: <CLEAR | HARD-STOP: finding>
-2. Concurrency: <CLEAR | RESIDUE: finding>
-3. Architecture: <CLEAR | RESIDUE: finding>
-Verdict: <PASS | HARD-STOP>
-Residue: <none | summary>
-Binding: <yes — mechanical | advisory — <sensitivity>>
-
-### GATE RECORD
-Reported: <yes — the gate report (banner/ARC) rendered before this outcome recorded | no>
-Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
-If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)
-Reviewed by: <name> · date: <date>
-
-<!-- A security finding is ALWAYS HARD-STOP. Record exactly one outcome — no silent pass. The Advisor 3-lens verdict and the Refute-read verdict are both measured by `add.py audit` (`advisor_verdict_unrecorded` · `refute_unrecorded`) — neither is engine-blocked; a human spot-audit is the backstop for any finding the AI did not surface or record. -->
-
----
-
-## 7 · OBSERVE — feed the next loop ▸ docs/09-the-loop.md
-
-Watch (reuse scenarios as monitors): <error rate / per-rejection rate / latency>
-
-### Decisions (ADR)
-<harvested at done from §1/§3/§5/§6 — do not hand-edit; one actor-tagged line per decision, refilled only while this placeholder stands>
-
-### Spec delta
-Forward changes for the next loop — each re-enters at Specify as the next task. One line
-each, tagged `[SPEC · open|seeded|dropped]`, with evidence (e.g. `[SPEC · open] rate-limit
-the retry path (evidence: prod herd spikes)`). See the `add` skill's `deltas.md`.
-
-### Competency deltas
-What did this loop teach the foundation? One line each, tagged by competency
-(`DDD · SDD · UDD · TDD · ADD`), status `open`, with evidence. See the `add` skill's `deltas.md`.
-<!-- e.g.  - [DDD · open] the model missed multi-tenancy (evidence: scenario_x failed) -->