@pilotspace/add 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.3.0] — 2026-07-24
+
+Minor: three waves — a **signal graph** view over the task DAG, the **§2
+Scenarios fold** into §4, and a **call-lean pass** that kills the two measured
+WM1 freeze/scope call sinks. Engine changes are additive; templates migrate
+in place (no manual task-file edits).
+
+### Signal graph — one addressable node for every note/todo/delta
+- **unified signal model** — note, todo, and spec-delta collapse into ONE
+  addressable `signal` node (status + edges), projected as a VIEW, not a new
+  store; `_signals` reader.
+- **`graph --signals`** — opt-in overlay renders signals on the task DAG;
+  **exit-criteria** render as `ec_` *delivered-by* nodes (a milestone's own
+  criteria appear as ✓/○ nodes wired to the tasks that meet them).
+- **`graph --html`** — emits a self-rendering HTML page to tmp (Mermaid inline,
+  no external host).
+- **atomicity signal** — the freeze SEEDS a persistent atomicity signal into the
+  task's todos instead of an ephemeral print, so the nudge survives the session.
+
+### §2 Scenarios folded into §4 — one place for cases
+- the standalone **§2 SCENARIOS** section is **retired in place**: pass/fail cases
+  now live with the tests in **§4 · TESTS & SCENARIOS** (primary-case rigor). The
+  §3–§7 numbers are unchanged so the freeze parser and every §-reference keep
+  working — the §1→§3 jump is intentional.
+- **PROJECT.md** gains a managed `ADD:SPECS` pointer block (init/migrate inject it
+  from the 5-DD spec set); foundation references reconciled to the `.add/specs/`
+  model; the generated **CLAUDE.md** block finalized in the generator.
+- the Step-2 Scenarios book chapter folds into Step-4; `add-flow.png` retired.
+
+### Call-lean pass — the WM1 freeze/scope sinks die at the source
+- **freeze-flag slot** — `PLAN.md.tmpl` §3 carries a drafted-blank *Least-sure
+  flag* slot; the first freeze no longer fails `unflagged_freeze` (0/6 reps in the
+  re-measure, was 3/3). The unfilled part-menu placeholder still never satisfies
+  the gate — the floor holds.
+- **scope-first freeze** — a §3 Scope that resolves to zero cover is now refused
+  `scope_unresolved` AT the freeze with a paste-ready fix, instead of surfacing
+  later as `scope_violation` → re-cross → re-gate. UNDECLARED stays grandfathered;
+  greenfield `[MISSING]` tokens still freeze; a `.add/tasks/` token gets a
+  task-dir teach note.
+- **scope-walk prunes** — `.venv` · `venv` · `.tox` · `.mypy_cache` · `.ruff_cache`
+  · `.eggs` and any `*.egg-info` dir are pruned from the scope walk, so an
+  in-workspace virtualenv or `pip install -e .` metadata is never read as an
+  out-of-scope write. `dist`/`build` stay watched (can be a real write-set). The
+  untouched-Scope-default warning now self-explains (a note, not a blocker; clears
+  only by editing the Scope line — re-cross does not clear it).
+- **honest fidelity meter** — the artifact-blind LLM `spec_fidelity` metric is
+  replaced by a deterministic `requirement_coverage` (frozen per-WM checklists +
+  probes, no LLM in the metric path); `oracle_pass_rate` promoted to the headline;
+  the judge demoted to an advisory `code_quality_annotation`.
+- **§3 Build-strategy relabel** — *Scope (may touch)* is the HARD scope-lock; the
+  rest (Strategy · Regression floor · Persona) is SOFT/optional. `MILESTONE.md`
+  gains a drafted-blank `## Strategy` slot.
+
+Retired (no CLI/install surface change): the standalone **§2 SCENARIOS** section
+(folded into §4) · the **ccsk / rule-file** mode · `add-flow.png`.
+
+Pinned by `test_release_2_3_0.py`. `ENGINE_MD5` re-aimed to `60eef504…`
+(scope refusal + walk prunes); the four tooling twins stay byte-identical;
+full tooling suite green (2277 tests).
+
+## [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/bin/cli.js

@@ -39,7 +39,7 @@ function parseArgs(argv) {
   // hint only echoes flags the user actually chose (shortest true command).
   const args = { _: [], force: false, check: false, noSkill: false, stage: null, name: null,
                  yes: false, nonInteractive: false, global: false, globalData: false,
-                 fromGlobalData: false, ruleFile: false, lockTimeout: null };
+                 fromGlobalData: false, lockTimeout: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
@@ -61,9 +61,6 @@ function parseArgs(argv) {
     // already provides the `add` skill, so a plugin bootstrap uses this to materialize
     // .add/tooling/ into the project without a duplicate .claude/skills/add.
     else if (a === "--no-skill") args.noSkill = true;
-    // --rule-file: write the ADD block to .claude/rules/add-workflows.md + reference it from
-    // CLAUDE.md instead of inlining (auto-on for ccsk projects with a .ccsk/ dir).
-    else if (a === "--rule-file") args.ruleFile = true;
     else if (a === "--stage" || a === "--name") {
       const v = argv[++i];
       // fail loudly on a trailing/abutting flag — never silently drop a value
@@ -263,126 +260,6 @@ function writeAgentPointer(target, profile) {
   }
 }
 
-// --- rule-file mode: ccsk-style relocation of the CLAUDE.md block ---------------------
-// Mirror of add.py / _installer.py rule-file logic (twins by duplication). For ccsk projects
-// (.ccsk/ dir) or an explicit --rule-file, the ADD pointer goes to .claude/rules/add-workflows.md
-// and CLAUDE.md keeps only a reference bullet. CLAUDE-only — AGENTS.md/.clinerules stay inline.
-const RULES_FILE_REL = path.join(".claude", "rules", "add-workflows.md");
-const WORKFLOW_HEADINGS = ["Rules & Workflows", "Workflows", "Rules"];
-const RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md";
-
-// True when the ADD block belongs in .claude/rules/add-workflows.md instead of inline.
-// Re-derived from disk: explicit flag, a ccsk project (.ccsk/), or a rule file already present.
-function ruleFileMode(root, flag) {
-  if (flag) return true;
-  try {
-    if (fs.existsSync(path.join(root, ".ccsk")) &&
-        fs.statSync(path.join(root, ".ccsk")).isDirectory()) return true;
-    if (fs.existsSync(path.join(root, RULES_FILE_REL))) return true;
-  } catch (_e) { /* fail-soft */ }
-  return false;
-}
-
-// Remove an inline ADD:BEGIN..END region (migration), collapsing the gap. An unterminated
-// BEGIN is left as-is rather than eating the rest of the file.
-function stripInlineBlock(text) {
-  const begin = text.indexOf(GUIDE_BEGIN);
-  if (begin === -1) return text;
-  let end = text.indexOf(GUIDE_END, begin);
-  if (end === -1) return text;
-  end += GUIDE_END.length;
-  const head = text.slice(0, begin).replace(/\n+$/, "");
-  const tail = text.slice(end).replace(/^\n+/, "");
-  if (head && tail) return head + "\n\n" + tail;
-  return head || tail;
-}
-
-// Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a fresh
-// '## Workflows' section. Caller guarantees the bullet is absent.
-function insertRuleReference(text) {
-  const lines = text.split("\n");
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/^(#{1,6})\s+(.*?)\s*$/);
-    if (m && WORKFLOW_HEADINGS.some((h) => m[2].trim().toLowerCase() === h.toLowerCase())) {
-      headingIdx = i;
-      break;
-    }
-  }
-  if (headingIdx === -1) {
-    const body = text.replace(/\n+$/, "");
-    const sep = body ? "\n\n" : "";
-    return body + sep + "## Workflows\n\n" + RULE_REF_LINE + "\n";
-  }
-  const level = lines[headingIdx].match(/^(#{1,6})/)[1].length;
-  let end = lines.length;
-  for (let j = headingIdx + 1; j < lines.length; j++) {
-    const m = lines[j].match(/^(#{1,6})\s+/);
-    if (m && m[1].length <= level) { end = j; break; }
-  }
-  let insertAt = headingIdx + 1;
-  for (let j = headingIdx + 1; j < end; j++) {
-    if (lines[j].trim()) insertAt = j + 1;
-  }
-  lines.splice(insertAt, 0, RULE_REF_LINE);
-  return lines.join("\n");
-}
-
-// Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating any prior
-// inline ADD block out. created|updated|unchanged|skipped; .bak on change; fail-soft.
-function ensureClaudeReference(claudeMd) {
-  try {
-    const existed = fs.existsSync(claudeMd);
-    const current = existed ? fs.readFileSync(claudeMd, "utf8") : "";
-    let next = stripInlineBlock(current);
-    if (next.indexOf("add-workflows.md") === -1) next = insertRuleReference(next);
-    if (!next.endsWith("\n")) next += "\n";
-    if (next === current) return "unchanged";
-    if (existed) fs.writeFileSync(claudeMd + ".bak", current);
-    fs.writeFileSync(claudeMd, next);
-    return existed ? "updated" : "created";
-  } catch (e) {
-    warn("could not write CLAUDE.md — " + (e && e.message ? e.message : e) + "; skipped");
-    return "skipped";
-  }
-}
-
-// Rule-file variant of writeAgentPointer for the Claude profile: write the ADD pointer block to
-// .claude/rules/add-workflows.md and leave a reference in CLAUDE.md. Fail-soft.
-function writeRuleFilePointer(target, profile) {
-  const rulesPath = path.join(target, RULES_FILE_REL);
-  const block = agentPointerBlock(profile);
-  try {
-    if (fs.existsSync(rulesPath)) {
-      const current = fs.readFileSync(rulesPath, "utf8");
-      const begin = current.indexOf(GUIDE_BEGIN);
-      let next;
-      if (begin !== -1) {
-        const endIdx = current.indexOf(GUIDE_END, begin);
-        if (endIdx !== -1) {
-          next = current.slice(0, begin) + block + current.slice(endIdx + GUIDE_END.length);
-        } else {
-          next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
-        }
-      } else {
-        next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
-      }
-      if (next !== current) {
-        fs.writeFileSync(rulesPath + ".bak", current);
-        fs.writeFileSync(rulesPath, next);
-      }
-    } else {
-      fs.mkdirSync(path.dirname(rulesPath), { recursive: true });
-      fs.writeFileSync(rulesPath, block + "\n");
-    }
-  } catch (e) {
-    warn("could not write " + RULES_FILE_REL + " — " + (e && e.message ? e.message : e) + "; skipped");
-    return "skipped";
-  }
-  ensureClaudeReference(path.join(target, "CLAUDE.md"));
-  return "ok";
-}
-
 // --- interactive layer (clack on a real TTY; plain text everywhere else) -----
 // Designed-for-failure: any doubt (non-TTY, CI, --yes, a failed import, an
 // un-promptable stream) degrades to the EXACT plain-text path below. The clack
@@ -650,16 +527,7 @@ function dropFiles(args, target, profile, intent) {
   // Agent detection: write THE detected agent's integration file (a marker-delimited
   // pointer init's sync-guidelines later supersedes) + tailor the closing next-step.
   // Best-effort + fail-soft — never aborts the successful drop above.
-  // Rule-file mode (ccsk projects / --rule-file) relocates the CLAUDE.md pointer to
-  // .claude/rules/add-workflows.md + a reference — CLAUDE-only; other agents stay inline.
-  if (profile.integration_file === "CLAUDE.md" && ruleFileMode(target, args.ruleFile)) {
-    if (fs.existsSync(path.join(target, ".ccsk"))) {
-      log("  ccsk detected — ADD rules go to .claude/rules/add-workflows.md");
-    }
-    writeRuleFilePointer(target, profile);
-  } else {
-    writeAgentPointer(target, profile);
-  }
+  writeAgentPointer(target, profile);
 
   // Gemini CLI auto-loads GEMINI.md, not AGENTS.md — so for the gemini profile we ALSO merge
   // .gemini/settings.json (context.fileName) to load the AGENTS.md pointer. Fail-soft + idempotent.
@@ -1985,7 +1853,4 @@ module.exports = {
   scopeOptions: scopeOptions,
   writeIntentNote: writeIntentNote,
   writeGeminiSettings: writeGeminiSettings,
-  ruleFileMode: ruleFileMode,
-  ensureClaudeReference: ensureClaudeReference,
-  writeRuleFilePointer: writeRuleFilePointer,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "2.1.0",
+  "version": "2.3.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

@@ -3,7 +3,7 @@ name: add
 description: >-
   ADD (AI-Driven Development) — a minimal, state-tracked workflow: the AI writes
   the code, the human owns direction and verification. Drives every feature through
-  one lean PLAN.md: Specify → Scenarios → Plan → Tests → Build → Verify → Observe,
+  one lean PLAN.md: Specify → Plan → Tests & Scenarios → Build → Verify → Observe,
   red/green TDD built in. Use whenever a repo has `.add/`, or the user says "add",
   "start a task", "next phase", "specify this feature", "ADD method", "AI-driven
   development", or wants spec/tests-first discipline over vague-prompt coding. Also
@@ -15,7 +15,7 @@ argument-hint: "status | init | continue | --todo <text> | [describe new short g
 license: MIT
 metadata:
   author: add
-  version: "2.0.0"
+  version: "2.3.0"
 ---
 
 # ADD — memory · judgment · conscience (the agent is the hands)
@@ -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) ·
+   §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) ·
+   §4 TESTS & SCENARIOS — the red suite (cases live here; optional inline gherkin when a human needs it): one test per Must & per Reject (a Must/Reject encoded in no §4 test = §1 not understood — stop); minor behaviors are prose build-guidance, not gated; 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/deltas.md

@@ -43,7 +43,7 @@ If a learning touches two, ask "which competency, once updated, would have PREVE
 
 ```
 emit (OBSERVE)        human review
-   open  ───────────▶  folded     (merged into PROJECT.md; version bumps)
+   open  ───────────▶  folded     (merged into its `.add/specs/<dd>` spec; version bumps)
          └──────────▶  rejected   (deliberately NOT consolidated — trail kept)
 ```
 

package/skill/add/design.md

@@ -42,7 +42,7 @@ Record **before** review-domain: project **defaults** in DESIGN.md's `## Design
 
 ### 1 · review-domain
 Start from the **domain**, not a blank canvas. Read the domain model — entities, flows, the
-ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature needs
+ubiquitous language in `.add/specs/domain.md` / `GLOSSARY.md` — and derive **which screens** the feature needs
 + each screen's **regions**. Map each entity to a *presentational* component (owns no domain
 decision). Output: the screen list + regions.
 

package/skill/add/phases/build.md

@@ -5,6 +5,28 @@ acceptance check — passes, without changing any test or the contract. This is
 AI leads; §1–§4 removed all ambiguity. Write code into `.add/tasks/<slug>/src/` (a non-coding
 task writes its artifact to the path its §5 Scope declares).
 
+## The reasoning discipline — build's slice of the arc (definitions: `phases/direction.md`)
+
+**Fluent ≠ true** holds in code: a diff feels done in proportion to how much you wrote, not how
+much you verified — a green you haven't refuted is a claim, not evidence. Run the arc per batch:
+
+- **FRAME** — restate the batch's tests and the frozen §3 clause they cover before writing a line.
+- **GROUND** — open every anchor before editing it; a recalled file/symbol/flag is `[PRIOR]`
+  until re-confirmed against the live tree THIS session; a live read outranks memory.
+- **REASON** — name the mechanism ("because…"), simulate one concrete input through the change
+  before committing it; when a red survives a fix, hold a second hypothesis instead of patching harder.
+- **ATTACK** — before presenting green: re-run the suite fresh, then reviewer-read your own diff
+  hunting the cheap falsifying input (file · line · values). An earned green is one you tried to
+  kill. Security findings stay HARD-STOP.
+- **DELIVER** — the green report leads with the outcome and tags its claims: a pass you ran THIS
+  session is `[OBSERVED]`; a remembered pass is `[PRIOR]` — never present it bare.
+- **Constraint loop on the §5 Scope allowlist** — don't eyeball it: list the files actually
+  touched (`git status` / diff) and check each against the declared Scope tokens mechanically
+  before the gate; a miss is `scope_violation` — caught by you, not by the engine.
+- **Follow-through (the Floor's second check)** — green tests ≠ the goal reached; simulate the
+  human's end state once — run the artifact under the BARE declared runtime — before calling
+  the batch done.
+
 ## Work in small batches
 
 Pick ONE task-sized slice, restate its tests, implement, iterate to green —
@@ -76,4 +98,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)
@@ -123,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
@@ -141,7 +171,10 @@ 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). 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>
@@ -151,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").
-- [ ] §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 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>
 
 ---
@@ -173,7 +207,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 +249,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?
+- **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
+  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?
@@ -231,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.
 
@@ -247,6 +299,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 +332,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

@@ -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.
@@ -36,7 +57,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 +65,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 |
 |---------|------|
@@ -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