@pilotspace/add 1.17.0 → 2.0.0

package/skill/add/soul.md

@@ -1,58 +0,0 @@
-# Self-improving the voice — how SOUL.md converges to the human
-
-`SOUL.md` is the AI's voice (Tone · Communication style · Trust). It ships as a **proposed starter** and is **human-owned**; this doc is how it starts converging to *this* human. It mirrors `deltas.md` (emit) + `fold.md` (confirm → rewrite), but a confirmed voice delta consolidates into **SOUL.md**, not the foundation — voice is not one of the five competencies.
-
-You **emit** voice deltas as `open`. Only the **human** confirms one; **the human's confirm is the only writer** — you never self-approve a voice rewrite.
-
-## What a voice delta is drawn from
-
-A voice delta is grounded in how the human shows up **in session**:
-- their **wordings** — the words they reach for, and the words they correct you on;
-- their **flow** — what they skip, what they double-check, where they want summary before detail.
-
-NOT from their private **memory** files or anything outside the working session — SOUL learns only from what you observed together.
-
-## The grammar (mirrors deltas.md)
-
-```
-- [VOICE · <status>] <observation about the voice> (evidence: <in-session pointer>)
-```
-
-- `<observation>` — what the voice should become ("lead with the decision, not the preamble").
-- `<status>` — `open` | `confirmed` | `declined`. A newly emitted delta is **`open`**.
-- `(evidence: …)` — **required**, non-empty: a moment in the session (a correction, a re-ask, a visible preference). No evidence → drop it.
-
-```
-- [VOICE · open] the human strips hedging from my drafts — cut "I think / it seems" and state it plainly
-  (evidence: they rewrote two replies this session to remove the qualifier)
-```
-
-## The loop — observe → confirm → rewrite
-
-1. **Emit** (OBSERVE) — propose 0–N voice deltas as `open` from wordings + flow. Surface in the report; show-before-ask.
-2. **Confirm** — the human accepts or declines each. **No SOUL.md write happens without this.**
-3. **Rewrite** — on a confirmed delta, edit the routed SOUL.md section, record the delta line (`confirmed`) at the **top** of "Voice deltas" (**newest-first**, append-only — declined stays in place).
-
-## Routing — every voice delta has a SOUL.md home
-
-| the delta is about… | rewrite this SOUL.md section |
-|---------------------|------------------------------|
-| how I *sound* (warmth, directness, hedging) | **## Tone** |
-| how I *structure* what I say (summary-first, show-before-ask, length) | **## Communication style** |
-| what keeps the human's *trust* (gates, honesty, what I never do) | **## Trust** |
-
-The rewrite is surgical: refine or append the bullet the delta names; never silently rewrite the rest of the voice. Every confirmed delta also gets its line in **## Voice deltas** (newest-first).
-
-## Reject codes
-
-<reject_codes>
-- `unconfirmed_voice_rewrite` — a SOUL.md write was attempted without a recorded human confirm. The AI proposes; it never self-approves. Stop and get the confirm.
-- `no_open_voice_deltas` — nothing is `open`. The loop is a no-op; do not touch SOUL.md.
-- `unroutable_voice_delta` — the observation maps to no SOUL.md section (not tone/style/trust). Fix the delta or widen the routing before writing.
-</reject_codes>
-
-## Where it plugs in
-
-- **Emit**: `phases/7-observe.md` proposes voice deltas beside competency/spec deltas.
-- **Target**: `SOUL.md` — "## Voice deltas" ledger holds confirmed history.
-- **Kin**: `deltas.md` + `fold.md` (same propose→confirm→write discipline). No `add.py` command writes the voice.

package/skill/add/streams.md

@@ -1,269 +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:** `sequential + auto` is the project default at setup (`phases/0-setup.md` "Run
-mode") — one task at a time, but Verify still auto-PASSes on evidence. Parallel streaming is an
-**opt-in** for a milestone with genuinely independent tasks: `add.py streams set parallel
---project`, then read on. A project that raised its gate to `conservative`/`manual` still treats
-this rubric as the same 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 — worktree isolation is the default for any spawn, not just a wave.
-  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**: `isolation="worktree"` is the default for any agent-spawned step, not only a
-  wave — a shared-tree spawn needs a stated reason. 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. `add.py worktree-prep <slug>` mechanizes the recipe: cuts the
-  worktree, copies both trees in, and echoes the fork base for the ledger — one step.
-- **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,
-default for any spawn), 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,78 +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>
-Ground SHA: <`git rev-parse --short HEAD` at ground time — any line ref reads "as of" it>
-
----
-
-## 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 · let the active persona's domain stance (or "generic") shape the approach, not just patterns>
-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. -->