@pilotspace/add 1.13.0 → 1.15.0

package/skill/add/scope.md

@@ -20,7 +20,7 @@
 Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
 
 1. **Ground in current assets.** Read the goal against what exists — the goal must reflect what the project already is. Ground as rigorously as a task's §0 (`phases/0-ground.md`), using the **same four fields** at milestone scope: **Touches** (the subsystems/files the milestone spans) · **Context** (the docs · todos · config · data it works against) · **Honors** (the `PROJECT.md` / `CONVENTIONS.md` invariants it must respect) · **Anchors** (the existing contracts/symbols its tasks will cite). Grounding is complete when each is named from real assets, not assumed.
-2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
+2. **Relate to the milestone map.** Run `add.py search <keyword> [<keyword> ...]` first — then read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
 3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.
 
 ## Brainstorm before you draft — co-specify at milestone level
@@ -40,7 +40,7 @@ Rank assumptions lowest-confidence first; top 1–2 get the flag: `⚠ <assumpti
 
 - **goal** — ONE outcome sentence (no "and" — that is two milestones).
 - **rationale** — intake bucket + WHY, AND the milestone relationship from "Position the goal". Never in state.json.
-- **Scope In/Out** — explicit anti-creep deferral list. An empty Out list means scope is not yet thought through.
+- **Scope In/Out** — explicit anti-creep deferral list. An empty Out list means scope is not yet thought through. UI/UX scope? use the template's Scope hint vocabulary, not generic prose.
 - **Shared decisions & glossary deltas** — cross-cutting rules every task must honor. New terms get a glossary entry.
 - **Shared / risky contracts to freeze first** — decision points between tasks; name the owning task.
 - **Tasks (breadth-first)** — `slug · depends-on · one line` each. Decompose by deliverable; keep each task one-file-sized.

package/skill/add/sensitivity.md

@@ -0,0 +1,51 @@
+# Sensitivity — the project's risk-class vocabulary
+
+A task declares its risk-CLASS with a `sensitivity:` line in the TASK header — *what
+kind* of risk it carries, distinct from `risk:` (*how much*). The engine validates +
+surfaces the human's declaration; it **never classifies**. Read live by freeze/status/check.
+
+## The base four (method-universal — always apply)
+
+- **security** — authn/authz, secrets, crypto, attack surface. A finding here is HARD-STOP;
+  the human is in the loop in EVERY tier (never advisor-gated, never auto-passed).
+- **data** — persistence, migrations, privacy of stored records, data loss.
+- **architecture** — module boundaries, contracts, cross-cutting structure.
+- **mechanical** — rote, low-impact change (rename, move, format, doc). The only class
+  a recorded advisor verdict (three §6 fields: Verdict · Residue · Binding) can gate for
+  auto-completion (`advisor-gate-relax`).
+
+These four can't be removed — a project only EXTENDS them.
+
+## Extend per project (you maintain this)
+
+Domain risk-classes live in `.add/GLOSSARY.md` under a `## Sensitivity classes` section,
+one `- <token>: <definition>` bullet per line:
+
+```markdown
+## Sensitivity classes
+Base (always apply): security · data · architecture · mechanical
+- pii: personally identifiable information; any task touching it escalates to human review
+- payments: money movement; reconciliation + an audit trail are required
+```
+
+`freeze` then accepts a header `sensitivity:` value from **base ∪ your domain classes**;
+a token in neither is refused `sensitivity_invalid`. `status` prints the active task's
+class; `check` nudges (`sensitivity_classes_unset`, never red) until you declare some.
+
+## The AI's job — keep it current
+
+- When a milestone or task reveals a **new kind of risk** this project carries (a regulated
+  data category, a payment rail, a tenancy boundary), ADD it as a class with a one-line
+  definition — propose it, the human confirms (it is foundation, like a glossary term).
+- **Re-read the section each session** (it rides `GLOSSARY.md`); pick the tightest class
+  when you declare a task's `sensitivity:` at freeze.
+- **Map domain → base behavior** in the definition so downstream gating is unambiguous —
+  e.g. "pii … escalates to human review" pins it as human-floor, not advisor-gatable.
+
+## Hold the line
+
+- **Declared, never inferred** — the engine reads your token; it does not guess a class.
+- **Base four are universal** — domain classes add to them, never replace them; security
+  stays a human floor in every tier.
+- **A comment is never a declaration** — commented-out example bullets don't count; only a
+  real `- <token>:` line under the section is a class.

package/skill/add/streams.md

@@ -14,17 +14,17 @@ 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 is that the reviewer is **never blocked waiting on a build**: builds for B·C·D run behind
-*their* frozen contracts while the human reviews A. You hide build latency under human latency.
+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
 
-Compute both from one `python3 .add/tooling/add.py status` — no new state:
+Both from one `add.py status` — no new state:
 
 - **READY-QUEUE** — tasks where `phase ≠ done` **and** every `deps=` task shows `gate=PASS`.
-  A task with unmet deps stays queued; a task finishing PASS unblocks its dependents.
-- **REVIEW-QUEUE** — the irreducibly serial part: the **bundle approval** (contract freeze) and
-  any **Verify escalation**. One human, one queue. Present these one at a time, never in a batch.
+  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
@@ -88,21 +88,19 @@ floor never drops to zero (`run.md:22`). Do not engineer around it.
 
 ## Design for failure (required)
 
-- **Fresh worktree base (verify base == HEAD)** — create each worker's worktree from current
-  `HEAD` **after** committing the task's frozen specification bundle. Confirm `git -C <worktree>
-  rev-parse HEAD` equals the orchestrator's `HEAD`; if drifted, `git merge` the base first.
-  On a pool-based runner (e.g. Claude Code) the pre-spawn check **shifts** to the worker's
-  **step-0**: sync to base and re-echo `rev-parse HEAD`, which the orchestrator verifies at
-  **merge-time**. The engine executes this gate (`engine-merge-base-enforcement`): run
-  `python3 .add/tooling/add.py wave-verify` before the first merge-back — it refuses a
-  mismatched or pending echo (`unverified_fork_base`) and an off-template ledger
-  (`wave_ledger_malformed`, fail-closed); `add.py check` is the standing monitor.
-- **Lease + timeout** — record which worker holds which task (in the wave ledger); if a worker
-  dies, release the claim back to READY.
-- **Failure isolates** — a worker that hits a STOP-and-escalate blocks only its own task;
-  siblings keep running and 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.
+- **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.
+- **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
 
@@ -167,6 +165,9 @@ 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:
@@ -240,8 +241,8 @@ always escalates** — no tier auto-passes it.
 
 ## The spawn adapter — one thin mapping per runner
 
-ADD needs six capabilities from any runner. **Isolation is the one ADD owns itself** (a git
-worktree), so streams stay portable even on a runner with no native sandbox.
+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 · … |
 |-----------|----------|----------------------------------|-----------------------------------------------|