@pilotspace/add 2.2.0 → 2.4.0

package/skill/add/phases/direction.md

@@ -153,7 +153,7 @@ Rejects: `not_classified` · `dangling_criterion` · `no_milestone` · `duplicat
 
 ---
 
-## Rules (§1) + scenarios (§2) — co-specification
+## Rules (§1) — co-specification
 
 State what the feature MUST do and MUST REJECT — zero ambiguity left to guessing. Co-specify in three moves: **Diverge** (surface the 2–3 genuine framings +
 open questions; let the user react), **Converge** (draft §1 by PROJECTING from the milestone
@@ -171,8 +171,10 @@ the design-definition loop (`design.md`).
   `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`.
 </output_format>
 
-Every Must and Reject must be checkable — canonically as a §4 test (its `covers:` tag); §2 gherkin is
-an OPTIONAL readable projection, added only when a human needs prose cases at the freeze, never as ceremony:
+Every Must and Reject must be checkable — canonically as a §4 test (its `covers:` tag). Cases live
+in §4 · TESTS & SCENARIOS (the old standalone §2 SCENARIOS section is retired). A Given/When/Then
+line is an OPTIONAL readable projection, added inline in §4 only when a human needs prose cases at
+the freeze, never as ceremony:
 
 ```gherkin
 Scenario: <short name>
@@ -182,16 +184,17 @@ Scenario: <short name>
   And <what must remain unchanged>   # REQUIRED for every rejection
 ```
 
-Then sweep the edge cases — boundary · duplicate · partial failure · concurrency · malformed input —
-one per applicable case, or rule it out on purpose. Every Then is specific and observable, never
+Then sweep the edge cases — boundary · duplicate · partial failure · concurrency · malformed input.
+Gate the PRIMARY cases + primary edge cases with a red test each; minor/secondary behaviors are
+DESCRIBED in prose as build-guidance, not a red test. Every Then is specific and observable, never
 "then it works". Your §1 ranking feeds the bundle-level flag the human reads at the freeze.
 
 <exit_gate>
 - [ ] Framings weighed noted; every required behavior stated; every rejection has a named error code.
 - [ ] Assumptions ordered lowest-confidence first; the 1–2 `⚠` flags carry why + cost — or an honest
       "none material" that still names the single biggest risk (never a blank "none").
-- [ ] Every Must and Reject is encoded — a §4 test (canonical) or an optional §2 gherkin scenario;
-      every rejection asserts what stays unchanged; edge cases covered or ruled out on purpose.
+- [ ] Every Must and Reject is encoded as a §4 test (`covers:` tag); every rejection asserts what
+      stays unchanged; primary edge cases covered or ruled out on purpose (minor ones may be prose).
 </exit_gate>
 
 ---
@@ -259,7 +262,7 @@ first, then walk the rest before saying yes:
   waiting at verify.
 - **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong. The engine refuses an unflagged freeze before build (`unflagged_freeze`).
 - **Intent** — does §1 say what you actually want built?
-- **Cases** — does every Must and Reject have an observable §2 scenario?
+- **Cases** — does every Must and Reject have an observable §4 test/scenario (`covers:` tag)?
 - **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
 - **Shape self-verify (the constraint loop)** — for the mechanically-checkable output-shape rules — the
   frozen §3 tag census (the closed XML vocabulary), the §5 Scope path tokens, each §4 `covers:` key, any
@@ -280,8 +283,8 @@ Reject any line → the bundle goes back to draft; the freeze stays the only gat
 Run the suite now, with no implementation — **red for the right reason** (missing implementation,
 not a broken harness). A test green before code exists is testing nothing. **A test is any
 machine-checkable assertion**, not only xUnit code — a metric threshold (ML/data), a reconciliation
-query, a plan-diff (infra), a rendered-screen diff (UI). Produce: one executable test per §2
-scenario asserting **behavior, not internals** · contract-conformance tests (shapes + error
+query, a plan-diff (infra), a rendered-screen diff (UI). Produce: one executable test per PRIMARY
+case/scenario asserting **behavior, not internals** · contract-conformance tests (shapes + error
 responses) · side-effect assertions on rejection paths (`assert balance unchanged`) · a recorded
 coverage target.
 

package/skill/add/phases/verify.md

@@ -9,13 +9,34 @@ sufficient. Fill **§6** in PLAN.md including the GATE RECORD.
 > **security is always a HARD-STOP and is never auto-passed**. Under `conservative`, or whenever
 > residue is found, this phase is **human-led** (auto-PASS conditions: `run.md`).
 
+## The reasoning discipline — verify's slice of the arc (definitions: `phases/direction.md`)
+
+**Fluent ≠ true** holds for verdicts: a verdict's confidence tracks how much evidence prose you
+wrote, not what you checked — a checkbox ticked from memory is a guess wearing a PASS. The arc
+at the gate:
+
+- **GROUND** — every Part-one checkbox is a factual claim: tick it only `[OBSERVED]` — you ran
+  the suite / read the evidence THIS session; a remembered pass is `[PRIOR]` — re-run it, never
+  recall it. A safety-grep counts only once you confirmed it actually matched.
+- **ATTACK** — verify IS the arc's attack beat: the earned-green refute-read (Part four) whose
+  primary output is a concrete falsifying input, and the three lenses of Part two. Security
+  stays HARD-STOP.
+- **DELIVER** — the gate card leads with the outcome, exposes the residue yourself
+  lowest-confidence-first, and tags its claims by evidence basis — never a bare "all green".
+- **Floor Goal check** — before recording PASS, restate the goal in the human's world: a suite
+  that satisfies the §4 words but misses what they actually wanted is the most expensive miss,
+  and this gate is the last place to catch it.
+- **Constraint loop on the §6 record** — the record blocks (3-lens verdict · Deep checks ·
+  Refute-read verdict · `Reported:`) are mechanically checkable: sweep them as a census before
+  the gate — an unfilled block is an unrecorded verdict, caught by you, not by the spot-audit.
+
 ## Part one — confirm the evidence
 
 - [ ] All tests pass — or, for a non-coding task, every §4 acceptance check is green (the evidence it names is real).
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during build.
 - [ ] The §3 Target (measurable) is hit — including any declared outcome tests can't show, confirmed by real evidence.
-- [ ] §1 rules trace to §2/§4 — an untraced rule is a coverage gap (`add.py check` warns on it).
+- [ ] §1 rules trace to a §4 test (`covers:` tag) — an untraced rule is a coverage gap (`add.py check` warns on it).
 - [ ] every §3-cited symbol still resolves in the CURRENT tree.
 
 If any is false, stop and return to Build.
@@ -73,7 +94,7 @@ python3 .add/tooling/add.py gate PASS          # marks the task done
 Verify owns the loop's tail since the six-phase merge. After the gate, fill §7:
 
 1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout.
-2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" define
+2. **Reuse scenarios as monitors** — the §4 scenarios/tests that defined "correct" define
    what you alert on: overall error rate, each rejection's rate, latency of the risky op.
 3. **Draft the next spec delta** — every defect, surprise, or new need becomes a change
    that re-enters the flow at Specify (a new task). Emit lessons tagged by the

package/skill/add/strategy.md

@@ -0,0 +1,54 @@
+# Strategy — the persona-framed PM loop that fills the `## Strategy` slot
+
+A multi-task or high-uncertainty milestone earns a plan over its tasks *before* they are
+built. This guide drives that plan: a short **DISCUSS → OPTIMIZE → CONVERGE** loop that fills
+the milestone's `## Strategy` slot (`MILESTONE.md`) with a sequenced, optimized task DAG.
+
+**Trigger:** a milestone with several tasks or real uncertainty, at intake or when it activates.
+**Skip:** a micro / `--tiny` milestone — a **drafted-blank** slot is valid, run nothing (risk-proportional).
+
+The persona already loaded at intake (`intake.md`) **drives** this loop — you don't re-select
+one. It frames the sequencing WITH the project's PM lens; it stays advisory throughout.
+
+## Run the loop (with the intake persona)
+
+1. **DISCUSS** — surface the task DAG: the dependencies, the shared/risky contracts, the
+   tradeoffs. Reflect the milestone goal, name what's in and out. Ask **one load-bearing
+   question per live lens** — an interview toward ~95% confidence, not a survey.
+2. **OPTIMIZE** — sequence the DAG. Fill the slot's four facets (defined there, not restated
+   here): **approach** (risk-first | dependency-first | first-slice-unblocks — and WHY) ·
+   the **freeze-first** contract(s) · the **parallel waves** behind those frozen contracts ·
+   the **first unblocking slice**. Name the alternative decompositions you rejected.
+3. **CONVERGE** — before you record, pressure-test the plan. If the milestone is
+   **high-uncertainty** (the sequencing is contested, or the self-score won't clear its bar),
+   spawn `add-advisor` in **refute** mode to try to **break** the strategy — the approach, the
+   freeze-first choice, the wave partition. Fold what survives; concede what holds. A
+   low-uncertainty / micro / `--tiny` milestone **skips** the spawn — no forced ceremony.
+   Then self-score with the existing six-dimension confidence self-score (`phases/direction.md`);
+   refine until it clears its bar (no dimension < 0.9 ≈ ~95% confident). Do **not** invent a
+   second threshold — that bar IS convergence. Record the converged plan in the `## Strategy` slot.
+
+The refute is **advisory**: the advisor hands back the concrete break — it **cannot block**.
+The human still confirms the strategy at the human decision point, through the persona-owned
+gate (`gate-udd.md`) — the persona decides the report's shape and cadence. Security stays **HARD-STOP**.
+
+## It stays SOFT
+
+The `## Strategy` slot is the **preferred** plan, exactly like a task's §5 Build-strategy: the
+build loop may deviate and records what it actually did. It is **advisory** — **never a new
+gate**, and it never lowers a floor. Security stays **HARD-STOP** everywhere. A milestone is
+never blocked on reaching a confidence bar; the bar guides the draft, it does not gate the work.
+
+## How deep? (risk-proportional)
+
+Loop depth scales with the milestone's risk/size — more risk/size, more depth:
+
+- **micro / `--tiny`** → skip the loop. A drafted-blank `## Strategy` is valid; the loop runs
+  nothing — **zero added per-turn cost**.
+- **multi-task, low-uncertainty** → run DISCUSS → OPTIMIZE → CONVERGE; no advisor.
+- **high-uncertainty** (contested sequencing, or the self-score won't clear its bar) → the full
+  loop **plus** the `add-advisor` refute at CONVERGE.
+
+This is the skill's judgment, reusing the Trigger / Skip and CONVERGE signals above — **never an
+engine gate** on `## Strategy`. The ladder is **SOFT**: a run may go deeper or shallower and
+records what it did. Security stays **HARD-STOP**.