@pilotspace/add 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [2.2.0] — 2026-07-22
+
+Minor: the Direction beat gains a **fable reasoning discipline** — a prompt-only
+pass that makes the agent derive from the task in front of it instead of a fluent
+template, distilled from the fable-thinking protocol. No engine change.
+
+- **fable reasoning discipline** — `phases/direction.md` opens with the lens for
+  the whole bundle: **Fluent ≠ true** (a draft's polish tracks its token count,
+  not its evidence), the **Five Moves** (FRAME · GROUND · REASON · ATTACK ·
+  DELIVER) each mapped to the beat that already applies it, and two pre-answer
+  checks the fluent draft skips — the **Floor** (restate the Goal in the human's
+  world, then sweep the Leftovers: every supplied invariant and the BARE runtime)
+  and the **constraint loop** (expand → verify mechanically → repair the §3 tag
+  census · §5 scope tokens · §4 `covers:` keys · REDS refs before the freeze).
+- **claim grammar** — `add-advisor`'s §6 Return tags every factual assertion by
+  how it's known: `[OBSERVED]` (checked live this session) · `[DERIVED]` ·
+  `[PRIOR]` (memory, may be stale) · `[ASSUMED]`; a bare claim reads as OBSERVED,
+  so a guess never rides in unmarked. **GROUND** makes the same rule structural:
+  a recalled file/flag/symbol is `[PRIOR]` until re-confirmed against the live tree.
+- Prompt-only, propagated byte-identical across the three synced skill trees;
+  `add.py` == ENGINE_MD5 unchanged. Pinned by `test_fable_floor.py`.
+
 ## [2.1.0] — 2026-07-22
 
 Minor: the two-agent roster matures and the persona author learns from real

package/agents/add-advisor.md

@@ -19,8 +19,10 @@ beat keeps moving. Personas carry the expertise; you carry independent, first-pr
   options and RETURN A DECISION with its rationale. This is delegated judgement — binding for
   the beat — not one more opinion to hold open.
 - **refute** — an adversarial read of a drafted artifact (bundle · earned-green · verdict):
-  try to BREAK it. Name the input/state that makes it wrong. Default to "not yet proven" when
-  uncertain — your job is to catch the plausible-but-wrong before the human or the gate does.
+  try to BREAK it. Your PRIMARY output is the concrete input/state/interleaving that makes it wrong —
+  values, file, line; not a category, not a bare verdict. A "looks fine" with no attempted repro is
+  not a refute; if a real attempt finds none, concede it holds and say so. Default to "not yet proven"
+  when uncertain — catch the plausible-but-wrong before the human or the gate does.
 
 Every mode serves EVERY beat — the spawn names the beat + mode, and you calibrate to it:
 **direction** (propose the bundle plan · refute the draft so the human freezes the stronger
@@ -71,6 +73,12 @@ worker cannot be about its own work.
 `{ mode, persona, kind, recommendation, decision|verdict, tradeoffs: [weighed],
 weakest_dimension, risks: [🔴|🟡|💭 …], assumptions, confidence: {per-dimension 0–1},
 escalate: {security_hard_stop|change_request|residue}? }`
+**Claim grammar** — tag each factual assertion in `recommendation`/`decision`/`risks` by its
+evidence basis, so the worker can tell a checked fact from a recalled one: `[OBSERVED]` you
+verified it against the live tree this session · `[DERIVED]` it follows from an observation ·
+`[PRIOR]` training or memory, may be stale · `[ASSUMED]` unverified but required. A bare claim
+reads as OBSERVED — so never leave a guess untagged. **Fluent ≠ true**: your confidence rises
+with token count, not evidence; the tag is what keeps the two apart.
 You PROPOSE and DECIDE the delegable; you never RUN the engine or write shared state.
 
 Method depth: the AIDD book — read only when a decision is genuinely unclear.

package/agents/add-worker.md

@@ -29,6 +29,8 @@ Read YOUR mode's guide from the project's skill tree (`.claude/skills/add/phases
 spawn — the orchestrator reads only SKILL.md and does not pre-read it for you.
 
 ## 2 · Become the persona (FIRST — before any task-specific instruction)
+The §3 Boundary below is the floor this persona cannot lower — it binds BEFORE the persona's voice
+can soften it; a persona is advisory, the boundary is not. Now become the persona:
 Select from `.add/personas/` by frontmatter alone (name · vibe · flow · task-kinds ·
 use-when · not-when): prefer a persona whose `flow:` names your mode's surface
 (direction→design · build→build · verify→verify) AND whose `task-kinds:` covers the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "ADD (AI-Driven Development) 2.0. The agent is the hands; ADD is the memory, judgment, and conscience — a minimal, state-tracked skill: one freeze per feature, trust from passing tests, state on disk so context rot never survives a new session.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -69,10 +69,10 @@ confirms. Unsharp intent? **Interview before you size** (`intake.md`). A milesto
 
 Every task is three beats (seven steps, folded), three engine calls, ONE human decision:
 
-1. **DIRECTION** — load the domain-fit persona (seed via add-worker persona-mode if none), then draft
-   the whole bundle top-to-bottom in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
-   §2 scenarios · §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) · §4 red suite
-   (run it — red for the RIGHT reason; fill each bullet's `covers:` clause key). Then the ONE approval,
+1. **DIRECTION** — load the domain-fit persona (seed via add-worker persona-mode if none), then compose
+   the whole bundle in ONE silent draft — §1–§3 + §5-scope, no per-section narration; §4 then runs red — in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
+   §2 scenarios (optional gherkin — §4 is canonical) · §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) ·
+   §4 red suite — one test per Must & per Reject (a Must/Reject encoded in neither §2 nor §4 = §1 not understood — stop); run red for the RIGHT reason; fill each `covers:` key. Then the ONE approval,
    presented lowest-confidence-first: `add.py freeze` (a setup session's baseline `lock` IS this approval).
 2. **BUILD** — code in `src/` until every red is green; change no test, no frozen contract; stay
    inside the §3 Scope. A test OUTSIDE your suite failing? `add.py locate` names the owning node, the
@@ -118,7 +118,7 @@ confirmable delta the human confirms rewrites `SOUL.md` (the human is the only w
 
 ## Command cookbook — copy a line; `-h` only off-menu
 
-`add.py` = `python3 .add/tooling/add.py`; lines 2–4 = the 3-call walk (`advance --fill <draft>` = step-wise).
+`add.py` = `python3 .add/tooling/add.py`; lines 2–4 = the 3 calls — default is ONE composed draft then bare `advance`/`freeze`; `advance --fill <draft>` = step-wise, only for a large/uncertain task.
 
 ```bash
 add.py status --brief        # resume · status --section <n|phase> = §body · --foundation · --json

package/skill/add/phases/build.md

@@ -76,4 +76,4 @@ verify residue → a SPEC delta.
 Routing: `ddd`→domain · `sdd`→system · `udd`→experience · `tdd`→quality · `add`→method — each
 lands in-flight in its living spec via `add.py delta-append <dd>` (grammar: `deltas.md`). A
 HOW-an-agent-behaves lesson → a persona, not the shared pile. Deltas prepend newest-first;
-the spec diff is the receipt. Self-score before emitting (the confidence six dimensions; < 0.9 → refine).
+the spec diff is the receipt. Self-score before emitting (the confidence six dimensions; name the weakest, refine).

package/skill/add/phases/direction.md

@@ -1,9 +1,39 @@
 # Direction — the whole specification bundle (setup · rules · plan · red suite) to the ONE freeze
 
-Every task drafts §1–§4 top-to-bottom, then ONE human approval crosses it into build:
-`add.py freeze --by <name> --cross`. This file is the reference depth for that span —
+Every task COMPOSES §1–§3 + §5-scope in ONE silent draft — a single write, no "moving on to §N"
+narration — then §4 runs red and ONE human approval crosses it into build:
+`add.py freeze --by <name> --cross`. The only mandatory breaks in the draft are running the §4 red
+suite (a tool action, not prose) and the freeze. This file is the reference depth for that span —
 SKILL.md carries the loop; read the section you're stuck in, not the file.
 
+## The reasoning discipline (the lens for the sections below)
+
+**Fluent ≠ true.** A draft's polish tracks its token count, not its evidence; every check in this
+file forces a fresh derivation from THIS task over a plausible template. It is Rule 2 (trust
+evidence, not inspection) turned inward — on your own reasoning, not just the build. Distilled from
+the fable-thinking protocol; each move maps to where the loop already applies it.
+
+**Five moves, one arc per beat:**
+- **FRAME** — restate the real question + the load-bearing facts. → §1 co-specify.
+- **GROUND** — verify by observation, not memory; a recalled file/flag/symbol/lesson is `[PRIOR]`
+  until re-confirmed against the live tree THIS session; a live read outranks memory. → §3 Grounding.
+- **REASON** — hold more than one hypothesis; demand a mechanism ("because…"), not a correlation;
+  simulate with concrete values before committing. → the persona plan · the advisor's propose-plan.
+- **ATTACK** — switch to reviewer, run the cheap kill-test; its output is a concrete falsifying input
+  (file · line · values), not a verdict. → advisor `refute` · verify earned-green (security = HARD-STOP).
+- **DELIVER** — lead with the outcome, expose the weakness, recommend don't survey. → the gate report, lowest-confidence-first.
+
+**Two pre-answer checks the fluent draft skips** (applied at the freeze — checklist below): the
+**Floor** — restate the **Goal** in the human's world (not the wording), then sweep the
+**Leftovers** (every supplied invariant / the BARE runtime encoded or waived) — and the
+**constraint loop** for mechanically-checkable output shape (§3 tag census · §5 scope tokens · §4
+`covers:` keys · REDS): expand → verify mechanically (grep/count, not a re-read) → repair → then freeze.
+
+**Claim grammar** — tag each factual assertion by how you know it: `[OBSERVED]` (checked live this
+session) · `[DERIVED]` (follows from an observation) · `[PRIOR]` (memory, may be stale) · `[ASSUMED]`
+(unverified but required). A bare claim reads as OBSERVED — never leave a guess untagged; it is the
+advisor's §6 Return discipline.
+
 ---
 
 ## Setup — first session only (autonomous draft → one baseline lock)
@@ -141,7 +171,8 @@ the design-definition loop (`design.md`).
   `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`.
 </output_format>
 
-§2 makes every rule checkable — one scenario per Must and per Reject:
+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:
 
 ```gherkin
 Scenario: <short name>
@@ -159,8 +190,8 @@ one per applicable case, or rule it out on purpose. Every Then is specific and o
 - [ ] 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").
-- [ ] §2: one scenario per Must and per Reject; every rejection asserts what stays unchanged; edge
-      cases covered or ruled out on purpose.
+- [ ] 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.
 </exit_gate>
 
 ---
@@ -173,7 +204,10 @@ above it the Contract does not move.
 ### Grounding — reason it in-context (don't write an essay — `PLAN.md.tmpl`: persist the interface, not prose)
 Project from the milestone `## Ground`, then deepen only where THIS task lands. Never invent a
 file/symbol you have not opened; cite the **symbol**, not a bare line number (`l.NNN` rots; symbols
-survive), via code-navigation tools, not memory. **Persist only what the contract needs**: the
+survive), via code-navigation tools, not memory. A recalled fact — a file, a flag, a symbol, or a
+prior lesson (even one carried in from memory) — is **PRIOR until re-confirmed** against the live
+tree THIS session; a live read outranks memory, and a safety-grep counts only once you have
+confirmed it actually matched (a `for x in $VAR` that ran vacuous proves nothing). **Persist only what the contract needs**: the
 **Anchors** it may cite (the specific symbols §3 names — it may cite ONLY these) and, optionally, a
 **Ground SHA** (the commit grounded against — the engine stamps it when the line is present).
 Everything else — what it **Touches**, the **Honors**/seams consulted, the **Issues/Risks**, the
@@ -212,12 +246,27 @@ line the freeze records it (audit-only — `route_unrecorded` is measured, never
 
 ## The freeze review checklist
 
-The human's one minute, aimed. Walk these seven before saying yes:
-
+The human's one minute, aimed. **Fluent ≠ true** — a bundle's polish tracks its token count, not its
+evidence, so these checks force a fresh read of THIS task over a plausible template. Run the **Floor**
+first, then walk the rest before saying yes:
+
+- **Floor (before you read the shape)** — the pre-answer check the fluent draft skips. (1) Restate the
+  **Goal**: the end-state the human actually wants, in their world, not the ticket's wording — a bundle
+  that satisfies the words but misses the goal is the most expensive miss. (2) Check the **Leftovers**:
+  every supplied constraint — each PROJECT.md `invariant:`, the BARE declared runtime, every ⚠ the
+  interview surfaced — is either encoded in §1–§4 or explicitly waived. An unused constraint is a trap,
+  not noise: the artifact must hold under the BARE runtime, so a leftover invariant is a defect already
+  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?
 - **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
+  REDS / dangling refs — don't eyeball them: expand the rule, self-verify the draft **mechanically**
+  (grep/count in reasoning space, not a re-read), repair, THEN freeze. This is where the freeze-parser
+  self-breaks get caught before the engine does — a bare `<word>` colliding with the tag census, a
+  `./src/` scope token tripping `scope_violation`.
 - **Grounded** — does the Contract cite anchors that exist in the Grounding map? `status`/`check` surface this.
 - **Risk** — high-risk or method-defining? Require `risk: high · autonomy: conservative` in the PLAN.md header.
 - **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
@@ -247,6 +296,8 @@ mode on any task). Coding kinds keep the executable red suite above.
 
 §4's `Tests live in:` line is machine-read — declare paths as backticked tokens on that line: with
 no local `tests/`, `add.py report` counts test functions at the declared paths (FIRST such line only).
+REPLACE the template's `./tests/` placeholder in place — never append a SECOND `Tests live in:` line:
+the report reads the FIRST, so a stale default left above your real path silently wins.
 `./…` → 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); a `.py` file counts itself. Resolved files dedupe; declared counts
@@ -278,9 +329,13 @@ it 0–1 on six dimensions: **Completeness** (every rule/scenario/rejection cove
 (understood without you in the room?) · **Practicality** (implementable against the real code?) ·
 **Optimization** (correctness/simplicity/cost balanced — no gold-plating, no corner cut?) ·
 **Edge cases** (failure modes, concurrency, empty/oversized inputs named?) · **Self-evaluation**
-(does it carry its own refine step?). Any dimension **< 0.9** → refine, then re-score. The lowest
-dimension is what you surface ⚠-first at the freeze; persistently low on risky scope →
-*recommend* lowering autonomy (the level stays the human's call).
+(does it carry its own refine step?). Rank the six worst→best (a model ranks far more reliably than
+it calibrates an absolute), then NAME the one concrete deficiency in your weakest dimension — a
+missing scenario, an unhandled input, not a number — and fix THAT before presenting; re-rank after.
+The lowest dimension is what you surface ⚠-first at the freeze; persistently low on risky scope →
+*recommend* lowering autonomy (the level stays the human's call). The self-score is a **weak signal**:
+the load-bearing correctness check is the adversarial refute-read (`phases/verify.md`) — the
+plausible-but-wrong a self-score waves through is exactly what the refute exists to catch.
 The hard rule: **advisory, never a gate** — it never auto-passes a verify, never substitutes for evidence or the
 human decision, and a self-asserted score is never recorded as something the human "agreed to".
 

package/skill/add/phases/verify.md

@@ -36,7 +36,7 @@ Record in the §6 **Deep checks** block — an unfilled one is a **shallow verif
 
 ## Part four — was the green earned?
 
-A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (green against an empty implementation), and real logic stubbed away — all invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md). Under `auto`, **record the verdict** in §6's `### Refute-read verdict` block — an unrecorded verdict leaves the auto-PASS untraceable (the human spot-audit is the backstop).
+A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (green against an empty implementation), and real logic stubbed away — all invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. Its PRIMARY output is a concrete falsifying input — the fixture value, interleaving, or caller that makes the green wrong (file · line · values), not a verdict; a "looks fine" with no attempted repro is not a refute, and if a real attempt finds none it concedes the green holds and says so. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md). Under `auto`, **record the verdict** in §6's `### Refute-read verdict` block — an unrecorded verdict leaves the auto-PASS untraceable (the human spot-audit is the backstop).
 
 ## Record exactly one outcome (no silent pass)
 
@@ -44,7 +44,7 @@ Render this gate from the card: banner → ARC → SUMMARY → FLAGS → EVIDENC
 (`gate-udd.md` = the full template + examples, read at most once per session), and reconcile FLAGS
 with `add.py report --decide`'s open-item count. Right-size the render to the risk: `sensitivity: mechanical`
 tasks use the compact form — banner → SUMMARY → EVIDENCE → APPROVE; `security` / `data` /
-`architecture` always get the full card. **Human-led: render before `gate` and record `Reported: yes` in §6, never self-stamp.**
+`architecture` always get the full card. Audience by mode: under `conservative` the card renders to the human before the gate; under `autonomy: auto` (no reachable human) you WRITE it to the §6/trace record as the accountable artifact and proceed — you render, you don't wait. **Human-led: render before `gate` and record `Reported: yes` in §6, never self-stamp.**
 
 | Outcome | When |
 |---------|------|