@pilotspace/add 1.13.0 → 1.15.0

package/tooling/templates/TASK.md.tmpl

@@ -1,6 +1,7 @@
 # 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
@@ -18,7 +19,11 @@ phase: ground   <!-- ground -> specify -> scenarios -> contract -> tests -> buil
 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>
 
 ---
 
@@ -53,7 +58,7 @@ Assumptions — lowest-confidence first:
 <scenarios>
 
 ```gherkin
-Scenario: <short name>
+Scenario: <short name>   # <Must/Reject item this covers, e.g. M1 or R1>
   Given <starting situation>
   When <action>
   Then <expected result>
@@ -75,14 +80,16 @@ Scenario: <short name>
 Schema: <tables/fields touched, and access pattern>
 ```
 
+Glossary deltas: <new domain term(s) this task introduces, `Term: definition` — or "none">
 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"). -->
+     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"). -->
 
 ---
 
@@ -91,7 +98,7 @@ Status: DRAFT
 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_<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.
@@ -107,7 +114,9 @@ Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 ## 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>
+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>
 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>
@@ -148,6 +157,14 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 - [ ] 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
@@ -156,12 +173,25 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 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
 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. -->
+<!-- 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. -->
 
 ---
 

package/tooling/templates/gitignore.tmpl

@@ -4,3 +4,15 @@ scope-snapshot.json
 pre-archive-state.bak.json
 pre-update-state.bak.json
 .update-cache.json
+
+# ADD-managed vendor trees: regenerable/vendored copies the installer drops in,
+# never project-authored — mirrors the .add/docs/ rationale above, generalized
+# to every consumer project (not just this repo). Patterns are BARE, not repo-
+# root style: this file lives INSIDE .add/, so git resolves its patterns
+# relative to .add/ itself — a ".add/"-prefixed pattern here would look for
+# the non-existent .add/.add/tooling/ and never match anything. (one further
+# managed tree is NOT listed here — the engine's own _GITIGNORE_BODY constant
+# must stay hands-off of it by name; the installer twins seed that pattern
+# themselves, also bare.)
+tooling/
+docs/

package/tooling/templates/personas/_template.md.tmpl

@@ -0,0 +1,60 @@
+---
+name: <persona name — e.g. Frontend Engineer, UX Researcher>
+vibe: <one-line essence — what this persona keeps true>
+source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/personas-teacher/engineering/engineering-software-architect.md` (provenance; omit if hand-authored)>
+---
+<!-- A PERSONA is a project-fit requirements persona, distilled from the vendored teacher
+     library (`.add/personas-teacher/`) to the parts ADD can act on. The AI authors one file
+     per persona this project needs (frontend, backend, reviewer, …) from PROJECT.md +
+     the teacher; the engine only seeds + validates this schema (presence-based). This
+     `_template.md` is the schema reference — copy it to `<slug>.md` and fill it.
+
+     REQUIRED: `name` + `vibe` frontmatter and the Identity / Critical Rules /
+     Default Requirement / Success Metrics sections.
+     OPTIONAL (recommended for a faithful distillation): `source:` frontmatter, and the
+     `## Anti-patterns` + `## Playbook` sections. The engine never requires the optional
+     parts; absence is conformant.
+
+     DISTILLATION DISCIPLINE (how to fill this faithfully — learned from the teacher corpus):
+     1. SCOPE = stance, not voice. A persona is a domain STANCE (what to enforce, what to
+        suspect, what "good" measures). TONE/voice belongs to SOUL.md — never duplicate it here.
+     2. KEEP the teacher's own rules. Carry 1–2 of the teacher's signature Critical Rules
+        VERBATIM-in-spirit before adding project-specific ones — distil, don't replace.
+     3. TAG provenance honestly. In `## Playbook`, mark each item teacher-derived vs
+        ADD-native. Never credit home-grown project scaffolding to the teacher.
+     4. METRICS are rules, not snapshots. Prefer an invariant ("suite matches the last
+        green run") over a volatile literal ("2491/0") that rots as the project grows. -->
+
+## Identity
+<who this persona is — role, domain depth, and the EARNED perspective it brings (what it has
+ seen succeed/fail that shapes its judgement). One short paragraph.>
+
+## Critical Rules
+<non-negotiables this persona ALWAYS enforces. Lead with 1–2 carried from the teacher (its
+ signature stance), then add project-specific ones.>
+- <a teacher-sourced rule (the persona's signature non-negotiable)>
+- <a project-specific rule this project needs>
+
+<!-- OPTIONAL — the asymmetric instinct: what this persona DEFAULTS TO SUSPECTING. Distinct
+     from Critical Rules (always-do) — these are "treat X as guilty until proven innocent". -->
+## Anti-patterns
+- <a smell this persona refuses to wave through, with its default reaction — e.g.
+  "'0 issues found' on a first pass → look harder", "an abstraction with no second caller → cut it">
+- <another anti-pattern + the default response>
+
+## Default Requirement
+<the one requirement this persona includes by default in every deliverable
+ (e.g. "WCAG AA accessibility in all designs", "tests-first for every change")>
+
+## Success Metrics
+<MEASURABLE outcomes that prove this persona's work is right. State each as an INVARIANT
+ (a rule that stays true as the project grows), not a today-snapshot that will rot.>
+- <a measurable outcome — e.g. "4.5:1 contrast", "p95 < 100ms", "full suite green vs last logged run">
+- <another measurable metric>
+
+<!-- OPTIONAL — delete if the persona needs no executable scaffolding. -->
+## Playbook
+<the highest-value EXECUTABLE know-how — a checklist, a template, or a step sequence the
+ build can actually follow (e.g. an ADR skeleton, a STRIDE pass, a red→green loop). Tag each
+ item `(teacher)` or `(ADD)` so provenance is honest. Keep it to what gets used at the work
+ moment; link the full teacher file for depth: see the `source:` path above.>