@pilotspace/add 1.16.0 → 1.17.0

package/tooling/add_engine/constants.py

@@ -24,6 +24,8 @@ __all__ = [
     "SETUP_FILES",
     "PERSONA_FRONTMATTER_KEYS",
     "PERSONA_REQUIRED_SECTIONS",
+    "PERSONA_HINT",
+    "PERSONA_FIT_HINT_TEMPLATE",
     "GUIDELINE_FILES",
     "RULES_FILE_REL",
     "WORKFLOW_HEADINGS",
@@ -99,6 +101,24 @@ SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md
 PERSONA_FRONTMATTER_KEYS = ("name", "vibe")
 PERSONA_REQUIRED_SECTIONS = ("## Identity", "## Critical Rules", "## Default Requirement", "## Success Metrics")
 
+# persona-seed-nudge v2: ONE hint, single-sourced — `new-milestone`/`check`/`status` all print
+# THIS constant (not their own copy) so the wording can never drift across the three surfaces.
+# Project-scoped (not "this milestone's domain") per the confirmed v2 amendment: the AI should
+# catch up ALL of a project's missing personas, not draft a single milestone-fit one.
+PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — spawn the add-persona "
+                "agent (or read docs/18-personas.md) to seed the project's persona(s) from "
+                "PROJECT.md's domain")
+
+# persona-fit-nudge: the OPPOSITE-branch, mutually-exclusive sibling of PERSONA_HINT — fires only
+# when ≥1 real persona ALREADY exists, so a brand-new milestone doesn't silently assume one of
+# them fits its domain. Existence-only (names the persona slugs already seeded); the AI still
+# owns the actual fit judgment via add-persona — the engine never scores content similarity.
+# {slugs} is filled at call time from `.add/personas/*.md` (excluding `_template`).
+PERSONA_FIT_HINT_TEMPLATE = (
+    "existing persona(s) seeded — {slugs} — confirm one fits this milestone's domain, or spawn "
+    "the add-persona agent (or read docs/18-personas.md) to draft a better-fit one"
+)
+
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
 # never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
 # milestones/, archive/). These are working state, not records: scope-snapshot.json
@@ -199,6 +219,7 @@ fast: true
 ## 0 · GROUND
 Touches (files · symbols):
 Anchors the contract cites:
+Ground SHA:
 
 ## 1 · SPECIFY
 Feature:

package/tooling/add_engine/io_state.py

@@ -199,3 +199,30 @@ def _md5_file(p: Path) -> str | None:
         return hashlib.md5(p.read_bytes()).hexdigest()
     except OSError:
         return None
+
+
+def _personas_unseeded(root: Path) -> bool:
+    """True when `.add/personas/` has no REAL (non-template) authored persona: the
+    directory is absent, empty, or holds only the seeded `_template.md` scaffold
+    (persona-seed-nudge). Fail-soft: an unreadable directory counts as unseeded
+    rather than raising — this feeds a `note:`/INFO hint, never a gate."""
+    d = root / "personas"
+    if not d.is_dir():
+        return True
+    try:
+        return not any(p.stem != "_template" for p in d.glob("*.md"))
+    except OSError:
+        return True
+
+
+def _real_persona_slugs(root: Path) -> list[str]:
+    """Sorted slugs of REAL (non-template) personas under `.add/personas/` — the existence-only
+    listing persona-fit-nudge names in its hint. Fail-soft: an unreadable/absent dir is empty,
+    mirroring `_personas_unseeded`'s own fail-soft convention."""
+    d = root / "personas"
+    if not d.is_dir():
+        return []
+    try:
+        return sorted(p.stem for p in d.glob("*.md") if p.stem != "_template")
+    except OSError:
+        return []

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

@@ -18,6 +18,7 @@ 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>
 
 ---
 
@@ -56,7 +57,7 @@ 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 & 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.
 

package/tooling/templates/TASK.md.tmpl

@@ -2,15 +2,11 @@
 
 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). -->
+autonomy: {{autonomy}}   <!-- level: manual < conservative < auto — lower for a high-risk task (`add.py autonomy set`). Multi-component repo? add a `component: <name>` line (.add/components.toml) to join that root to §5 Scope. -->
 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. -->
+<!-- high-risk/method-defining? declare `risk: high` on the slug line + a lowered autonomy — the engine refuses an unguarded completion (`unguarded_high_risk_auto`). 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`.
+> One file = one task — fill top-to-bottom; the phase marker above is the single source of truth (`add.py phase`); unclear phase → its book chapter.
 
 ---
 
@@ -49,7 +45,7 @@ Assumptions — lowest-confidence first:
   - [ ] <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). -->
+<!-- EXIT: every rule + rejection stated; assumptions ranked lowest-confidence first, top 1–2 ⚠-flagged with why + cost (or an honest "none material" naming the biggest risk). -->
 
 ---
 
@@ -83,14 +79,7 @@ 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"). -->
+<!-- The freeze IS the one approval — lead it with the bundle's lowest-confidence flag (§1 ⚠ feeds it; a flag may point at any part — run.md). Approved -> Status: FROZEN @ vN — approved by <name>; changing a frozen contract = change request back to SPECIFY. EXIT: frozen · every §1 rejection has a contracted response · names match GLOSSARY (new terms = Glossary delta) · flag surfaced. -->
 
 ---
 
@@ -103,10 +92,7 @@ Plan (one test per scenario, asserting behavior not internals):
 </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 -->
+<!-- declare paths as backticked tokens on this line: `./…` = this task dir · a token with "/" = the project root · a bare name = a sibling of the previous token's dir · a directory counts its *.py files (non-recursive) · declared counts marked † · outside the project root counts 0 -->
 
 <!-- EXIT: one test per scenario; suite red for the RIGHT reason; target recorded. -->
 
@@ -115,9 +101,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; preferred architecture/pattern strategies; advise solution/method to resolve issues/implement features>
+Strategy (ordered batches): <1. … 2. … — the planned build order; guidance, not enforced; preferred architecture/pattern strategies; advise solution/method to resolve issues/implement features; let the named Persona's domain stance (below) shape the approach, not just architecture patterns>
 
-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>
+Persona (required): <name the persona file under `.add/personas/` this build embodies as a domain stance atop SOUL.md — advisory, never lowers a gate; name "generic" if no project persona fits yet>
 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>
@@ -125,14 +111,7 @@ 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. -->
+<!-- Scope tokens, backticked, FIRST declaring line: `./…` = this task dir · a token with "/" = project root · a bare name = sibling of the previous token's dir · a DIRECTORY token covers its whole subtree (diverges from §4's non-recursive counting) · outside-root resolutions drop fail-closed · absent line = UNDECLARED (grandfathered, never retro-red) · enforcement live: a completing verify gate refuses an out-of-scope build (scope_violation → self-heal); check surfaces it. EXIT: all green; coverage held; no test/contract touched; no unlisted dependency. -->
 
 ---
 
@@ -148,9 +127,7 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 - [ ] 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 outcomes a correct build must produce, derived from the §2 scenarios + §3 contract — evidence you can SEE, not test names.
 - [ ] <observable outcome a correct build must produce> — confirmed by <how / where>
 - [ ] <another observable outcome> — confirmed by <evidence seen>
 
@@ -160,26 +137,17 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 - [ ] 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.
+> Re-resolve every symbol §3 cites against the CURRENT tree (code moved since Ground SHA) — catch a stale anchor here, not later.
 - [ ] 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.
+> Under auto, record the earned-green refute-read (the engine never spawns it — you do; NOT-EARNED -> `add.py heal`). Audit-measured (`refute_unrecorded`), never blocked; a human spot-audit is the backstop.
 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.
+> Lenses run in order; a Security HARD-STOP ends the checklist (leave the rest blank). Binding for sensitivity: mechanical (advisor-gate-relax); advisory otherwise. Audit-measured (`advisor_verdict_unrecorded`), never blocked.
 Advisor: <agent-id | self>
 1. Security: <CLEAR | HARD-STOP: finding>
 2. Concurrency: <CLEAR | RESIDUE: finding>
@@ -194,7 +162,7 @@ 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. -->
+<!-- Security is ALWAYS HARD-STOP; record exactly one outcome — no silent pass. The Advisor 3-lens and Refute-read verdicts are audit-measured (`advisor_verdict_unrecorded` · `refute_unrecorded`), never engine-blocked; a human spot-audit backstops anything unrecorded. -->
 
 ---
 
@@ -206,11 +174,8 @@ Watch (reuse scenarios as monitors): <error rate / per-rejection rate / latency>
 <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`.
+One line per forward change, tagged `[SPEC · open|seeded|dropped]` + evidence — each re-enters at Specify (`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`.
+One lesson per line: `[DDD|SDD|UDD|TDD|ADD · open] the learning (evidence: …)` — see `deltas.md`.
 <!-- e.g.  - [DDD · open] the model missed multi-tenancy (evidence: scenario_x failed) -->

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

@@ -1,6 +1,10 @@
 ---
 name: <persona name — e.g. Frontend Engineer, UX Researcher>
 vibe: <one-line essence — what this persona keeps true>
+flow: <RECOMMENDED — which of the three apply-surfaces this persona is loaded at (see
+ docs/18-personas.md "Apply — three surfaces"): design (the UDD requirements lens) | build
+ (the domain-identity overlay on SOUL.md) | advisor (subagent/streams delegation, incl. the
+ verify refute-read) — comma-separate if more than one, e.g. `build, advisor`>
 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
@@ -9,8 +13,11 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      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 /
+     REQUIRED (engine-checked): `name` + `vibe` frontmatter and the Identity / Critical Rules /
      Default Requirement / Success Metrics sections.
+     RECOMMENDED (not engine-checked, but expected on every persona for consistency): `flow:`
+     frontmatter and the `## Abilities` section — a persona with no stated flow or abilities is
+     hard for the design/build/advisor surfaces to actually pick up and use.
      OPTIONAL (recommended for a faithful distillation): `source:` frontmatter, and the
      `## Anti-patterns` + `## Playbook` sections. The engine never requires the optional
      parts; absence is conformant.
@@ -23,12 +30,27 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      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. -->
+        green run") over a volatile literal ("2491/0") that rots as the project grows.
+     5. NAME the flow. State which apply-surface(s) actually load this persona — a persona
+        that fits none of design/build/advisor is dead weight nobody will ever pick up.
+     6. ABILITIES are checkable skills, not aspirations. Anchor each to a real file, tool, or
+        command this project already has — the same anchoring discipline as Critical Rules
+        and Success Metrics, applied to "what this persona can concretely do." -->
 
 ## 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.>
 
+## Abilities
+<concrete, checkable things this persona can actually DO — a capability list, distinct from
+ Critical Rules (always-enforced constraints) and Playbook (optional step-by-step scaffolding).
+ State each as something the agent can perform right now, anchored to a real file/tool/command
+ where possible — not an aspiration.>
+- <ORIENT first (convention): lead with the 1–3 commands the agent RUNS on load before acting —
+  e.g. `add.py status` · the domain's suite · the diff to judge — acting beats re-deriving>
+- <a concrete capability — e.g. "can diff two response fixtures byte-for-byte to prove passthrough">
+- <another concrete capability>
+
 ## Critical Rules
 <non-negotiables this persona ALWAYS enforces. Lead with 1–2 carried from the teacher (its
  signature stance), then add project-specific ones.>