@pilotspace/add 1.7.3 → 1.9.0

package/skill/add/phases/7-observe.md

@@ -1,8 +1,6 @@
 # Phase 7 — Observe (feed the next loop)
 
-Goal: release deliberately, watch reality, and turn what you learn into the next
-spec. Release is not the finish line — it is where the most reliable information
-about the feature finally appears. Fill **§7** in TASK.md.
+Goal: release deliberately, watch reality, and turn what you learn into the next spec. Fill **§7** in TASK.md.
 
 ## Do
 

package/skill/add/phases/fast-lane.md

@@ -0,0 +1,31 @@
+# Fast lane — less ceremony, same floor
+
+The fast lane is the **collapsed, opt-in task path for small work**. Same flow — ground → specify →
+contract → tests → build → verify — with fewer sections and the bundle approved in one pass. It
+**collapses** the ceremony; it never drops the floor. The human opts in (`--fast`); the engine never
+guesses that a task is small.
+
+## When
+
+Pick it for a **small, low-risk, roughly single-file change**. Stay on the full lane when the work
+wants its scenarios enumerated — a milestone or release, an architecture or security change, anything
+cross-cutting, or anything you are not yet sure is small. In doubt, run the full lane.
+
+## How
+
+1. `add.py new-task <slug> --fast` scaffolds the minimal `TASK.fast.md` (sections {0,1,3,4,5,6};
+   §2 SCENARIOS and §7 OBSERVE dropped — §1's Accept line carries the behavior a scenario would).
+2. Ground, draft §1 + §3, and **freeze the contract as one batched approval** — the single decision
+   point, led by the lowest-confidence flag.
+3. Write a **red** test (§4), run it failing for the right reason.
+4. Build (§5) to green, then record the **verify gate** (§6).
+
+## Floor kept, only collapsed
+
+Three things never move, on either lane: a **frozen** §3 before build · a **red** test before build ·
+a recorded **verify gate** at the end (a security finding is always HARD-STOP). A `--fast` task is
+freeze-gated under ANY milestone — `advance` refuses `contract_not_frozen` while §3 is a draft. Speed
+comes from **fewer sections + auto-gating**, not from cutting any of the three.
+
+Not a way around the contract, the red test, or the gate; not for milestones or releases; not
+engine-chosen — ceremony is human-owned.

package/skill/add/release.md

@@ -1,21 +1,13 @@
 # Release — cut a versioned ship, never an unwatched flip
 
-A project does not "release" because someone bumped a number. It releases when one or more
-**closed milestones** are bundled into a versioned, user-facing cut whose notes are evidence-backed,
-whose risk is disclosed, and whose behaviour is then watched. This guide is the **5th scope level** —
-after setup (`phases/0-setup.md`), intake (`intake.md` / `scope.md`), the milestone loop (`loop.md`),
-and stage graduation (`graduate.md`). It is a different verb from each of them:
+A project releases when ≥1 **closed milestones** are bundled into a versioned cut whose notes are evidence-backed, risk is disclosed, and behaviour is then watched. This is the **5th scope level** — distinct from milestone (feature-complete), graduation (rigor shift), and stage (mvp→prod).
 
-- a **milestone** is *feature-complete and consolidated*; a **release** is *shipped + watched*.
-- **graduation** changes the project's *rigor* (mvp→production); a **release** ships a *version*.
-  The axes are orthogonal — you cut releases at every stage (prototype preview · mvp beta · prod GA).
+- **milestone** = feature-complete and consolidated; **release** = shipped + watched.
+- **graduation** changes *rigor*; a **release** ships a *version*. Orthogonal axes.
 
-So a release is its own scope level: it bundles **≥1** closed milestone, and it may bundle several.
-You (the AI) **gather and propose**; the **human confirms and judges**; the engine records the cut
-and enforces a floor — it **never tags, publishes, or deploys** (the same stance as "the engine never
-renders" in `design.md` and "never spawns" in `advisor.md`). The outward act is the human's.
+You **gather and propose**; the **human confirms and ships**; the engine records the cut and enforces a floor — it **never tags, publishes, or deploys**.
 
-## The cue (what starts this)
+## The cue
 
 When ≥1 milestone is `done` AND archived AND not yet attributed to a release, `add.py status` prints:
 
@@ -23,93 +15,47 @@ When ≥1 milestone is `done` AND archived AND not yet attributed to a release,
   → releasable: N milestone(s) closed since last release
 ```
 
-That line is the trigger. It is a **tally** over unreleased-but-archived milestones — never a
-readiness judgment. It is silent until the first such milestone exists (a project that has never
-released, or has released everything, sees nothing here — grandfathered, zero change).
+That line is a tally over unreleased-but-archived milestones — never a readiness judgment.
 
 ## The flow
 
 One arc, seven steps: **cue → gather → draft notes → readiness floor → human confirms → cut → watch.**
 
-1. **Gather the release inventory** — run `add.py release-report` (add `--json` to branch on it). It
-   clusters the cut's evidence into labeled record-sets: the closed milestones since the last release ·
-   their **consolidated deltas** (the "what changed" record) · open RISK-ACCEPTED waivers riding into
-   the release · any open **security HARD-STOP** (a blocker) · the §2 scenarios to take live as monitors.
-   It **gathers, never judges** — there is no readiness verdict to read; the records are what you reason from.
-2. **Draft the release notes** — write a [Keep a Changelog](https://keepachangelog.com/) entry **from the
-   consolidated deltas + each milestone's goal** (reuse — those consolidated deltas ARE the changelog source;
-   you are not inventing the story, you are surfacing what the foundation already recorded). Group Added / Changed /
-   Fixed; name the headline capabilities concretely. Propose the **semver bump** — breaking→MAJOR,
-   feature→MINOR, fix-only→PATCH — and let the human confirm it (the version is a decision, not a default).
-3. **Meet the readiness floor** — before the cut the engine enforces a floor (see below): the suite is
-   green, **zero** open security HARD-STOP, and every RISK-ACCEPTED waiver shipping in this release is
-   signed AND disclosed in the notes. A security finding is a HARD-STOP here exactly as in verify —
-   never auto-passed, never shipped silent.
-4. **Human confirms the cut** — present via `report-template.md`, opening with the ARC (goal · done · plan):
-   the version you are shipping, the milestones + evidence that earn it, and the rollout + watch plan that
-   follows. Render the cut as a guided choice — the recommended version + its described alternatives
-   (per `report-template.md`). Show the drafted notes, the version, and the waivers being shipped. The human approves once
-   (the decision point) — never pre-stamped; you surface a summary to decide on, not the artifact itself.
-5. **Cut — record the marker** — only now run `add.py release <version> --notes <file>`. The engine
-   **records**: it prepends the CHANGELOG entry, stamps one append-only row (newest-first) in
-   `RELEASES.md` (date · version · milestones · waivers shipped · evidence), and attributes the bundled
-   milestones to this version (so the cue stops firing for them).
-6. **Ship — the human's outward act** — the engine has recorded the cut; the **human runs the tag /
-   publish / deploy** (`git tag`, `npm publish`, the deploy pipeline — tool-agnostic, whatever this project
-   ships through). The tag is the human-gated trigger, exactly the dogfooded recipe today. The engine never
-   performs it: design-for-failure lives in the pipeline the human owns, not in the method tool.
-7. **Watch — re-enter observe at the release scope level** — the §2 scenarios become live monitors for the
-   *released* version; live-registry / deploy confirmation is post-cut **evidence**, not a unit test. A
-   regression found in the wild re-enters at Specify as a **change request** → a narrowed **PATCH hotfix
-   release** (this same flow, scoped to the fix). Release is not the finish line — it is where the most
-   reliable information appears (`phases/7-observe.md`).
-
-## The floor (what the engine enforces)
-
-`add.py release <version>` is **guarded** — it refuses (non-zero exit, state byte-unchanged) on:
+1. **Gather** — run `add.py release-report` (`--json` to branch on it). It clusters the cut's evidence: closed milestones since last release · consolidated deltas · open RISK-ACCEPTED waivers · open security HARD-STOP (blocker) · §2 scenarios to take live as monitors. Gathers, never judges.
+2. **Draft notes** — write a [Keep a Changelog](https://keepachangelog.com/) entry from the consolidated deltas + each milestone's goal. Group Added / Changed / Fixed. Propose the **semver bump** (breaking→MAJOR, feature→MINOR, fix-only→PATCH) for human confirmation.
+3. **Readiness floor** — the engine enforces: suite green, zero open security HARD-STOP, every RISK-ACCEPTED waiver signed and disclosed in the notes.
+4. **Human confirms** — present via `report-template.md`, opening with the ARC (goal · done · plan). Render as a guided choice (per `report-template.md`). Never pre-stamp; show-before-ask.
+5. **Cut** — only now run `add.py release <version> --notes <file>`. The engine records: CHANGELOG entry, append-only `RELEASES.md` row (newest-first: date · version · milestones · waivers · evidence), milestone attribution.
+6. **Ship** — the **human** runs the tag / publish / deploy (`git tag`, `npm publish`, deploy pipeline). Engine never performs it.
+7. **Watch** — §2 scenarios become live monitors. A regression re-enters at Specify as a **change request** → PATCH hotfix release.
+
+## The floor
+
+`add.py release <version>` is **guarded** — refuses (non-zero exit, state byte-unchanged) on:
 
 <reject_codes>
-- `release_security_open` — an open security HARD-STOP exists. The non-negotiable; a security finding is
-  never shipped. Resolve it (a change request back to Specify) before the cut. `--force` does NOT override this.
-- `release_tests_red` — the suite is not green. Evidence, not a plausible diff, is what a release ships on.
-- `release_no_closed_milestone` — nothing new since the last release. The cut is a no-op; do **not** bump.
+- `release_security_open` — open security HARD-STOP exists. Never shipped. `--force` does NOT override this.
+- `release_tests_red` — suite not green.
+- `release_no_closed_milestone` — nothing new since last release.
 - `release_undisclosed_waiver` — a RISK-ACCEPTED waiver rides into the release but is absent from the notes.
-  Disclosure is the floor: a shipped risk the user can't read about is a hidden risk. Add it to the notes.
 </reject_codes>
 
-`--force` preserves human authority for grandfathered / edge cases (e.g. a first release of a brownfield
-adopt), mirroring `stage --force` — but it never overrides `release_security_open`. Use it deliberately,
-not as the normal path.
+`--force` preserves human authority for grandfathered / edge cases (e.g. brownfield first cut) — never overrides `release_security_open`.
 
-## Invariants (never break these)
+## Invariants
 
-- **The engine records; the human ships.** `add.py release` writes the CHANGELOG + ledger + attribution;
-  it never tags, publishes, or deploys. The outward act stays human-owned and tool-agnostic.
+- **Engine records; human ships.** `add.py release` writes CHANGELOG + ledger + attribution; never tags, publishes, or deploys.
 - **Security is a HARD-STOP at the cut**, not just at verify. No `--force`, no waiver, no exception.
-- **Notes draw from consolidated deltas** — release after `fold.md` has run, so the changelog surfaces
-  consolidated learnings, not raw open lessons. The lifecycle order is one line:
-  `milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
-- **The ledger is append-only (newest-first)** — like §Key Decisions, a release row is never rewritten;
-  a superseded or yanked version is recorded with a new row, never edited away.
-- **A release bundles, it does not equal.** One version may attribute several milestones; never force a
-  release per milestone.
-
-## Depth and reuse
-
-The shape is constant; the depth follows the stage (read it from `add.py status`):
-
-- **prototype / poc** — a one-line preview note + a tag; no deploy ceremony. The point is feedback, not GA.
-- **mvp** — full notes + tag + a guarded publish; watch the headline scenarios.
-- **production** — every step at full rigor: notes + tag + deploy behind a rollback-tested pipeline +
-  live scenario monitors + error-budget watch. The hotfix path (step 7) is first-class here.
-
-## Worked example (this method's own 1.5.0)
-
-The repo already runs this by hand. The `udd-design-loop` milestone closed (4/4) and consolidated into
-`foundation-version 33`; the human then drafted the `## [1.5.0]` CHANGELOG entry from those deltas,
-bumped the three version sources in lockstep, and the forward-pinned `test_release_1_5_0.py` asserted
-in-repo readiness (versions agree · changelog lineage survives · feature anchors named · engine
-untouched). The cut itself — the `git tag` that triggers the npm/PyPI publish — stayed human-gated, and
-the live-registry confirmation was gathered *after* the tag as verify evidence, never a unit test. This
-guide makes that ritual first-class: `release-report` gathers it, the floor enforces it, `add.py release`
-records it, and the human still owns the tag.
+- **Notes draw from consolidated deltas** — release after `fold.md` has run. Lifecycle order: `milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
+- **Ledger is append-only (newest-first)** — a release row is never rewritten; a yanked version gets a new row.
+- **A release bundles, it does not equal.** One version may attribute several milestones.
+
+## Depth by stage
+
+- **prototype/poc** — one-line preview note + tag; no deploy ceremony.
+- **mvp** — full notes + tag + guarded publish; watch headline scenarios.
+- **production** — full rigor: notes + tag + deploy behind rollback-tested pipeline + live monitors + error-budget watch. Hotfix path (step 7) is first-class.
+
+## Worked example
+
+The `udd-design-loop` milestone closed (4/4), consolidated into `foundation-version 33`; the human drafted `## [1.5.0]` from those deltas, bumped version sources in lockstep, and `test_release_1_5_0.py` asserted readiness. The `git tag` stayed human-gated; live-registry confirmation gathered *after* the tag as verify evidence, never a unit test.

package/skill/add/report-template.md

@@ -1,19 +1,12 @@
 # Chat reports — the decision-point template (for the AI, not for add.py)
 
-The engine renders artifacts (`report`, `report --decide`, `status`); this file
-governs the CHAT MESSAGE you wrap around them. The digest is the artifact BEHIND
-your presentation, never a replacement for it — and your prose is never a
-replacement for the digest.
+The engine renders artifacts (`report`, `report --decide`, `status`); this file governs the CHAT MESSAGE you wrap around them.
 
-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.
+Use it every time you report at or near a decision point.
 
 ## 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 report blocks below:
+Every report at a human gate opens with the **ARC** — three labelled lines placing the decision in the work's whole arc. Render it first, then a separator, then the report blocks:
 
 ```
 ARC  goal: <the milestone / project goal this decision serves>
@@ -21,38 +14,22 @@ ARC  goal: <the milestone / project goal this decision serves>
      plan: <this gate → the next step → the goal>
 ```
 
-- **goal** — the milestone or project goal the decision serves, read from the
-  `m-goal` line in `add.py status`; never re-typed from memory.
-- **done** — proven progress only: exit-criteria met/total and tasks done from
-  the rollup, plus what this gate proves. An honest fact, never a hope.
-- **plan** — this gate → the next step → the goal, mirroring the rollup's
-  `DECIDE NEXT` line.
-
-The arc is required at every human gate: **baseline-lock · contract-freeze ·
-verify · intake · scope · milestone-close · graduation**. The three labels stay
-constant; their content adapts to the gate. The arc is presentation only — it
-adds no gate and changes no PASS / RISK-ACCEPTED / HARD-STOP / freeze outcome.
-
-Its facts are engine-sourced, exactly like EVIDENCE below: goal = `m-goal` ·
-done = exit-criteria met/total + tasks done · plan = `DECIDE NEXT`. If your arc
-and `add.py` output disagree, the engine wins — fix the arc, not the engine.
-
-### Per-gate examples — one shape, gate-specific content
-
-- **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6
-  green, gate ready · `plan:` PASS this gate → wire the arc into every gate → goal.
-- **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence
-  flag surfaced · `plan:` freeze §3 → build → goal.
-- **milestone-close** — `goal:` … · `done:` exit-criteria 3/3 met, all tasks
-  done · `plan:` close → archive → the next milestone.
-- **intake** — `goal:` the sized request · `done:` classified new-major,
-  rationale stated · `plan:` create the milestone → first contract → goal.
+- **goal** — read from `m-goal` in `add.py status`; never re-typed from memory.
+- **done** — proven progress only: exit-criteria met/total, tasks done, what this gate proves. An honest fact, never a hope.
+- **plan** — this gate → the next step → the goal, mirroring the rollup's `DECIDE NEXT` line.
+
+The arc is required at every human gate: **baseline-lock · contract-freeze · verify · intake · scope · milestone-close · graduation**. It is presentation only — it adds no gate and changes no PASS / RISK-ACCEPTED / HARD-STOP / freeze decision.
+
+Its facts are engine-sourced (goal = `m-goal` · done = exit-criteria + tasks done · plan = `DECIDE NEXT`); if your arc and `add.py` disagree, the engine wins.
+
+### Per-gate examples
+
+- **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6 green · `plan:` PASS → wire the arc into every gate → goal.
+- **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence flag surfaced · `plan:` freeze §3 → build → goal.
 
 ## 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).
+Render every block (write "none" rather than dropping one); add MORE when needed.
 
 ```
 SUMMARY   one line: intent + target + where we are + what we done
@@ -63,47 +40,18 @@ EVIDENCE  small table: tests · gates · parity · check — engine-sourced
 NEXT      the recommended next actions, ranked (top ▶ highlighted, bolded) + what each unlocks
 ```
 
-1. **SUMMARY** — one line carrying intent + target + position, e.g.
-   "v13 task 2/3 — tests-declared-fallback is green, gate PASS." The reader
-   knows where they are before they read anything else.
-2. **DECISION** — the question the human must answer, presented as a **guided
-   decision**: lead with the one **recommended pick** marked `▶ … (recommended)`,
-   then its **1–3** described alternatives, every option carrying a one-line
-   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
-   *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`),
-   quote them verbatim and keep their document order — extraction ≠ judgment.
-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.
-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.
+1. **SUMMARY** — one line: intent + target + position.
+2. **DECISION** — as a **guided decision**: one `▶ … (recommended)` + 1–3 described alternatives. Exactly one per report, or "none — FYI". Ask after everything below (show-before-ask).
+3. **FLAGS** — lowest-confidence first, each with *why* and *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`), quote verbatim and keep document order.
+4. **DECIDED** — high-confidence autonomous calls, highest-confidence first, each with *why* it was safe. "none" when none. NEVER list a security / residue / lowered-autonomy call here.
+5. **EVIDENCE** — engine-sourced facts from `add.py` output, never re-typed.
+6. **NEXT** — ranked next actions, top one marked `▶` with what it unlocks. Mirror the rollup's `DECIDE NEXT` for the top action; overrule it only with a stated reason. **Informational, not a second gate**.
 
-### The DECISION block as a guided choice
+### Beyond the core blocks
 
-When the human must choose, render block 2 as a **guided decision** — never a bare next step:
+When a report needs more — a `RISK` ledger, a `DIFF`, a `SCOPE` map — add an extra block (SCREAMING-CASE label · one-line intent · engine-sourced where possible) AFTER EVIDENCE and BEFORE NEXT. Add only when it carries what the core blocks don't; never pad; never drop a core block.
+
+### The DECISION block as a guided choice
 
 ```
 DECISION  <the question>
@@ -112,59 +60,26 @@ DECISION  <the question>
       <one-line description — what it means · what it unlocks or costs>
     <alternative option>
       <one-line description>
-    <alternative option>
-      <one-line description>
 ```
 
-- **Recommended pick** — exactly one option carries the `▶ … (recommended)` marker; never zero,
-  never two. Your `confidence.md` self-score informs which to recommend; the human overrides freely
-  (a recommendation, not a default that auto-proceeds).
-- **1–3 described alternatives** — only real, takeable options (no strawmen). If there is genuinely
-  one path, show the single recommended step + its description — never invent filler to reach three.
-- **Every option is described** — the pick and each alternative carry a one-line description (what
-  it means + what it unlocks or costs); ≤1 line, no bare labels.
-- **Human gates only** — render the guided choice at `[human gate]` decision points; at a
-  `[you drive]` autonomous step there is no human to choose, so render none. Show-before-ask still
-  holds — the described choice is the ASK, rendered after EVIDENCE.
-
-**The ask itself** — when block 2's decision becomes a literal question component (an
-`AskUserQuestion` picker or a numbered menu), compose it as the guided choice above: the
-**recommended option goes first, with a `(Recommended)` suffix**, and each option's `description`
-carries its one-line description. On a tool without `AskUserQuestion`, render the same shape as a
-numbered/`▶` menu in chat — the convention is tool-agnostic. The question text stays a summary —
-intent + what "yes" means + the flag count — pointing at the report above.
+- **Exactly one** option carries `▶ … (recommended)`. `confidence.md` self-score informs which; the human overrides freely.
+- **1–3 real alternatives** only — no strawmen; if there is genuinely one path, show one — never invent filler to reach three.
+- **Every option is described** — pick and each alternative carry a one-line description.
+- **Human gates only** — render at `[human gate]` points; not at `[you drive]` steps.
+
+**The ask itself** — when block 2 becomes an `AskUserQuestion` picker: recommended option goes first with `(Recommended)` suffix. On tools without `AskUserQuestion`, render as a numbered/`▶` menu. The question is a summary, never the artifact — intent + what "yes" means + the flag count.
 
 ## Hard rules
 
 <constraints>
 - **Summary-first.** Never bury the decision under a task list or a diff.
-- **Show before ask.** Render the artifact (digest · diff · report) before any
-  approval question; the human decides on what they can see.
-- **Guided decision.** At a `[human gate]`, present block 2 as a guided choice — one highlighted
-  **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
-  `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
-  count disagrees with the engine is the un-transparent gate the ARC exists to close.
-- **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or
-  blank until the answer returns: show → ask → stamp → advance. An artifact
-  must never claim an approval that has not happened.
-- **One report per decision point.** After an approval, point at the frozen artifact —
-  do not re-render the whole bundle.
-- **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
-  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.
+- **Show before ask.** Render the artifact (digest · diff · report) before any approval question.
+- **Guided decision.** At a `[human gate]`, block 2 is a guided choice — one `▶ … (recommended)` + 1–3 described alternatives; never a bare next step.
+- **Reconcile the count.** FLAGS must reconcile with `add.py report --decide`'s open-item count before the ask. Engine wins if prose disagrees — fix the data, not the sentence.
+- **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or blank until the answer returns: show → ask → stamp → advance.
+- **One report per decision point.** After an approval, point at the frozen artifact — do not re-render the bundle.
+- **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.** A compact SUMMARY · DECISION · FLAGS block sits in chat immediately before the ask; the question text itself is two lines at most — intent + what "yes" means + flag count — pointing at the report above.
+- **NEXT is not a second gate.** The single decision stays in DECISION; NEXT is ranked recommendations only.
+- **DECIDED never holds a gate-class call.** Security / residue / lowered-autonomy calls escalate in DECISION.
 </constraints>