@pilotspace/add 1.0.0 → 1.2.0

package/tooling/templates/CONVENTIONS.md.tmpl

@@ -1,4 +1,4 @@
-# CONVENTIONS  (survivor layer — set once, kept for the whole project)
+# CONVENTIONS  (living documentation — set once, kept for the whole project)
 
 Language/framework: <e.g. Python 3.12 / FastAPI>
 Folders: .add/tasks/<slug>/{TASK.md, tests/, src/}

package/tooling/templates/GLOSSARY.md.tmpl

@@ -1,3 +1,26 @@
 # GLOSSARY  (one name per concept — used everywhere: specs, contracts, code)
 
 <term>: <definition>
+
+# ADD method vocabulary (domain-standard names; bridges to legacy terms)
+GOAL: the one durable outcome a project (and each milestone) runs toward — the loop's orientation anchor, declared as the lowercase `goal:` line in PROJECT.md / MILESTONE.md and surfaced by status/guide every session; distinct from a task's §1 Must (a single required behavior, not the whole-project outcome).
+deep verify: the deepened Verify evidence (v20) required beyond passing tests — for a task that produced code, that every new symbol is referenced (wiring) and no new dead/unused code exists; for prose/non-code, a recorded no-skim semantic read; which path applies is resolver-judged and the engine never classifies (a rubric, not add.py).
+onboarding: the install -> first-milestone path (formerly "on-ramp").
+primary flow: the solid forward path of the flow diagram — a phase starts only when its input exists (formerly "forward spine").
+cross-cutting concern: a concern running through every step rather than being one step — security, testing, observability, cost (formerly "spine / continuous concern").
+working state: everything an agent loads each session — skill router, active phase, PROJECT/MILESTONE/TASK, state.json (formerly "state surface").
+audit trail: the reference record read by people, never auto-loaded into agent context (formerly "story surface").
+method rationale: the why behind every rule — the AIDD book, loaded on demand, never duplicated (formerly "trust layer").
+failing-first suite: the test suite written before code, confirmed red for the right reason — a missing implementation (formerly "red safety net").
+non-functional review: the deliberate post-evidence check of what tests rarely catch — concurrency, security, architecture (formerly "blind-spot checks").
+change scope: the files a locked run may and may not touch (formerly "touch-boundary"; the <touch_boundary> XML prompt tag keeps its name).
+automated quality gate: the evidence-based Verify resolver under autonomy auto — may auto-PASS on complete evidence; security always escalates (formerly "evidence auto-gate").
+autonomy level: the per-task Verify resolver setting — auto (default) or conservative; declared in the TASK.md header, human-reviewed at the freeze (formerly "autonomy dial").
+living documentation: the durable project artifacts — conventions, glossary, frozen contracts — that outlive any particular code (formerly "survivor layer").
+scope level: the granularity a decision lives at — intake level (request -> versioned scope), milestone level, setup/foundation level, task level (formerly "altitude").
+baseline approval: the one human gate that freezes the AI-drafted foundation, first scope, and first contract together — runs as `add.py lock` (formerly "the lock-down").
+lesson learned: a single learning a loop produces, tagged by the competency it improves — the `- [DDD · open]` grammar and deltas.md/`add.py deltas` machine names stay (formerly "competency delta").
+lowest-confidence flag: the AI's ranked declaration of the 1–2 points most likely to be wrong in what a human is asked to approve — each with why + cost-if-wrong; the ⚠ glyph keeps its name as the machine marker (formerly "least-sure flag").
+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").

package/tooling/templates/MILESTONE.md.tmpl

@@ -1,6 +1,7 @@
 # MILESTONE: {{title}}
 
 goal: {{goal}}
+rationale: <why this scope — the confirmed intake classification (bucket + reason)>
 stage: {{stage}} · status: active · created: {{date}}
 
 > SDD living doc for this milestone. Keep it THIN: breadth, shared decisions, and

package/tooling/templates/PROJECT.md.tmpl

@@ -1,4 +1,4 @@
-# PROJECT — survivor layer (cross-milestone context)
+# PROJECT — living documentation (cross-milestone context)
 
 > The durable foundation that outlives every milestone and feeds context into each
 > TDD⇄ADD loop. Read this FIRST in any session. Keep it lean — one screen, not a
@@ -7,6 +7,7 @@
 > that is the re-entrant arrow from the engine down to the foundation.
 
 slug: {{project}} · stage: {{stage}} · updated: {{date}}
+goal: <the one durable outcome this whole project runs toward — set this at setup; status/guide surface it every session>
 
 ---
 
@@ -22,8 +23,8 @@ slug: {{project}} · stage: {{stage}} · updated: {{date}}
 <!-- The spec is a living document, not a frozen plan. This section POINTS to the
      active milestone + frozen contracts; it does not duplicate them. -->
 - Active milestone → `.add/milestones/<slug>/MILESTONE.md`  (see `add.py status`)
-- Frozen contracts (survivor): the contracts other work builds against.
-- Settled vs still open:
+- Frozen contracts (living docs): the contracts other work builds against.
+- Settled vs still open: <frozen contracts · open questions>
 
 ## Users (UDD) — UI/UX: design before code
 <!-- UI/UX-Driven Development: users use the interface, not the spec. Capture the

package/tooling/templates/TASK.md.tmpl

@@ -2,6 +2,9 @@
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
 phase: specify   <!-- 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 with `autonomy: 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).
@@ -14,21 +17,31 @@ phase: specify   <!-- specify -> scenarios -> contract -> tests -> build -> veri
 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>
-Assumptions — least-sure first:
-  ⚠ <the one assumption most likely to be wrong> — least sure because <why>; if wrong: <cost>
+</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 least-sure 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). -->
+<!-- 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>
   Given <starting situation>
@@ -37,6 +50,8 @@ Scenario: <short name>
   And <what must remain unchanged>   # required for every rejection
 ```
 
+</scenarios>
+
 <!-- EXIT: one scenario per Must AND per Reject; each result is observable. -->
 
 ---
@@ -50,22 +65,30 @@ Scenario: <short name>
 Schema: <tables/fields touched, and access pattern>
 ```
 
-Status: DRAFT   <!-- becomes: FROZEN @ v1 once approved. Changing a frozen contract = change request back to SPECIFY. -->
-<!-- The freeze IS the one approval. Lead it with the bundle's least-sure flag: the 1–2 points
-     most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], with why + cost.
-     The §1 ⚠ assumptions are its first feeder; a flag may point at a scenario or the contract too. See run.md. -->
-
-<!-- EXIT: frozen + every spec rejection has a contracted response + names match GLOSSARY + the bundle's least-sure flag was surfaced at the freeze (or an honest "none material"). -->
+Status: DRAFT
+<!-- 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 + the
+     bundle's lowest-confidence flag was surfaced at the freeze (or an honest "none material"). -->
 
 ---
 
-## 4 · TESTS — red safety net ▸ docs/06-step-4-tests.md
+## 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>
+</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. -->
 
@@ -81,7 +104,7 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 
 ---
 
-## 6 · VERIFY — evidence + blind-spot checks ▸ docs/08-step-6-verify.md
+## 6 · VERIFY — evidence + non-functional review ▸ docs/08-step-6-verify.md
 
 - [ ] all tests pass
 - [ ] coverage did not decrease
@@ -91,6 +114,11 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 - [ ] layering & dependencies follow CONVENTIONS.md
 - [ ] a person reviewed and approved the change
 
+### 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>
+
 ### GATE RECORD
 Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
 If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)