@pilotspace/add 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.
 
+## [1.7.1] — 2026-06-18
+
+Installer depth and method quality release: the onboarding installer gains
+brand-aware prompts, readiness detection, and intent handoff; SOUL.md is now
+seeded on first install and update; scope drafting and build verification gain
+new depth guards. All additive; no breaking changes.
+
+### Added
+- **Brand-aware guided installer (`installer-smarts`)** — `add init` now prompts
+  for the user's brand/project name and detects whether ADD is already present
+  (readiness check); defaults to global scope and captures the user's first
+  intent, handing it off to the first `/add` session via `.add/.intent`.
+- **SOUL.md seeded on install and update (`installer-soul-seed`)** — `add init`
+  and `add update` now seed `.add/SOUL.md` from the bundled voice template if it
+  does not yet exist, so the voice file is present from the first session without
+  waiting for `add.py init`.
+- **Build expectations in VERIFY (`verify-expectations`)** — the §6 VERIFY step
+  gains a Build-expectations block: the AI pre-declares observable outcomes derived
+  from §2 scenarios + §3 contract, and verify confirms them — so a build is checked
+  correct, not merely test-green.
+
+### Changed
+- **Scope drafting quality guard (`scope-drafting-quality`)** — the scope guide now
+  requires the goal to be grounded in current project assets and the milestone map
+  before the goal sentence is drafted; a draft well-formedness gate catches
+  incomplete MILESTONE.md shapes early.
+
 ## [1.7.0] — 2026-06-18
 
 The installer & onboarding release: standing up — or repairing — ADD is now one

package/bin/cli.js

@@ -119,6 +119,63 @@ function detectAgent(env) {
   return generic;
 }
 
+// A PATH lookup (no spawn): is an executable named `cmd` on PATH? Fail-soft -> null.
+// Injectable into the enriched detector so the dev machine's installed agents never pollute tests.
+function whichSync(cmd) {
+  try {
+    const dirs = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32"
+      ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";")
+      : [""];
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        const hit = path.join(dir, cmd + ext);
+        if (fs.existsSync(hit)) return hit;
+      }
+    }
+  } catch (_e) { /* fail-soft */ }
+  return null;
+}
+
+// ADDITIVE enrichment for the INTERACTIVE default — never replaces detectAgent (which stays
+// env-only; test_agent_detect pins it, the non-interactive write uses it). Precedence:
+// env signal (authoritative) > a CLAUDE.md in the target (repo signal; AGENTS.md is ambiguous,
+// so it does NOT pick) > an installed agent CLI (machine signal; PATH lookup only) > generic.
+// Pure + fail-soft: a throwing probe reads as absent. `which` is injectable for hermetic tests.
+function detectAgentEnriched(env, target, which) {
+  which = which || whichSync;
+  const base = detectAgent(env);
+  if (base.id !== "generic") return base;              // env signal wins
+  const byId = {};
+  for (const p of AGENT_PROFILES) byId[p.id] = p;
+  try {
+    if (target && fs.existsSync(path.join(target, "CLAUDE.md"))) return byId.claude;   // repo signal
+  } catch (_e) { /* fall through */ }
+  for (const id of ["claude", "codex", "opencode"]) {
+    try { if (which(id)) return byId[id]; } catch (_e) { /* probe absent */ }   // machine signal
+  }
+  return base;                                         // generic
+}
+
+// Fail-soft pre-flight summary for the INTERACTIVE path (the caller gates):
+// "Pre-flight: git <✓|–> · python3 <✓|–> · agent: <label>". Each probe is a PATH lookup;
+// a failure reads as absent. Never throws.
+function readinessLine(env, target, which) {
+  env = env || process.env;
+  which = which || whichSync;
+  const caps = terminalCaps(env, process.stdout);
+  const tick = caps.unicode ? "✓" : "+";
+  const cross = caps.unicode ? "–" : "-";
+  const sep = caps.unicode ? " · " : " | ";
+  const have = (cmd) => { try { return !!which(cmd); } catch (_e) { return false; } };
+  let label;
+  try { label = detectAgentEnriched(env, target, which).label; }
+  catch (_e) { label = "your AI agent"; }
+  const mark = (ok) => (ok ? tick : cross);
+  return "Pre-flight: git " + mark(have("git")) + sep +
+         "python3 " + mark(have("python3")) + sep + "agent: " + label;
+}
+
 function agentPointerBlock(profile) {
   return (
     GUIDE_BEGIN + "\n" +
@@ -194,10 +251,73 @@ async function loadClack() {
   return import("@clack/prompts");
 }
 
-// Returns { cancelled, target }. A cancel happens BEFORE any file is written, so a
+// --- brand + feature showcase (interactive path only; fail-soft) -------------
+// Wordmark + value line + the 7-step Specify->Observe loop, rendered BEFORE the first
+// prompt on the interactive path only — so the non-interactive byte stream is unchanged.
+// The 7 labels are the real ADD phases (grounded in the method, never invented). Fail-soft:
+// any draw error is swallowed so a banner can never abort the install. No color is emitted
+// (default accent: none); the glyphs / tagline / accent are a SWAPPABLE content slot.
+const BRAND_LOOP = ["Specify", "Scenarios", "Contract", "Tests", "Build", "Verify", "Observe"];
+
+function terminalCaps(env, stream) {
+  const width = Number(env.COLUMNS) || (stream && stream.columns) || 80;
+  const enc = env.LC_ALL || env.LC_CTYPE || env.LANG || "";
+  const unicode = /utf-?8/i.test(enc) && !env.ADD_INSTALLER_ASCII;
+  return { width: width, unicode: unicode };
+}
+
+function brandLines(caps) {
+  const head = (caps.unicode && caps.width >= 40)
+    ? [
+        " █████╗ ██████╗ ██████╗",
+        "██╔══██╗██╔══██╗██╔══██╗",
+        "███████║██║  ██║██║  ██║",
+        "██╔══██║██║  ██║██║  ██║",
+        "██║  ██║██████╔╝██████╔╝",
+        "╚═╝  ╚═╝╚═════╝ ╚═════╝ ",
+      ]
+    : ["ADD"];                                  // plain-ASCII wordmark fallback
+  const arrow = caps.unicode ? " → " : " -> ";
+  const dash = caps.unicode ? " — " : " - ";
+  return head.concat([
+    "AI-Driven Development",
+    "",
+    "Spec-and-tests-first development" + dash + "any agent, through the CLI, no lost context.",
+    "The loop ADD drives with you:",
+    "  " + BRAND_LOOP.join(arrow),
+    "",
+  ]);
+}
+
+function renderBrand(env, stream) {
+  try {
+    env = env || process.env;
+    stream = stream || process.stdout;
+    stream.write(brandLines(terminalCaps(env, stream)).join("\n") + "\n");
+  } catch (_e) { /* fail-soft: a banner must never abort the install */ }
+}
+
+// The two install-scope choices — global-first (recommended) vs self-contained. PURE +
+// exported (the pip _scope_options twin) so the recommended pick + its why are hermetically
+// testable; the interactive scope SELECT renders these.
+function scopeOptions() {
+  return [
+    { value: "global", label: "Global home + this project",
+      hint: "a shared ~/.add + ~/.claude/skills/add reused by every project (this project still gets its own copy)",
+      recommended: true },
+    { value: "project", label: "This project only",
+      hint: "self-contained + git-tracked: nothing is written outside this folder" },
+  ];
+}
+
+// Returns { cancelled, target, profile, global }. A cancel happens BEFORE any file is written, so a
 // cancelled run leaves the target untouched. Without a real TTY to read (the forced
-// test seam), we cannot prompt — abort safely rather than hang.
-async function runClackPreamble(clack, target, detected) {
+// test seam), we cannot prompt — abort safely rather than hang. `askScope` is false when an
+// explicit --global already chose the scope (honored, not re-asked).
+async function runClackPreamble(clack, target, detected, askScope) {
+  renderBrand(process.env, process.stdout);   // brand + showcase BEFORE the first prompt
+  try { log(readinessLine(process.env, target)); }   // pre-flight: git · python3 · agent (fail-soft)
+  catch (_e) { /* the pre-flight line is informational — never block the install */ }
   clack.intro("ADD — AI-Driven Development");
   if (!process.stdin.isTTY) return { cancelled: true, target: target };
   const chosen = await clack.text({
@@ -207,6 +327,19 @@ async function runClackPreamble(clack, target, detected) {
   if (clack.isCancel(chosen)) return { cancelled: true, target: target };
   const ok = await clack.confirm({ message: "Write the ADD skill + tooling + book here?" });
   if (clack.isCancel(ok) || !ok) return { cancelled: true, target: target };
+  // global-first SCOPE step (after the target confirm, before agent-detect) — recommended
+  // global home, explicit pick; skipped when --global already chose. global stays ADDITIVE.
+  let scopeGlobal = false;
+  if (askScope) {
+    const opts = scopeOptions();
+    const scope = await clack.select({
+      message: "Install scope?",
+      options: opts.map((o) => ({ value: o.value, label: o.label, hint: o.hint })),
+      initialValue: opts.find((o) => o.recommended).value,
+    });
+    if (clack.isCancel(scope)) return { cancelled: true, target: target };
+    scopeGlobal = scope === "global";
+  }
   // agent-detect STEP (seeded delta: a STEP in THIS flow, via the clack ui layer) — the
   // user confirms or overrides the detected agent before any file is written.
   const picked = await clack.select({
@@ -216,13 +349,37 @@ async function runClackPreamble(clack, target, detected) {
   });
   if (clack.isCancel(picked)) return { cancelled: true, target: target };
   const profile = AGENT_PROFILES.find((p) => p.id === picked) || detected;
-  return { cancelled: false, target: String(chosen || target), profile: profile };
+  // LAST optional step — a one-line build intent for `/add` to read. Fully optional: a clack
+  // cancel or an empty answer SKIPS (intent ""); the install has already been confirmed, so this
+  // never aborts. A NOTE only — it never triggers init.
+  let intent = "";
+  const typed = await clack.text({
+    message: "What do you want to build first? (optional — Enter to skip)",
+    placeholder: "", defaultValue: "",
+  });
+  if (!clack.isCancel(typed) && typed) intent = String(typed).trim();
+  return { cancelled: false, target: String(chosen || target), profile: profile, global: scopeGlobal, intent: intent };
+}
+
+// Persist `intent` as a NOTE at <target>/.add/.intent for `/add` to read — iff non-empty.
+// DEFERRED-INIT: inert text only; never runs add.py/init, never touches state.json. Fail-soft
+// (a write error is swallowed — the note is best-effort, never a reason to fail the install).
+// Returns whether the note was written. Twin of _installer.py:_write_intent_note.
+function writeIntentNote(target, intent) {
+  const text = (intent || "").trim();
+  if (!text) return false;
+  try {
+    const addDir = path.join(target, ".add");
+    fs.mkdirSync(addDir, { recursive: true });        // .add/ exists post-drop; recursive mkdir is a no-op then
+    fs.writeFileSync(path.join(addDir, ".intent"), text + "\n");
+    return true;
+  } catch (_e) { return false; }
 }
 
 // The drop — now a RECONCILE: restore missing managed trees + refresh present ones
 // (sweep orphans) + report per-tree status. Byte-compatible handoff with the prior
 // installer. The interactive path resolves a target then calls straight into this.
-function dropFiles(args, target, profile) {
+function dropFiles(args, target, profile, intent) {
   profile = profile || detectAgent(process.env);
   log("Installing ADD into " + target);
   reconcile(args, target);
@@ -232,6 +389,9 @@ function dropFiles(args, target, profile) {
   // Best-effort + fail-soft — never aborts the successful drop above.
   writeAgentPointer(target, profile);
 
+  // Optional build-intent NOTE for `/add` to read — "" (skip / non-interactive) -> no-op.
+  writeIntentNote(target, intent);
+
   // NO step 4: the installer DROPS FILES ONLY. Initialisation is deferred to the AI
   // (via `/add`) or a CLI user — a pre-run plain `add.py init` would grandfather-lock
   // the v12 lock-down gate before `/add` runs (see file header). So no Python is run here.
@@ -255,12 +415,18 @@ async function cmdInit(args) {
 
   let chosenTarget = target;
   let profile = detectAgent(process.env);     // default: non-interactive / fallback
+  let intent = "";                            // build-intent NOTE — stays "" on the non-interactive path
   if (interactive(args)) {
     let clack = null;
     try { clack = await loadClack(); }
     catch (_e) { warn("clack unavailable — falling back to plain-text install"); }
     if (clack) {
-      const outcome = await runClackPreamble(clack, target, profile);
+      // enriched seed (env > CLAUDE.md > installed CLI) for the agent-select default; the user
+      // still confirms/overrides before any write. The non-interactive write below stays env-only.
+      const detected = detectAgentEnriched(process.env, target);
+      // an explicit --global/--global-data already chose the scope — don't re-ask it.
+      const askScope = !(args.global || args.globalData);
+      const outcome = await runClackPreamble(clack, target, detected, askScope);
       if (outcome.cancelled) {
         // the exit code IS the contract; a closed-pipe stdout (EPIPE) must not
         // mask the cancel — guard the courtesy message, never let it throw.
@@ -271,13 +437,15 @@ async function cmdInit(args) {
       chosenTarget = path.resolve(outcome.target);
       if (!fs.existsSync(chosenTarget)) fail("target directory does not exist: " + chosenTarget);
       if (outcome.profile) profile = outcome.profile;   // honor the user's override
+      if (outcome.global) args.global = true;           // honor the interactive scope pick (additive)
+      intent = outcome.intent || "";                    // optional build-intent NOTE (written after the drop)
     }
   }
   if (args.globalData) args.global = true;   // --global-data implies --global (need a home)
   // OPT-IN global home, BEFORE the per-project drop (fail-closed if the home is unwritable
   // or its registry is corrupt — the package + the self-contained default stay usable).
   if (args.global) installGlobal(args, chosenTarget);
-  dropFiles(args, chosenTarget, profile);
+  dropFiles(args, chosenTarget, profile, intent);
   // OPT-IN data persist, AFTER the drop (one-way snapshot of existing user-data).
   if (args.globalData) installGlobalData(chosenTarget);
 }
@@ -597,4 +765,18 @@ async function main() {
   }
 }
 
-main().catch((e) => fail(e && e.message ? e.message : String(e)));
+// Run ONLY when invoked directly (the bin / npx entry). When `require()`d — the test harness
+// imports the pure detectors — main() must NOT fire (it would parse argv + install). This guard
+// changes no runtime behavior on the real CLI path; the non-interactive output stays byte-identical.
+if (require.main === module) {
+  main().catch((e) => fail(e && e.message ? e.message : String(e)));
+}
+
+module.exports = {
+  detectAgent: detectAgent,
+  detectAgentEnriched: detectAgentEnriched,
+  readinessLine: readinessLine,
+  whichSync: whichSync,
+  scopeOptions: scopeOptions,
+  writeIntentNote: writeIntentNote,
+};

package/docs/08-step-6-verify.md

@@ -25,9 +25,12 @@ Verify can be resolved two ways, set per task by the `autonomy:` header (see [go
 
 ## Part one — confirm the evidence
 
+Before the build, the task pre-declares its **build expectations** — the observable outcomes a correct build must produce, read off §2's scenarios and §3's contract. Confirm each one here against evidence you can see, not a restated test name: this is what makes the gate check the build is *right*, not merely that the suite is green.
+
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during the build.
+- [ ] Every pre-declared build expectation is confirmed by real evidence (not merely a green test).
 
 If any of these is false, stop here and return to the build; there is nothing to verify yet.
 
@@ -71,6 +74,7 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 ## The verification checklist
 
 - [ ] All tests pass (the evidence).
+- [ ] Every pre-declared build expectation is confirmed by observable evidence.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -63,7 +63,9 @@ python3 .add/tooling/add.py status
 (the `soul-self-improve` path proposes voice deltas the human confirms).
 
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
-  `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
+  `no .add/ project found`) → enter **autonomous setup**: first, if `.add/.intent` exists, read it — the
+  one-line first-build intent the user gave the installer (a NOTE, never an init trigger) — and let it seed
+  your kickoff suggestion (`phases/0-setup.md`); then YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
   `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human baseline approval.
 - **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
@@ -110,7 +112,7 @@ See `run.md`.
 
 Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
 milestone close), follow `report-template.md` — open with the ARC (goal · done · plan,
-engine-sourced), then SUMMARY → DECISION → ⚠ FLAGS → EVIDENCE → NEXT, show-before-ask, never
+engine-sourced), then SUMMARY → DECISION → FLAGS → DECIDED → EVIDENCE → NEXT, show-before-ask, never
 pre-stamp a decision point — and the question is a summary, never the artifact.
 
 In **observe**, also emit **lessons learned** — learnings tagged by which of the five

package/skill/add/intake.md

@@ -31,6 +31,11 @@ First ask "does this change already-frozen scope?" → if yes, it is a `change-r
 → `new-major`; a slice of a live theme → `sub-milestone`; fits the active milestone
 → `task`.
 
+**One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's
+stated scope, do NOT force it into `sub-milestone` (which requires "too big for one task").
+Instead: create a new micro-milestone to house it (`new-milestone` + `new-task`). The
+micro-milestone gives the task ledger attribution and clear exit criteria without inflating scope.
+
 ## What you emit (the proposal)
 
 Present the proposal to the human via `report-template.md` — open with the ARC (goal · done ·

package/skill/add/phases/6-verify.md

@@ -12,11 +12,20 @@ sufficient. Fill **§6** in TASK.md including the GATE RECORD.
 > or whenever residue is found, this phase is **human-led** and the checks below
 > are the human's.
 
+## Before you build — declare the build expectations
+
+Fill the §6 **Build expectations** block BEFORE you start Build: the OBSERVABLE outcomes a
+correct build must produce, derived from §2 SCENARIOS + §3 CONTRACT. At this gate, confirm each
+one against real evidence (the `confirmed by` column) — so verify proves the build is *correct*,
+not merely that the suite is green. An expectation with no evidence is not yet verified; passing
+tests on inputs you thought of never substitute for the outcome you promised.
+
 ## Part one — confirm the evidence
 
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during build.
+- [ ] Every §6 Build expectation is confirmed by real evidence (not just a green test).
 
 If any is false, stop and return to Build — there is nothing to verify yet.
 

package/skill/add/report-template.md

@@ -8,12 +8,12 @@ replacement for the digest.
 Use it every time you report at or near a decision point: an intake proposal, a
 bundle approval, a verify gate, a task completion, a milestone close.
 
-## The decision arc — rendered first, above the five blocks
+## The decision arc — rendered first, above the report blocks
 
 Every report at a human gate opens with the **ARC** — three labelled lines that
 place the decision in the work's whole arc, so the human confirms with sight of
 where this is going, not just the step in front of them. Render it first, then a
-separator, then the unchanged five blocks below:
+separator, then the report blocks below:
 
 ```
 ARC  goal: <the milestone / project goal this decision serves>
@@ -48,14 +48,19 @@ and `add.py` output disagree, the engine wins — fix the arc, not the engine.
 - **intake** — `goal:` the sized request · `done:` classified new-major,
   rationale stated · `plan:` create the milestone → first contract → goal.
 
-## The five blocks, in order
+## The report blocks, in order
+
+The blocks below are the CORE set, rendered in order at every decision-point
+report. Render every one (write "none" rather than dropping a block); add MORE
+blocks when a specific report needs them (see "Beyond the core blocks" below).
 
 ```
-SUMMARY   one line: intent + target + where we are
-DECISION  what you need from the human (or "none — FYI")
-⚠ FLAGS   lowest-confidence first, why + cost-if-wrong
+SUMMARY   one line: intent + target + where we are + what we done
+DECISION  what you need from the human (or "none — FYI") — exactly one
+FLAGS     lowest-confidence first: why + cost-if-wrong
+DECIDED   highest-confidence first: the autonomous calls you made + why each was safe
 EVIDENCE  small table: tests · gates · parity · check — engine-sourced
-NEXT      the single next action + what it unlocks
+NEXT      the recommended next actions, ranked (top ▶ highlighted, bolded) + what each unlocks
 ```
 
 1. **SUMMARY** — one line carrying intent + target + position, e.g.
@@ -67,16 +72,35 @@ NEXT      the single next action + what it unlocks
    description (see "guided choice" below). Exactly one decision per report, or an
    explicit "none — FYI". If a decision exists, ask it after everything below has
    been shown (show-before-ask).
-3. **⚠ FLAGS** — lowest-confidence first, each with *why* confidence is lowest and the
+3. **FLAGS** — lowest-confidence first, each with *why* confidence is lowest and the
    *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`),
    quote them verbatim and keep their document order — extraction ≠ judgment.
-4. **EVIDENCE** — engine-sourced facts pasted from `add.py` output, never
+4. **DECIDED** — the counterpart to FLAGS: the high-confidence calls you settled
+   autonomously WITHOUT a gate, highest-confidence first, each with *why* it was
+   safe (the change-type or evidence that earned the autonomy). FLAGS surfaces the
+   lowest-confidence calls so the human can challenge them; DECIDED surfaces the
+   highest-confidence ones so the human can see what you closed without asking. "none" when you made no
+   autonomous calls. NEVER list a security / residue / lowered-autonomy call here —
+   those always escalate in DECISION (see the Hard rules), never auto-decided.
+5. **EVIDENCE** — engine-sourced facts pasted from `add.py` output, never
    re-typed from memory. If your prose and the engine disagree, the engine
    wins: fix the engine or the data, not the sentence.
-5. **NEXT** — one action and what it unlocks. Mirror the rollup's DECIDE NEXT
-   line when it is right; overrule it only with a stated reason (e.g. planned
+6. **NEXT** — the recommended next actions as a ranked list, the top one marked
+   `▶` and each with what it unlocks. NEXT is **informational, not a second gate**:
+   it shows the menu of what's next and never adds a decision — the one decision
+   stays the DECISION block. Mirror the rollup's DECIDE NEXT line for the top
+   action when it is right; overrule it only with a stated reason (e.g. planned
    tasks the state file cannot see yet).
 
+### Beyond the core blocks — add more when the decision needs it
+
+The six blocks above are the CORE set. When a specific report needs more than they
+carry — a `RISK` ledger, a `DIFF`, a `SCOPE` map, a `COST` estimate — add an extra
+block in the same shape (SCREAMING-CASE label · one-line intent · engine-sourced
+where it can be), placed AFTER EVIDENCE and BEFORE NEXT so NEXT always closes the
+report. Add a block only when it carries what the core six don't; never pad to look
+thorough — and never drop a core block; render "none" instead.
+
 ### The DECISION block as a guided choice
 
 When the human must choose, render block 2 as a **guided decision** — never a bare next step:
@@ -120,7 +144,7 @@ intent + what "yes" means + the flag count — pointing at the report above.
   **recommended pick** (`▶ … (recommended)`, exactly one) + its 1–3 described alternatives, every
   option carrying a one-line description; never a bare next step. `confidence.md` informs the pick;
   the human overrides freely. Not at `[you drive]` autonomous steps.
-- **Reconcile the count.** Before the ask, your ⚠ FLAGS must reconcile with
+- **Reconcile the count.** Before the ask, your FLAGS must reconcile with
   `add.py report --decide`'s open-item count. If your prose calls an item
   resolved while the digest still counts it open, the engine wins — fix the data
   (the TASK.md markers the digest reads), not the sentence. A report whose flag
@@ -133,10 +157,14 @@ intent + what "yes" means + the flag count — pointing at the report above.
 - **Honest scope.** "Done" means the request, not the last task: report
   "task 2/3", never "done" while approved scope remains.
 - **The question is a summary, never the artifact.** Every approval ask carries
-  two layers: a compact SUMMARY · DECISION · ⚠ FLAGS block sits in chat
+  two layers: a compact SUMMARY · DECISION · FLAGS block sits in chat
   immediately before the ask (positional), and the question text itself is a
   summary of two lines at most — intent + what "yes" means + the flag count —
   pointing at the report above (compositional). The full bundle, diff, or
   artifact lives only in the chat report; a question that re-carries it buries
   the decision.
+- **NEXT is not a second gate.** NEXT lists recommended next actions (ranked, top
+  `▶`); the single decision stays the DECISION block — NEXT never carries an approval ask.
+- **DECIDED never holds a gate-class call.** A security / residue / lowered-autonomy
+  call is escalated in DECISION, never reported as already auto-decided in DECIDED.
 </constraints>

package/skill/add/scope.md

@@ -20,6 +20,25 @@ scope drafting honors intake's classification — it never re-sizes a request:
 means one drafting pass, NOT auto-creation. Nothing is written to disk — single draft or the
 whole batch — until the human confirms. You propose; you wait.
 
+## Position the goal — ground in assets, relate to the milestone map   (do this FIRST)
+
+Before you draft the goal sentence — before Diverge below — position the request in what
+already exists. You cannot write a correct goal without knowing where it sits.
+
+1. **Ground in current assets.** Read the goal input against `PROJECT.md` (domain · spec ·
+   UI/UX), the code it touches, and the existing docs — so the goal is grounded in what the
+   project already is, not in what you assume.
+2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md`
+   and `.add/archive/*` — and name THIS request's relationship to them: *extends* theme X ·
+   *depends-on* Y · *overlaps* Z. Record that relationship in the `rationale` line you will write.
+3. **If the goal is already delivered** by an existing milestone, do NOT fork it — reject
+   `duplicate_goal` and route the request as a `task` or `change-request` (create nothing).
+
+This COMPLEMENTS `intake.md`'s bucket test (which weighs only whether a live milestone's goal
+covers the request); positioning also grounds the goal in current assets and relates it to the
+prior milestone map (`.add/milestones/*` + `.add/archive/*`) — which classification does not do.
+Point at intake for the bucket; do not restate it here.
+
 ## Brainstorm before you draft — co-specify at milestone level
 
 Don't draft a MILESTONE.md from thin input. Run the same three-move co-specify as a
@@ -45,6 +64,8 @@ Render the draft as a guided choice — the recommended scope + its described al
 
 - **goal** — ONE sentence, an outcome not an output ("a user can size any request", not "write
   intake.md"). If it needs an "and", it is probably two milestones.
+- **rationale** — the confirmed intake bucket + WHY (the theme · slice · fit), AND the milestone
+  relationship you captured in "Position the goal" above. One or two header lines; never in state.json.
 - **Scope In/Out** — the explicit anti-creep deferral list. Naming what is OUT is as important
   as what is IN; an empty Out list usually means the scope is not yet thought through.
 - **Shared decisions & glossary deltas** — cross-cutting rules every task must honor, named from
@@ -54,6 +75,22 @@ Render the draft as a guided choice — the recommended scope + its described al
   by phase; keep each task one-file-sized. Order by dependency, not by guesswork.
 - **Exit criteria** — observable, and **every exit criterion maps to a declared task slug**
   (no dangling criterion). Each line answers "which task delivers this, and how would we see it?"
+- **Close — ship review** + **Release steps** — leave these as the template at draft time: they are
+  **drafted-blank** here and filled LATER (Close at `milestone-done`, the close flow; Release steps when
+  the ship path is known, owned by `release.md`) — not scope drafting. Named here so you know the full
+  9-section shape and neither fill them early nor read a fresh draft as "incomplete".
+
+## Draft well-formedness gate   (a draft passes ALL of these before you propose it)
+
+A scope draft is well-formed — ready to show the human — only when:
+- [ ] the goal is ONE outcome sentence (no "and" — that is two milestones)
+- [ ] every exit criterion maps to a declared task slug (no dangling criterion)
+- [ ] `rationale` records the bucket + the milestone relationship from "Position the goal"
+- [ ] `Close — ship review` and `Release steps` are left as the template (drafted-blank)
+- [ ] the In/Out list names what is deferred (an empty Out list is unfinished thinking)
+
+Propose only a well-formed draft — an incomplete one is the gap that lets a milestone reach
+task breakdown half-formed.
 
 ## Reject codes (emit `{ reject, rationale }`, create nothing)
 
@@ -65,6 +102,9 @@ Render the draft as a guided choice — the recommended scope + its described al
   a malformed milestone. With no engine lint, you are the first check and the human is the backstop.
 - `no_milestone` — intake routed the request to `task` or `change-request`; scope drafting
   creates NO milestone. Honor the classification; do not invent milestone-sized scope.
+- `duplicate_goal` — the goal is already delivered by an existing milestone (live or in
+  `.add/archive/`). Do NOT fork it into a parallel milestone; route the request as a `task` or
+  `change-request` and create nothing. (Raised by the "Position the goal" step.)
 </reject_codes>
 
 ## Worked example (from this repo's own history)

package/tooling/templates/TASK.md.tmpl

@@ -133,6 +133,13 @@ Constraints: do NOT change any test or the contract; allow-list packages only; a
 - [ ] layering & dependencies follow CONVENTIONS.md
 - [ ] 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 outcome a correct build must produce> — confirmed by <how / where>
+- [ ] <another observable outcome> — confirmed by <evidence seen>
+
 ### Deep checks — do not skim (fill the path that applies; the resolver judges which)
 - [ ] WIRING (code) — every new symbol is referenced; record where / how confirmed
 - [ ] DEAD-CODE (code) — no new unused or orphaned symbol introduced