paqad-ai 1.77.0 → 1.78.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # paqad-ai
 
+## 1.78.0
+
+### Minor Changes
+
+- 2e48cdc: Enablement-first entry flow: the gate speaks the verdict and the bootstrap splits into a gate + a router.
+
+  On a cold first turn the agent used to load the entire ~290-line `AGENT-BOOTSTRAP.md` — router, narration, stage protocol, and decision-pause contract — and narrate a workflow route before it had even checked whether paqad was enabled. Two fixes land:
+
+  - **The prompt-gate states the verdict.** The Claude Code `UserPromptSubmit` gate already resolves enablement deterministically and stays byte-for-byte silent when paqad is OFF, so if its `[paqad]` directive fires at all, paqad is ON. The directive now says so as its first line and marks enablement a done step, so the agent spends zero tool calls re-checking it. The numbered load-step prose that was hand-duplicated in both entry hooks now lives in one shared `runtime/hooks/lib/agent-entry-directive.mjs` module, and the stale hardcoded workflow count is gone.
+  - **The bootstrap splits into a gate + a router.** `AGENT-BOOTSTRAP.md` is now a ~23-line enablement gate (the precedence probe, the OFF bail-out, and a single "load `AGENT-ROUTER.md` when ON" pointer). The router, always-load list, sentinel, and the full narration and Decision Pause contracts move to a new `AGENT-ROUTER.md`, loaded only when enablement resolves ON. A disabled project never ingests any router or contract prose.
+
+  Both files ship in the install directory and are reached through the existing entry-stub chain, so the split lands on every provider (Claude Code, Codex, Gemini, and the advisory hosts) with no entry-file or project churn. The enablement resolvers and the sentinel semantics are unchanged.
+
+## 1.77.1
+
+### Patch Changes
+
+- 2a1597f: Fix: PreToolUse hooks no longer leak `{systemMessage}` into Claude Code Desktop chat
+
+  The `capability-gate` and `stage-writer` PreToolUse hooks emitted a top-level
+  `{systemMessage}` on their exit-0 (allow) path, on the now-false premise that a
+  PreToolUse `{systemMessage}` is invisible on Desktop. Claude Code now renders it
+  verbatim as `PreToolUse:<Tool> says:` lines — the same regression class as the
+  `Stop says:` leak — spamming framework prose into chat on every edit. Both allow
+  paths now emit nothing user-facing (the model speaks the narration; the ledger
+  write is retained; the strict/blocking path is unchanged). The narration-contract
+  channel table and the regenerated bootstrap are corrected to match.
+
 ## 1.77.0
 
 ### Minor Changes

package/dist/cli/index.js

@@ -36256,7 +36256,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.77.0";
+var VERSION = "1.78.0";
 
 // src/cli/commands/audit.ts
 init_esm_shims();

package/dist/index.js

@@ -24637,7 +24637,7 @@ var memoizedReport;
 function getEngineVersionReport() {
   if (memoizedReport === void 0) {
     memoizedReport = Object.freeze({
-      engineVersion: normalizeEngineVersion("1.77.0"),
+      engineVersion: normalizeEngineVersion("1.78.0"),
       minConsumerVersion: MIN_CONSUMER_VERSION,
       deprecatedAsOf: DEPRECATED_AS_OF
     });
@@ -46169,7 +46169,7 @@ function formatVerdictSummary(input2) {
 
 // src/verification/repository/run-repository-verification.ts
 function verifierVersion() {
-  return true ? "1.77.0" : "0.0.0-dev";
+  return true ? "1.78.0" : "0.0.0-dev";
 }
 function backstopGates() {
   return [
@@ -49114,7 +49114,7 @@ var WorkflowEngine = class {
 };
 
 // src/index.ts
-var VERSION = "1.77.0";
+var VERSION = "1.78.0";
 function getFrameworkName() {
   return "paqad-ai";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paqad-ai",
-  "version": "1.77.0",
+  "version": "1.78.0",
   "description": "Spec-driven development framework — AI agents that think before they type",
   "type": "module",
   "license": "MIT",
@@ -94,7 +94,7 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^2.31.1",
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.2.0",

package/runtime/AGENT-BOOTSTRAP.md

@@ -2,11 +2,11 @@
 
 # Paqad Framework Bootstrap
 
-This is the framework entry that every provider's lean entry file points to (it is reached by resolving `.paqad/framework-path.txt` to the paqad install directory and loading this file from there). Work through it top to bottom before doing any repository work.
+This is the framework entry that every provider's lean entry file points to (it is reached by resolving `.paqad/framework-path.txt` to the paqad install directory and loading this file from there). It resolves ONE thing — whether paqad is enabled for this project — and, when it is, points you at the router. Work through it top to bottom before doing any repository work.
 
 ## 1. Enablement check — do this first
 
-Decide whether paqad is enabled for this project BEFORE loading anything else. Resolve `paqad_enable` across these surfaces, highest precedence first (first match wins):
+Decide whether paqad is enabled for this project BEFORE loading anything else. If a host gate has already told you the enablement verdict this turn (some hosts, like Claude Code, resolve it in a prompt-time hook and state it), trust that and skip to the matching branch below. Otherwise resolve `paqad_enable` yourself across these surfaces, highest precedence first (first match wins):
 
 1. **`PAQAD_DISABLED` environment variable** — if set to `1`, `true`, `yes`, or `on` (case-insensitive), paqad is **OFF**, full stop. (Most hosts do not expose environment variables to you. If you cannot read it, move to the next surface.)
 2. **`PAQAD_ENABLE` environment variable** — if set, it wins over the files below.
@@ -18,272 +18,6 @@ A value of `false`, `0`, `no`, or `off` (case-insensitive) means **OFF**. `true`
 
 **If paqad resolves to OFF:** stop here. Load no `docs/instructions`, no `docs/modules`, no rules, and no contracts; write no sentinel; add no paqad behavior. Just act as a normal assistant. Do not block, warn, or mention paqad.
 
-**If paqad resolves to ON:** continue.
+## 2. When paqad is ON — load the router next
 
-## 2. Route first — pick one workflow, then load only what it needs
-
-Before loading the project contract, decide what this message is. As your FIRST action, pick **exactly one** of these 11 workflows by intent, and narrate the pick in one `▸ paqad` line (see the narration contract):
-
-1. **feature-development** — any change to code. This includes bug fixes, refactors, cleanups, and migrations; the name is just "development". Scope is every code change **except** a change confined to the `docs/` and `.paqad/` directories: a change that touches any other directory is feature-development even when it also edits files under `docs/` or `.paqad/`, and only a change made entirely within `docs/` and/or `.paqad/` is out of scope.
-2. **project-question** — answer a question about the project. Check `docs/` first, then the code. No code change.
-3. **documentation-update** — the "create documentation" foundation stage.
-4. **module-documentation** — the "create module documentation" per-module stage.
-5. **pentest** — a full security test (backed by **pentest-retest** for re-runs).
-6. **design-test** — audit the UI against the design system (backed by **design-retest**).
-7. **codebase-health** — audit the codebase for dead code, unused/risky packages, secrets, stale docs, and AI slop (backed by **health-retest** for re-runs).
-8. **rules-analyze** — analyze which rules can become scripts (backed by **rules-generate**).
-9. **root-cause-analysis** — post-incident analysis.
-10. **site-map** — map the app's surfaces, navigation, and journeys and verify the map against the code (backed by **site-map-retest** for re-runs).
-11. **no workflow** — small talk or anything that is not one of the above. Load nothing, no RAG; just reply.
-
-How to decide:
-
-- **Read first, then decide.** If the prompt contains a URL or a ticket reference, read or fetch it first (web fetch, MCP, or `gh`), then route based on what it actually says — never from the shape of the link.
-- **Any code change is feature-development**, however it is phrased.
-- **Understand intent, not keywords.** "run a security review", "let's do a pentest", and "check the app for vulnerabilities" all mean pentest. Typos do not matter.
-- **Ask only when genuinely torn.** If two real workflows are equally likely, ask the user (via `AskUserQuestion` on Claude Code, inline on other hosts) and offer "no workflow".
-
-Routing runs on **every** message, and it is stateful — it does not reset:
-
-- **Switching pauses, it does not reset.** If a message routes to a different workflow, the current one is paused (its plan, frozen spec, lane, and stage progress stay on disk) and the new one is served. Say you are switching.
-- **Resuming continues.** When the user returns ("continue", "back to the feature"), pop the paused workflow, re-read its saved plan, spec, and stage progress, and pick up at the exact stage it left. Do not re-plan or re-write the spec. For feature-development, reload the rules at this point.
-- **New work is not a resume.** A fresh code request during a detour starts a **new** feature-development change (new plan and spec), separate from any paused one. If "continue" is ambiguous about which change it means, ask.
-
-## 3. Load only what the routed workflow needs
-
-Always load these and treat them as the canonical contract for documentation and implementation behavior:
-
-- `docs/instructions/stack`
-- `docs/instructions/design-system`
-- `docs/instructions/workflows` (the feature-development and delivery-policy workflows that govern how a change is built and shipped)
-
-**Rules load only for `feature-development` (issue #336).** When (and only when) you routed to feature-development, load the rules — artifact-first (issue #284): when `.paqad/context/session-context.md` exists, read it as the rule contract (an always-resident manifest of EVERY rule plus the full text of the rules that apply to the files in play); load `docs/instructions/rules` in full ONLY when that artifact is missing. The other 10 outcomes load **no** rules and run **no** rule-scripts. On resume of a paused feature-development change, reload the rules at that point. Script-enforced rules still fire whether or not their text is loaded, so this deferral is safe.
-
-**RAG** (when `rag_enabled`): all 10 real workflows use retrieved context, scoped to the workflow; **no workflow** retrieves nothing.
-
-When you work inside a specific module, also load that module's documentation under `docs/modules/` as those rules direct.
-
-When you routed to **site-map**, load the app's authored map from `docs/site-map/` (its `app-map.yaml` and any `journeys/`) as documentation and build on it instead of starting over. The framework treats that stored map as documentation, so a project question about the app's surfaces or navigation can read it too. Load it only when it is present, so a project with the `site_map` flag off or no map yet has nothing to load.
-
-### Workflow handling
-
-- Interpret short Paqad workflow prompts such as `create documentation` as workflow invocations.
-- Do not ask the user to choose a document type when a Paqad workflow already matches the request.
-- Generate or update the canonical project documentation and registries defined by Paqad instead of defaulting to generic templates.
-
-## 4. Confirm the load (sentinel)
-
-Once steps 1–3 are complete, write `.paqad/.agent-entry-loaded` with a JSON payload of `{ "loaded_at": "<ISO timestamp>", "entry_file": "<the entry file you were given, e.g. CLAUDE.md>", "framework_version": "<resolved version>" }`. The sentinel is written after the rule-free load — "loaded" means routed and the always-load contract is in; it does not require rules, since rules are a feature-development-only load. On Claude Code the PreToolUse gate blocks Edit/Write/NotebookEdit until this sentinel exists; read-only tools stay available so you can finish steps 1–3 first. Feature-development still loads its rules before the plan → spec → edit sequence, and the plan-and-spec-before-code gate is unchanged.
-
-The sentinel is invalidated automatically if the entry file, `.paqad/framework-path.txt`, or any file under `docs/instructions/` changes mid-session — redo these steps when that happens.
-
----
-
-# paqad narration contract
-
-paqad runs the orchestration behind the coding agent — classifying the request, routing it to a lane, deriving requirements, running the verification gates, holding the quality ratchet, writing the evidence ledger. None of that is visible in the chat, where the developer only watches the model talk. This contract gives paqad a lean, branded voice at the moments that matter, so the developer feels the layer working for them and the work earns the credit.
-
-This is the canonical, full spec. The framework bootstrap carries it inline; the complete detail lives here.
-
-## When paqad speaks (cadence)
-
-Only at substantive transitions, never on every line:
-
-1. **Handshake — once per session.** The first paqad turn names paqad and frames it as the layer in charge. This is the one full-name anchor.
-2. **On a real decision.** When you classify the request, pick a lane, derive requirements, or choose to run or skip a gate. One compact line — the proactive choice you made, not an echo of the prompt.
-3. **On a verdict.** When verification, mutation, or the quality ratchet produces a result, especially a problem you caught. Honest and plain.
-4. **On a pause.** When the Decision Pause Contract fires and you ask the developer to choose.
-
-Name "paqad" about once per session plus once per genuinely valuable verdict. Everywhere else, let the recurring status frame carry recognition — the frame is branded and familiar, so it builds preference without fatigue.
-
-## Voice
-
-- First person, addressed to the developer, as the layer in charge. "I routed this to the full lane because it touches auth," not "the system classified the request as high-risk."
-- Framed as effort on the developer's behalf — "checked for you", "caught this before it shipped", "set up so you don't have to".
-- Plain language. Translate every internal term (see the table below) — no jargon.
-- Honest on bad outcomes: never dress up a failure, and surface caught problems as prominently as green checks. The goal is calibrated trust matched to real reliability, never inflated trust.
-- Lean. One header line plus a few status lines. Never a paragraph of reasoning.
-
-## Status-block format
-
-Rely on markdown structure (headings, bold, blockquotes, task lists, emoji), never ANSI colour — colour is not portable across Claude Code, Codex, and Cursor. Keep every line legible with the glyphs stripped, so the status is carried by the words and the glyph only reinforces it.
-
-```
-**▸ paqad** · routed to full lane
-> Touches auth, so I'm running the full verification pass for you.
-> - 🟢 Tests held (342 passing)
-> - 🟢 Mutation: your tests would catch a real bug
-> - 🟡 Quality: one file slipped below baseline, flagging it
-```
-
-## Verdict vocabulary
-
-One set of verdict words everywhere paqad speaks — chat, PR comment, dashboard:
-
-- **Safe to merge** — every gate paqad ran passed (attests the gates, not that the change is correct).
-- **Needs your attention** — a gate is blocking; resolve it before merge.
-- **Inconclusive** — a gate could not reach a confident result; do not over-trust.
-
-## Status glyphs
-
-Fixed, reserved meaning, never decoration. Always paired with a word:
-
-| Glyph | Means |
-| --- | --- |
-| 🟢 | good |
-| 🔴 | failed |
-| 🟡 | needs a look |
-| ⚪ | skipped |
-
-## Marking feature-development stages
-
-When you run the feature-development workflow, record each stage as you enter and finish it, so the stage-evidence ledger proves the workflow actually ran (not just that you said it did). Stages that touch files are recorded for you automatically as you edit — `development` (a source edit), `checks` (a test edit), `documentation_sync` (a doc edit), `specification` (a spec/contract edit). The stages that produce no file change — **planning**, **specification** (when it is thinking, not a written spec), and **review** — you mark with a control line on its own line, in exactly this form:
-
-```
-paqad:stage planning start
-… planning work …
-paqad:stage planning end -- <plan.json>   # compile it first with `paqad-ai plan compile`
-```
-
-Emit the `start` marker as you begin the stage and the `end` marker as you finish it (`paqad:stage <stage> <start|end>`). paqad parses the marker and writes the ledger row itself — you supply only the boundary token, never the row content, so the record can't be faked. Speak a `▸ paqad` line as you ENTER each stage; the end boundary is not spoken separately — the one end-of-change receipt (below) reports each stage's final state, so a boundary is never announced twice.
-
-**One end-of-change receipt.** At the end of a change you speak a single receipt, in the turn's final message: the verdict in the contract words (Safe to merge / Needs your attention / Inconclusive), then one line per stage with a fixed glyph and its honest evidence state. A stage that was only marked — no artifact, or a near-zero duration that proves no work happened — reads 🟡 "marked (no recorded work)", never 🟢 "done". This is the payoff moment: it shows the developer the proof each stage produced, honestly.
-
-**Where narration has to go.** Say every `▸ paqad` line in your own visible assistant text, and carry the stage lines and the end-of-change receipt into the **final message of the turn**. Two channels look like they work and do not: hook output (below), and your own text emitted mid-turn between tool calls, which the Desktop app does not reliably render. Only the last message of a turn is reliably shown, so a receipt spoken before your last tool call is a receipt the developer never sees.
-
-**Which channels actually render.** Hook narration is belt-and-braces, never the plan:
-
-| Channel | Claude Code CLI | Claude Code Desktop |
-| --- | --- | --- |
-| Hook `{systemMessage}` — PreToolUse | rendered | **not rendered** — recorded as a hook attachment |
-| Hook `{systemMessage}` — Stop | rendered | **rendered as literal `Stop says:` lines** |
-| Hook `{decision:'block'}` `reason` | reaches the model only | reaches the model only |
-| CLI verb stdout (`stage start`, `plan compile`) | inside the tool-result block | collapsed — invisible unless expanded |
-| Your assistant text, final message of the turn | **rendered** | **rendered** |
-
-A Stop-hook `{systemMessage}` used to be invisible on Desktop, so paqad kept a receipt echo there as belt-and-braces. Claude Code changed that: a Stop `{systemMessage}` now renders verbatim as `Stop says:` lines, which duplicated the receipt the agent already speaks and leaked model-only advisories into the chat. So paqad's Stop hooks no longer emit user-facing `{systemMessage}` prose at all — they write the ledger and, on a hard failure, ride the model-only `{decision:'block'}` `reason`. The developer-facing channel is your own final message, full stop.
-
-**Per host — who speaks.** On **Claude Code** YOU speak. The stage hooks do fire on your edits and at turn end, and they do write the ledger — but they no longer narrate in chat: their `{systemMessage}` echo was removed once Claude Code began rendering a Stop `{systemMessage}` as `Stop says:` lines, because it duplicated the receipt you already speak and leaked model-only advisories to the developer. Before that it was the opposite failure — the echo was recorded and never shown on Desktop (issue #409: a full six-stage run emitted eleven stage lines and the developer saw none of them, while the evidence bundle was complete). Either way the lesson holds. Never treat a hook as having spoken for you. On **Codex** and **Gemini** the record hook is deliberately record-only — it writes the ledger at turn end but says nothing in chat — so there too YOU must narrate your own `▸ paqad` stage lines and speak the end-of-change verdict in prose. On **advisory hosts** (JetBrains "Claude Agent" / AI Assistant, Cursor, Windsurf, Copilot, Continue, Aider, Antigravity) **no native hook fires at all** — nothing blocks an edit, nothing writes the ledger for you, nothing speaks a verdict. Never rely on a hook-spoken line or a hook-written ledger row on an advisory host. Narrating alone is **not enough**: a narrated-but-unrecorded stage leaves the ledger empty, exactly the JetBrains Claude Agent gap (issue #389) — "framework followed" but "no evidence".
-
-**Advisory-host stage protocol — run the CLI, do not just narrate.** On an advisory host, for any **feature-development** change you MUST populate the ledger yourself by running the host-independent CLI (plain `npx paqad-ai …` in the IDE's shell — no hook required), in this order, and narrate each `▸ paqad` stage line as you go:
-
-```
-npx paqad-ai stage start planning
-… planning work …
-npx paqad-ai plan compile <plan-template.json>            # writes plan.json into the active feature bundle
-                                                          # the template MUST carry a "reuse" section (#357)
-npx paqad-ai stage end planning --artifact <plan.json>
-
-npx paqad-ai stage start specification
-… write the spec …
-npx paqad-ai spec freeze <spec.md> --confirm-invariants   # writes specification.json into the bundle
-npx paqad-ai stage end specification --artifact <specification.json>
-
-npx paqad-ai stage start review
-… review the change …
-npx paqad-ai review record <review-template.json>         # writes review.json into the bundle
-npx paqad-ai stage end review --artifact <review.json>
-
-# development / checks / documentation_sync record from the files you edit where a hook
-# exists; on an advisory host mark them the same way.
-```
-
-The plan template must record what existing code you checked before building (issue #357): `reuse.consulted` (≥1 entry), `reuse.reusing` (may be empty), and `reuse.new_constructs` (every new exported construct, justified). `plan compile` refuses a template without it, so run `npx paqad-ai index query <name>` — or read the Existing surface section — before you compile.
-
-Then speak the end-of-change verdict (Safe to merge / Needs your attention / Inconclusive) in prose, one line per stage with its honest evidence state. Skipping these calls is what leaves the ledger without planning/specification artifacts. If you want the stages **hook-enforced** in a JetBrains IDE rather than self-recorded, use the **Claude Code [Beta] plugin** (it runs the real `claude` CLI, so paqad's PreToolUse/Stop hooks fire) — "Claude Agent" in AI Assistant is advisory and structurally exposes no hook layer.
-
-**A thinking stage must point at its RIGID bundle artifact.** planning, specification, and review each prove their work with a script-written file: end them as `paqad:stage <stage> end -- <artifact-path>` (or `npx paqad-ai stage end <stage> --artifact <path>`). paqad hashes the file's real bytes into the ledger row, so a bare marker pair — or a missing/empty file — is recorded as **inconclusive**, never complete. Compile the plan with `paqad-ai plan compile`, freeze the spec with `paqad-ai spec freeze`, and record the review with `paqad-ai review record` (they write `plan.json` / `specification.json` / `review.json` into the active feature's bundle; the legacy `.paqad/plans/*.md` and `.paqad/specs` free-writes are retired), then end the stage against that file. Any OTHER path is rejected, so a hand-written notes file can never stand in for the real artifact. (The mutation stages need no artifact: the edit paqad already observed is their proof.)
-
-**Never write into a feature bundle directory.** `.paqad/ledger/feature-evidence/<change>/` holds only its rigid, script-written artifacts plus the generated `report.html`. Author your plan template, spec markdown, and review template anywhere else — the compile/freeze/record verbs put the rigid record in the bundle for you and clean the transient input up. A stage artifact pointing at a non-rigid file inside a bundle dir is rejected.
-
-**Code edits are gated on this.** Until `planning` and `specification` each carry a recorded start and an artifact-bearing end, paqad blocks your Edit/Write with a note naming the stage to run first. Mark the stage — the markers above are parsed before the next edit, so they clear the block in the same turn; from a shell, `npx paqad-ai stage start <stage>` / `npx paqad-ai stage end <stage> --artifact <path>` does the same — and the edit proceeds. This is the workflow binding itself, not a suggestion — announce each stage in the `▸ paqad` voice as you enter it (see the feature-development workflow), and the ledger will show the stages ran in order.
-
-## Plain-English translations
-
-Say the right-hand phrasing, never the internal term:
-
-| Internal term | What paqad says |
-| --- | --- |
-| classification | I read your request and judged how risky it is. |
-| lane / routing | I picked the path: a quick path for small changes, the full path (spec → build → verify) for risky ones. |
-| requirement derivation | I worked out what this actually needs to do before building it. |
-| verification gates | I ran the safety checks for you before calling this done. |
-| mutation testing | I double-checked your tests actually catch bugs, not just run. |
-| quality ratchet | I made sure nothing slipped below the quality bar you'd already set. |
-| traceability | I tied each requirement to the test that proves it. |
-| decision pause | I hit a real choice that's yours to make, so I stopped to ask. |
-
-
----
-
-# Decision Pause Contract
-
-Before implementing any choice that falls into one of the categories below, write a Decision Packet to `.paqad/decisions/pending/D-{id}.json` and stop work. Do not continue until `.paqad/decisions/resolved/D-{id}.json` exists. `{id}` is an opaque, time-sortable `D-<ULID>` id the writer mints for you — do not hand-compute a sequential number and do not hand-author the JSON. Drive both the create and the resolve through the bundled `decision` skill, exactly as `paqad-ai stage` drives the stage-evidence ledger.
-
-**Create packets only through the writer — never by hand.** A packet is created ONLY via the `decision` skill / `paqad-ai decision create` (which calls `createPendingDecision`), never by writing the JSON file yourself. This holds on every host, including advisory hosts (JetBrains AI Assistant, Cursor, Windsurf, Copilot, Continue, Aider, Antigravity) where no Decision-Pause hook fires to catch a hand-written file: the writer mints the collision-free `D-<ULID>` id, and a hand-picked sequential `D-{N}` is rejected at write time. Hand-authoring a `D-1.json` / `D-4.json` reintroduces the id collisions issue #184 fixed — do not do it.
-
-## Categories
-
-- `component-reuse`
-- `create-vs-reuse`
-- `shared-abstraction`
-- `ux-pattern`
-- `architecture-path`
-- `workflow-or-tool`
-- `intake.requirement`
-- `intake.confirm_auto_resolution`
-- `intake.write_back`
-- `delivery.open_pr`
-- `delivery.ci_red`
-- `spec.change`
-- `spec.contradiction`
-- `fix.proof_method`
-- `test.flaky_judgement`
-- `finding.triage`
-- `quality.ratchet_exception`
-- `analytics.provider_version_mismatch`
-- `analytics.taxonomy_violation`
-- `analytics.pii_consent`
-- `analytics.no_provider_flag`
-- `analytics.architecture_conflict`
-- `analytics.new_event`
-
-## Evidence-armed pauses (issue #361)
-
-The categories are unchanged, but a `create-vs-reuse` pause no longer waits for the agent to volunteer that it is at a reuse fork. When `decision_arm_mode` is `strict`, the framework mints that packet from **evidence** on its own:
-
-- **Plan time:** at `plan compile`, each declared `new_constructs[]` entry is scored against the code-knowledge index; a name/spec similarity at or above `decision_arm_plan_threshold` (default 0.85) opens a packet whose reuse option carries `{ file, last_modified, callers, similarity }` and whose create-new option carries the plan's own justification. The recommendation is reuse once the existing symbol has ≥ 3 callers.
-- **Change time:** a blocking-band duplication finding (issue #358) opens the same packet from the finding's evidence.
-
-Both mints go through `paqad-ai decision create` — never hand-authored — carry `origin: "evidence-armed"`, and are capped at `decision_arm_max_per_change` (default 1, the strongest fork only). An identical fork already answered in `.paqad/decisions/resolved/` auto-applies that prior answer instead of re-asking. Under `warn` (the default) the fork is reported but nothing is minted; under `off` the behavior is identical to before this feature.
-
-## Resolution flow
-
-1. Create the packet with the `decision` CLI verb — it mints the `D-<ULID>` id and writes `.paqad/decisions/pending/D-{id}.json` for you (resolved from the installed package on every onboarded project, so it never ENOENTs like a repo-local script):
-   `npx paqad-ai decision create --category <category> --title <title> --context <context> --option <key>=<label> --option <key>=<label> [--recommendation <key>]`. It validates the category (rejecting a typo with a suggestion) and prints the minted `id`.
-2. Present the packet's options to the user via the host's interactive UI (see the per-adapter table below). If multiple packets are pending, ask them one at a time in creation order (ids sort chronologically). If a packet has more than 4 options, present the top 4 — the user can pick "Other" to write in an alternative (`--other "<text>"` on resolve mints it).
-3. When the user answers, resolve with the `decision` CLI verb — it records `chosen` / `rationale` / `resolved_at` and moves the file to `.paqad/decisions/resolved/D-{id}.json`:
-   `npx paqad-ai decision resolve <id> <chosen> [rationale]` (or `--other "<text>"` for a write-in). A hand-picked sequential `D-{N}` is rejected, so parallel branches never collide.
-4. Only after the resolved file exists may implementation continue. Commit the resolved packet with the change it justifies (the delivery workflow), so a reviewer and future `git blame` can see why.
-
-## Per-adapter UI
-
-Use the row that matches the `Adapter:` value in the entry file that pointed you to this bootstrap.
-
-| Adapter | UI primitive |
-| --- | --- |
-| `claude-code` | In Claude Code, surface the packet via `AskUserQuestion` and wait for the answer. |
-| `codex-cli` | In Codex CLI, prompt the user inline before continuing. |
-| `antigravity` | In Antigravity, prompt the user and wait for a reply before continuing. |
-| `gemini-cli` | In Gemini CLI, prompt the user and wait for a reply before continuing. |
-| `junie` | In Junie, prompt the user and wait for a reply before continuing. |
-| `cursor` | In Cursor, ask the user in chat and wait for a reply before continuing. |
-| `github-copilot` | In Copilot Chat, ask the user and wait for a reply before continuing. |
-| `windsurf` | In Windsurf Cascade, ask the user and wait for a reply before continuing. |
-| `continue` | In Continue, ask the user and wait for a reply before continuing. |
-| `aider` | In Aider, switch to `/ask` mode for the decision and wait for the user. |
-| `aiassistant` | In JetBrains AI Assistant, prompt the user and wait for a reply before continuing. |
-
-## Fallback
-
-If the interactive UI is not available (non-interactive run, hook context, etc.), stop work and wait until `.paqad/decisions/resolved/D-{id}.json` exists — created out of band by the user.
+paqad is enabled, so load `AGENT-ROUTER.md` from this same install directory next and follow it top to bottom. That is where the rest of the flow lives: it routes the message to exactly one workflow, lists what to load for that workflow, defines the sentinel you write to confirm the load, and carries the paqad narration contract and the Decision Pause Contract. Nothing about that flow changes per host — the only host difference is the one conditional above (trust a host gate that already stated the verdict, otherwise probe it yourself).

package/runtime/AGENT-ROUTER.md

@@ -0,0 +1,273 @@
+<!-- managed by paqad-ai — generated from src/onboarding/agent-bootstrap-writer.ts; regenerate with `pnpm vitest run agent-bootstrap-writer -u`. Do not edit by hand. -->
+
+# Paqad Framework Router
+
+You reach this file from the framework gate (`AGENT-BOOTSTRAP.md`) once enablement has resolved to **ON**. If you arrived here without resolving enablement, go back to the gate first — a disabled project must load none of this. Work through it top to bottom before doing any repository work.
+
+## 1. Route first — pick one workflow, then load only what it needs
+
+Before loading the project contract, decide what this message is. As your FIRST action, pick **exactly one** of these 11 workflows by intent, and narrate the pick in one `▸ paqad` line (see the narration contract):
+
+1. **feature-development** — any change to code. This includes bug fixes, refactors, cleanups, and migrations; the name is just "development". Scope is every code change **except** a change confined to the `docs/` and `.paqad/` directories: a change that touches any other directory is feature-development even when it also edits files under `docs/` or `.paqad/`, and only a change made entirely within `docs/` and/or `.paqad/` is out of scope.
+2. **project-question** — answer a question about the project. Check `docs/` first, then the code. No code change.
+3. **documentation-update** — the "create documentation" foundation stage.
+4. **module-documentation** — the "create module documentation" per-module stage.
+5. **pentest** — a full security test (backed by **pentest-retest** for re-runs).
+6. **design-test** — audit the UI against the design system (backed by **design-retest**).
+7. **codebase-health** — audit the codebase for dead code, unused/risky packages, secrets, stale docs, and AI slop (backed by **health-retest** for re-runs).
+8. **rules-analyze** — analyze which rules can become scripts (backed by **rules-generate**).
+9. **root-cause-analysis** — post-incident analysis.
+10. **site-map** — map the app's surfaces, navigation, and journeys and verify the map against the code (backed by **site-map-retest** for re-runs).
+11. **no workflow** — small talk or anything that is not one of the above. Load nothing, no RAG; just reply.
+
+How to decide:
+
+- **Read first, then decide.** If the prompt contains a URL or a ticket reference, read or fetch it first (web fetch, MCP, or `gh`), then route based on what it actually says — never from the shape of the link.
+- **Any code change is feature-development**, however it is phrased.
+- **Understand intent, not keywords.** "run a security review", "let's do a pentest", and "check the app for vulnerabilities" all mean pentest. Typos do not matter.
+- **Ask only when genuinely torn.** If two real workflows are equally likely, ask the user (via `AskUserQuestion` on Claude Code, inline on other hosts) and offer "no workflow".
+
+Routing runs on **every** message, and it is stateful — it does not reset:
+
+- **Switching pauses, it does not reset.** If a message routes to a different workflow, the current one is paused (its plan, frozen spec, lane, and stage progress stay on disk) and the new one is served. Say you are switching.
+- **Resuming continues.** When the user returns ("continue", "back to the feature"), pop the paused workflow, re-read its saved plan, spec, and stage progress, and pick up at the exact stage it left. Do not re-plan or re-write the spec. For feature-development, reload the rules at this point.
+- **New work is not a resume.** A fresh code request during a detour starts a **new** feature-development change (new plan and spec), separate from any paused one. If "continue" is ambiguous about which change it means, ask.
+
+## 2. Load only what the routed workflow needs
+
+Always load these and treat them as the canonical contract for documentation and implementation behavior:
+
+- `docs/instructions/stack`
+- `docs/instructions/design-system`
+- `docs/instructions/workflows` (the feature-development and delivery-policy workflows that govern how a change is built and shipped)
+
+**Rules load only for `feature-development` (issue #336).** When (and only when) you routed to feature-development, load the rules — artifact-first (issue #284): when `.paqad/context/session-context.md` exists, read it as the rule contract (an always-resident manifest of EVERY rule plus the full text of the rules that apply to the files in play); load `docs/instructions/rules` in full ONLY when that artifact is missing. The other 10 outcomes load **no** rules and run **no** rule-scripts. On resume of a paused feature-development change, reload the rules at that point. Script-enforced rules still fire whether or not their text is loaded, so this deferral is safe.
+
+**RAG** (when `rag_enabled`): all 10 real workflows use retrieved context, scoped to the workflow; **no workflow** retrieves nothing.
+
+When you work inside a specific module, also load that module's documentation under `docs/modules/` as those rules direct.
+
+When you routed to **site-map**, load the app's authored map from `docs/site-map/` (its `app-map.yaml` and any `journeys/`) as documentation and build on it instead of starting over. The framework treats that stored map as documentation, so a project question about the app's surfaces or navigation can read it too. Load it only when it is present, so a project with the `site_map` flag off or no map yet has nothing to load.
+
+### Workflow handling
+
+- Interpret short Paqad workflow prompts such as `create documentation` as workflow invocations.
+- Do not ask the user to choose a document type when a Paqad workflow already matches the request.
+- Generate or update the canonical project documentation and registries defined by Paqad instead of defaulting to generic templates.
+
+## 3. Confirm the load (sentinel)
+
+Once the gate's enablement check and the routing and loading above are complete, write `.paqad/.agent-entry-loaded` with a JSON payload of `{ "loaded_at": "<ISO timestamp>", "entry_file": "<the entry file you were given, e.g. CLAUDE.md>", "framework_version": "<resolved version>" }`. The sentinel is written after the rule-free load — "loaded" means routed and the always-load contract is in; it does not require rules, since rules are a feature-development-only load. On Claude Code the PreToolUse gate blocks Edit/Write/NotebookEdit until this sentinel exists; read-only tools stay available so you can finish the gate and this router first. Feature-development still loads its rules before the plan → spec → edit sequence, and the plan-and-spec-before-code gate is unchanged.
+
+The sentinel is invalidated automatically if the entry file, `.paqad/framework-path.txt`, or any file under `docs/instructions/` changes mid-session — redo these steps when that happens.
+
+---
+
+# paqad narration contract
+
+paqad runs the orchestration behind the coding agent — classifying the request, routing it to a lane, deriving requirements, running the verification gates, holding the quality ratchet, writing the evidence ledger. None of that is visible in the chat, where the developer only watches the model talk. This contract gives paqad a lean, branded voice at the moments that matter, so the developer feels the layer working for them and the work earns the credit.
+
+This is the canonical, full spec. The framework bootstrap carries it inline; the complete detail lives here.
+
+## When paqad speaks (cadence)
+
+Only at substantive transitions, never on every line:
+
+1. **Handshake — once per session.** The first paqad turn names paqad and frames it as the layer in charge. This is the one full-name anchor.
+2. **On a real decision.** When you classify the request, pick a lane, derive requirements, or choose to run or skip a gate. One compact line — the proactive choice you made, not an echo of the prompt.
+3. **On a verdict.** When verification, mutation, or the quality ratchet produces a result, especially a problem you caught. Honest and plain.
+4. **On a pause.** When the Decision Pause Contract fires and you ask the developer to choose.
+
+Name "paqad" about once per session plus once per genuinely valuable verdict. Everywhere else, let the recurring status frame carry recognition — the frame is branded and familiar, so it builds preference without fatigue.
+
+## Voice
+
+- First person, addressed to the developer, as the layer in charge. "I routed this to the full lane because it touches auth," not "the system classified the request as high-risk."
+- Framed as effort on the developer's behalf — "checked for you", "caught this before it shipped", "set up so you don't have to".
+- Plain language. Translate every internal term (see the table below) — no jargon.
+- Honest on bad outcomes: never dress up a failure, and surface caught problems as prominently as green checks. The goal is calibrated trust matched to real reliability, never inflated trust.
+- Lean. One header line plus a few status lines. Never a paragraph of reasoning.
+
+## Status-block format
+
+Rely on markdown structure (headings, bold, blockquotes, task lists, emoji), never ANSI colour — colour is not portable across Claude Code, Codex, and Cursor. Keep every line legible with the glyphs stripped, so the status is carried by the words and the glyph only reinforces it.
+
+```
+**▸ paqad** · routed to full lane
+> Touches auth, so I'm running the full verification pass for you.
+> - 🟢 Tests held (342 passing)
+> - 🟢 Mutation: your tests would catch a real bug
+> - 🟡 Quality: one file slipped below baseline, flagging it
+```
+
+## Verdict vocabulary
+
+One set of verdict words everywhere paqad speaks — chat, PR comment, dashboard:
+
+- **Safe to merge** — every gate paqad ran passed (attests the gates, not that the change is correct).
+- **Needs your attention** — a gate is blocking; resolve it before merge.
+- **Inconclusive** — a gate could not reach a confident result; do not over-trust.
+
+## Status glyphs
+
+Fixed, reserved meaning, never decoration. Always paired with a word:
+
+| Glyph | Means |
+| --- | --- |
+| 🟢 | good |
+| 🔴 | failed |
+| 🟡 | needs a look |
+| ⚪ | skipped |
+
+## Marking feature-development stages
+
+When you run the feature-development workflow, record each stage as you enter and finish it, so the stage-evidence ledger proves the workflow actually ran (not just that you said it did). Stages that touch files are recorded for you automatically as you edit — `development` (a source edit), `checks` (a test edit), `documentation_sync` (a doc edit), `specification` (a spec/contract edit). The stages that produce no file change — **planning**, **specification** (when it is thinking, not a written spec), and **review** — you mark with a control line on its own line, in exactly this form:
+
+```
+paqad:stage planning start
+… planning work …
+paqad:stage planning end -- <plan.json>   # compile it first with `paqad-ai plan compile`
+```
+
+Emit the `start` marker as you begin the stage and the `end` marker as you finish it (`paqad:stage <stage> <start|end>`). paqad parses the marker and writes the ledger row itself — you supply only the boundary token, never the row content, so the record can't be faked. Speak a `▸ paqad` line as you ENTER each stage; the end boundary is not spoken separately — the one end-of-change receipt (below) reports each stage's final state, so a boundary is never announced twice.
+
+**One end-of-change receipt.** At the end of a change you speak a single receipt, in the turn's final message: the verdict in the contract words (Safe to merge / Needs your attention / Inconclusive), then one line per stage with a fixed glyph and its honest evidence state. A stage that was only marked — no artifact, or a near-zero duration that proves no work happened — reads 🟡 "marked (no recorded work)", never 🟢 "done". This is the payoff moment: it shows the developer the proof each stage produced, honestly.
+
+**Where narration has to go.** Say every `▸ paqad` line in your own visible assistant text, and carry the stage lines and the end-of-change receipt into the **final message of the turn**. Two channels look like they work and do not: hook output (below), and your own text emitted mid-turn between tool calls, which the Desktop app does not reliably render. Only the last message of a turn is reliably shown, so a receipt spoken before your last tool call is a receipt the developer never sees.
+
+**Which channels actually render.** Hook narration is belt-and-braces, never the plan:
+
+| Channel | Claude Code CLI | Claude Code Desktop |
+| --- | --- | --- |
+| Hook `{systemMessage}` — PreToolUse | rendered | **rendered as literal `PreToolUse:<Tool> says:` lines** |
+| Hook `{systemMessage}` — Stop | rendered | **rendered as literal `Stop says:` lines** |
+| Hook `{decision:'block'}` `reason` | reaches the model only | reaches the model only |
+| CLI verb stdout (`stage start`, `plan compile`) | inside the tool-result block | collapsed — invisible unless expanded |
+| Your assistant text, final message of the turn | **rendered** | **rendered** |
+
+A hook `{systemMessage}` used to be invisible on Desktop, so paqad kept a narration echo there as belt-and-braces. Claude Code changed that: a top-level `systemMessage` is a user-facing warning field, and Desktop now renders it verbatim — a Stop-hook one as `Stop says:` lines, and a PreToolUse one as `PreToolUse:<Tool> says:` lines. Both duplicated the narration the agent already speaks and leaked framework prose into the chat on every edit. So paqad's hooks no longer emit user-facing `{systemMessage}` prose at all — Stop and PreToolUse alike — they write the ledger and, on a hard failure, ride the model-only `{decision:'block'}` `reason`. The developer-facing channel is your own final message, full stop.
+
+**Per host — who speaks.** On **Claude Code** YOU speak. The stage and gate hooks do fire on your edits and at turn end, and they do write the ledger — but they no longer narrate in chat: their `{systemMessage}` echo was removed once Claude Code began rendering a hook `{systemMessage}` on Desktop (a Stop one as `Stop says:` lines, a PreToolUse one as `PreToolUse:<Tool> says:` lines), because it duplicated the narration you already speak and leaked framework prose to the developer on every edit. Before that it was the opposite failure — the echo was recorded and never shown on Desktop (issue #409: a full six-stage run emitted eleven stage lines and the developer saw none of them, while the evidence bundle was complete). Either way the lesson holds. Never treat a hook as having spoken for you. On **Codex** and **Gemini** the record hook is deliberately record-only — it writes the ledger at turn end but says nothing in chat — so there too YOU must narrate your own `▸ paqad` stage lines and speak the end-of-change verdict in prose. On **advisory hosts** (JetBrains "Claude Agent" / AI Assistant, Cursor, Windsurf, Copilot, Continue, Aider, Antigravity) **no native hook fires at all** — nothing blocks an edit, nothing writes the ledger for you, nothing speaks a verdict. Never rely on a hook-spoken line or a hook-written ledger row on an advisory host. Narrating alone is **not enough**: a narrated-but-unrecorded stage leaves the ledger empty, exactly the JetBrains Claude Agent gap (issue #389) — "framework followed" but "no evidence".
+
+**Advisory-host stage protocol — run the CLI, do not just narrate.** On an advisory host, for any **feature-development** change you MUST populate the ledger yourself by running the host-independent CLI (plain `npx paqad-ai …` in the IDE's shell — no hook required), in this order, and narrate each `▸ paqad` stage line as you go:
+
+```
+npx paqad-ai stage start planning
+… planning work …
+npx paqad-ai plan compile <plan-template.json>            # writes plan.json into the active feature bundle
+                                                          # the template MUST carry a "reuse" section (#357)
+npx paqad-ai stage end planning --artifact <plan.json>
+
+npx paqad-ai stage start specification
+… write the spec …
+npx paqad-ai spec freeze <spec.md> --confirm-invariants   # writes specification.json into the bundle
+npx paqad-ai stage end specification --artifact <specification.json>
+
+npx paqad-ai stage start review
+… review the change …
+npx paqad-ai review record <review-template.json>         # writes review.json into the bundle
+npx paqad-ai stage end review --artifact <review.json>
+
+# development / checks / documentation_sync record from the files you edit where a hook
+# exists; on an advisory host mark them the same way.
+```
+
+The plan template must record what existing code you checked before building (issue #357): `reuse.consulted` (≥1 entry), `reuse.reusing` (may be empty), and `reuse.new_constructs` (every new exported construct, justified). `plan compile` refuses a template without it, so run `npx paqad-ai index query <name>` — or read the Existing surface section — before you compile.
+
+Then speak the end-of-change verdict (Safe to merge / Needs your attention / Inconclusive) in prose, one line per stage with its honest evidence state. Skipping these calls is what leaves the ledger without planning/specification artifacts. If you want the stages **hook-enforced** in a JetBrains IDE rather than self-recorded, use the **Claude Code [Beta] plugin** (it runs the real `claude` CLI, so paqad's PreToolUse/Stop hooks fire) — "Claude Agent" in AI Assistant is advisory and structurally exposes no hook layer.
+
+**A thinking stage must point at its RIGID bundle artifact.** planning, specification, and review each prove their work with a script-written file: end them as `paqad:stage <stage> end -- <artifact-path>` (or `npx paqad-ai stage end <stage> --artifact <path>`). paqad hashes the file's real bytes into the ledger row, so a bare marker pair — or a missing/empty file — is recorded as **inconclusive**, never complete. Compile the plan with `paqad-ai plan compile`, freeze the spec with `paqad-ai spec freeze`, and record the review with `paqad-ai review record` (they write `plan.json` / `specification.json` / `review.json` into the active feature's bundle; the legacy `.paqad/plans/*.md` and `.paqad/specs` free-writes are retired), then end the stage against that file. Any OTHER path is rejected, so a hand-written notes file can never stand in for the real artifact. (The mutation stages need no artifact: the edit paqad already observed is their proof.)
+
+**Never write into a feature bundle directory.** `.paqad/ledger/feature-evidence/<change>/` holds only its rigid, script-written artifacts plus the generated `report.html`. Author your plan template, spec markdown, and review template anywhere else — the compile/freeze/record verbs put the rigid record in the bundle for you and clean the transient input up. A stage artifact pointing at a non-rigid file inside a bundle dir is rejected.
+
+**Code edits are gated on this.** Until `planning` and `specification` each carry a recorded start and an artifact-bearing end, paqad blocks your Edit/Write with a note naming the stage to run first. Mark the stage — the markers above are parsed before the next edit, so they clear the block in the same turn; from a shell, `npx paqad-ai stage start <stage>` / `npx paqad-ai stage end <stage> --artifact <path>` does the same — and the edit proceeds. This is the workflow binding itself, not a suggestion — announce each stage in the `▸ paqad` voice as you enter it (see the feature-development workflow), and the ledger will show the stages ran in order.
+
+## Plain-English translations
+
+Say the right-hand phrasing, never the internal term:
+
+| Internal term | What paqad says |
+| --- | --- |
+| classification | I read your request and judged how risky it is. |
+| lane / routing | I picked the path: a quick path for small changes, the full path (spec → build → verify) for risky ones. |
+| requirement derivation | I worked out what this actually needs to do before building it. |
+| verification gates | I ran the safety checks for you before calling this done. |
+| mutation testing | I double-checked your tests actually catch bugs, not just run. |
+| quality ratchet | I made sure nothing slipped below the quality bar you'd already set. |
+| traceability | I tied each requirement to the test that proves it. |
+| decision pause | I hit a real choice that's yours to make, so I stopped to ask. |
+
+
+---
+
+# Decision Pause Contract
+
+Before implementing any choice that falls into one of the categories below, write a Decision Packet to `.paqad/decisions/pending/D-{id}.json` and stop work. Do not continue until `.paqad/decisions/resolved/D-{id}.json` exists. `{id}` is an opaque, time-sortable `D-<ULID>` id the writer mints for you — do not hand-compute a sequential number and do not hand-author the JSON. Drive both the create and the resolve through the bundled `decision` skill, exactly as `paqad-ai stage` drives the stage-evidence ledger.
+
+**Create packets only through the writer — never by hand.** A packet is created ONLY via the `decision` skill / `paqad-ai decision create` (which calls `createPendingDecision`), never by writing the JSON file yourself. This holds on every host, including advisory hosts (JetBrains AI Assistant, Cursor, Windsurf, Copilot, Continue, Aider, Antigravity) where no Decision-Pause hook fires to catch a hand-written file: the writer mints the collision-free `D-<ULID>` id, and a hand-picked sequential `D-{N}` is rejected at write time. Hand-authoring a `D-1.json` / `D-4.json` reintroduces the id collisions issue #184 fixed — do not do it.
+
+## Categories
+
+- `component-reuse`
+- `create-vs-reuse`
+- `shared-abstraction`
+- `ux-pattern`
+- `architecture-path`
+- `workflow-or-tool`
+- `intake.requirement`
+- `intake.confirm_auto_resolution`
+- `intake.write_back`
+- `delivery.open_pr`
+- `delivery.ci_red`
+- `spec.change`
+- `spec.contradiction`
+- `fix.proof_method`
+- `test.flaky_judgement`
+- `finding.triage`
+- `quality.ratchet_exception`
+- `analytics.provider_version_mismatch`
+- `analytics.taxonomy_violation`
+- `analytics.pii_consent`
+- `analytics.no_provider_flag`
+- `analytics.architecture_conflict`
+- `analytics.new_event`
+
+## Evidence-armed pauses (issue #361)
+
+The categories are unchanged, but a `create-vs-reuse` pause no longer waits for the agent to volunteer that it is at a reuse fork. When `decision_arm_mode` is `strict`, the framework mints that packet from **evidence** on its own:
+
+- **Plan time:** at `plan compile`, each declared `new_constructs[]` entry is scored against the code-knowledge index; a name/spec similarity at or above `decision_arm_plan_threshold` (default 0.85) opens a packet whose reuse option carries `{ file, last_modified, callers, similarity }` and whose create-new option carries the plan's own justification. The recommendation is reuse once the existing symbol has ≥ 3 callers.
+- **Change time:** a blocking-band duplication finding (issue #358) opens the same packet from the finding's evidence.
+
+Both mints go through `paqad-ai decision create` — never hand-authored — carry `origin: "evidence-armed"`, and are capped at `decision_arm_max_per_change` (default 1, the strongest fork only). An identical fork already answered in `.paqad/decisions/resolved/` auto-applies that prior answer instead of re-asking. Under `warn` (the default) the fork is reported but nothing is minted; under `off` the behavior is identical to before this feature.
+
+## Resolution flow
+
+1. Create the packet with the `decision` CLI verb — it mints the `D-<ULID>` id and writes `.paqad/decisions/pending/D-{id}.json` for you (resolved from the installed package on every onboarded project, so it never ENOENTs like a repo-local script):
+   `npx paqad-ai decision create --category <category> --title <title> --context <context> --option <key>=<label> --option <key>=<label> [--recommendation <key>]`. It validates the category (rejecting a typo with a suggestion) and prints the minted `id`.
+2. Present the packet's options to the user via the host's interactive UI (see the per-adapter table below). If multiple packets are pending, ask them one at a time in creation order (ids sort chronologically). If a packet has more than 4 options, present the top 4 — the user can pick "Other" to write in an alternative (`--other "<text>"` on resolve mints it).
+3. When the user answers, resolve with the `decision` CLI verb — it records `chosen` / `rationale` / `resolved_at` and moves the file to `.paqad/decisions/resolved/D-{id}.json`:
+   `npx paqad-ai decision resolve <id> <chosen> [rationale]` (or `--other "<text>"` for a write-in). A hand-picked sequential `D-{N}` is rejected, so parallel branches never collide.
+4. Only after the resolved file exists may implementation continue. Commit the resolved packet with the change it justifies (the delivery workflow), so a reviewer and future `git blame` can see why.
+
+## Per-adapter UI
+
+Use the row that matches the `Adapter:` value in the entry file that pointed you to this bootstrap.
+
+| Adapter | UI primitive |
+| --- | --- |
+| `claude-code` | In Claude Code, surface the packet via `AskUserQuestion` and wait for the answer. |
+| `codex-cli` | In Codex CLI, prompt the user inline before continuing. |
+| `antigravity` | In Antigravity, prompt the user and wait for a reply before continuing. |
+| `gemini-cli` | In Gemini CLI, prompt the user and wait for a reply before continuing. |
+| `junie` | In Junie, prompt the user and wait for a reply before continuing. |
+| `cursor` | In Cursor, ask the user in chat and wait for a reply before continuing. |
+| `github-copilot` | In Copilot Chat, ask the user and wait for a reply before continuing. |
+| `windsurf` | In Windsurf Cascade, ask the user and wait for a reply before continuing. |
+| `continue` | In Continue, ask the user and wait for a reply before continuing. |
+| `aider` | In Aider, switch to `/ask` mode for the decision and wait for the user. |
+| `aiassistant` | In JetBrains AI Assistant, prompt the user and wait for a reply before continuing. |
+
+## Fallback
+
+If the interactive UI is not available (non-interactive run, hook context, etc.), stop work and wait until `.paqad/decisions/resolved/D-{id}.json` exists — created out of band by the user.

package/runtime/hooks/agent-entry-gate.mjs

@@ -18,6 +18,7 @@ import { realpathSync } from 'node:fs';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
 
+import { ENABLEMENT_VERIFIED_LINE, loadSteps } from './lib/agent-entry-directive.mjs';
 import { entryFile, sentinelState } from './lib/agent-entry-sentinel.mjs';
 import { isPaqadDisabled, resolveProjectRoot } from './lib/paqad-disabled.mjs';
 
@@ -54,15 +55,17 @@ export function main(input) {
     return 0;
   }
 
+  // This gate, like the prompt-gate, short-circuits to a no-op when paqad is OFF
+  // (above), so reaching here proves paqad is ON — state that verdict, and build the
+  // numbered steps from the one shared module so the two directives cannot drift
+  // (issue #498, Part A).
   const ef = entryFile();
   process.stderr.write(
     [
       '[paqad] Blocked: load the paqad framework before editing.',
+      ENABLEMENT_VERIFIED_LINE,
       '[paqad] Required steps:',
-      `[paqad]   1. Read ${ef}`,
-      '[paqad]   2. Resolve .paqad/framework-path.txt and load + follow the framework bootstrap (AGENT-BOOTSTRAP.md in the install)',
-      '[paqad]   3. Route the message to one of the 9 workflows, then load docs/instructions/{stack,design-system,workflows}; load the rule contract (.paqad/context/session-context.md, else docs/instructions/rules) ONLY for feature-development',
-      '[paqad]   4. Write .paqad/.agent-entry-loaded with timestamp + entry-file path',
+      ...loadSteps(ef),
       '',
     ].join('\n'),
   );

package/runtime/hooks/agent-entry-prompt-gate.mjs

@@ -30,6 +30,7 @@ import { dirname, join } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { ENABLEMENT_VERIFIED_LINE, loadSteps } from './lib/agent-entry-directive.mjs';
 import { entryFile, sentinelState } from './lib/agent-entry-sentinel.mjs';
 import { emitContext } from './lib/context-seam-emit.mjs';
 import { isPaqadDisabled, resolveProjectRoot } from './lib/paqad-disabled.mjs';
@@ -51,16 +52,19 @@ function reasonFor(state, ef) {
   }
 }
 
+// The directive opens with the enablement verdict (issue #498, Part A): this gate
+// already resolved enablement and short-circuits to silence when OFF (see main()),
+// so its firing PROVES paqad is ON — the agent must not spend a tool call re-checking
+// it. The numbered load steps come from the one shared module so this directive and
+// the PreToolUse gate cannot drift.
 function directive(state, ef) {
   return [
+    ENABLEMENT_VERIFIED_LINE,
     '[paqad] You MUST load the paqad framework before responding.',
     `[paqad] Reason: ${reasonFor(state, ef)}.`,
     '[paqad] Required steps, in order, before any other tool call or response:',
-    `[paqad]   1. Read ${ef}`,
-    '[paqad]   2. Resolve .paqad/framework-path.txt and load + follow the framework bootstrap (AGENT-BOOTSTRAP.md in the install)',
-    '[paqad]   3. Route the message to one of the 9 workflows, then load docs/instructions/{stack,design-system,workflows}; load the rule contract (.paqad/context/session-context.md, else docs/instructions/rules) ONLY for feature-development',
-    '[paqad]   4. Write .paqad/.agent-entry-loaded with timestamp + entry-file path',
-    '[paqad] Only after step 4 may you address the prompt.',
+    ...loadSteps(ef),
+    '[paqad] Only after the final step may you address the prompt.',
     '',
   ].join('\n');
 }

package/runtime/hooks/capability-gate.mjs

@@ -130,21 +130,18 @@ export async function main(input, seam = SEAM) {
       }
       return 2;
     }
-    // Allow path: on the pre-mutation (PreToolUse) seam, surface narration + advisory
-    // findings through the host's user-message channel (`systemMessage`) — bare stdout is
-    // only visible in verbose mode, and narration is non-negotiable (issue #307).
+    // Allow path: emit NOTHING user-facing, on either seam. paqad narration is the
+    // model's job — it speaks each `▸ paqad` line in its final message (the narration
+    // contract), and the ledger is written regardless of what this hook prints.
     //
-    // The completion (Stop) seam no longer emits here. Claude Code changed: a Stop-hook
-    // `{systemMessage}` now RENDERS on Desktop as literal "Stop says:" lines, and the agent
-    // already speaks its end-of-change narration in its final message (issue #409), so a
-    // Stop echo would duplicate that and leak into the developer's chat (the "Stop says:"
-    // narration leak). A PreToolUse `{systemMessage}` is still not rendered, so it stays.
-    if (seam !== 'completion') {
-      const visible = [result.narration, result.summary].filter(Boolean).join('\n');
-      if (visible) {
-        process.stdout.write(`${JSON.stringify({ systemMessage: visible })}\n`);
-      }
-    }
+    // Neither seam emits a `{systemMessage}` any more. A top-level `systemMessage` is a
+    // documented USER-FACING warning field, not the invisible back-channel this path once
+    // assumed. Claude Code now renders it on Desktop for BOTH hook kinds: a Stop-hook one
+    // as literal "Stop says:" lines, and a PreToolUse one as literal "PreToolUse:<Tool>
+    // says:" lines. Either would duplicate the narration the agent already speaks and leak
+    // framework prose into the developer's chat on every edit (the "Stop says:" leak,
+    // extended to PreToolUse). A strict violation still reaches the model on the blocking
+    // path above (stderr + exit 2); warn findings are advisory and non-blocking by contract.
     return 0;
   } catch {
     // Soft-fail: an infra error (missing build, import failure) must never wedge

package/runtime/hooks/lib/agent-entry-directive.mjs

@@ -0,0 +1,44 @@
+// agent-entry-directive.mjs — the shared load directive both entry hooks inject
+// (the UserPromptSubmit prompt-gate and the PreToolUse gate). Issue #498, Part A.
+//
+// The two hooks used to hand-copy the same numbered "how to load the framework"
+// step list. That copy drifted (RC1): it omitted the enablement step entirely and
+// named a stale nine-workflow count when the router lists eleven. The step prose now
+// lives here, in exactly ONE dist-less module, so the two cannot diverge again. It sits
+// under runtime/hooks/lib/ beside the other shared hook helpers (agent-entry-
+// sentinel.mjs, paqad-disabled.mjs); the .mjs hooks cannot import the TypeScript
+// onboarding writers, so the shared source has to be a runtime .mjs.
+//
+// Both hooks resolve enablement FIRST and short-circuit to a pure no-op when paqad
+// is OFF (issue #220). So if either directive is ever emitted, paqad is ON — the
+// gate has already proven it. The directive states that verdict up front (so the
+// agent spends zero tool calls re-checking it) and marks enablement a done step.
+
+/**
+ * The enablement verdict line. Emitted only on the enabled path — both entry hooks
+ * bail out silently when paqad is OFF — so it states ON as a proven fact, not a
+ * guess. Both hooks open their directive with it, so the two stay in sync.
+ */
+export const ENABLEMENT_VERIFIED_LINE =
+  '[paqad] Enablement: ON — verified by this gate. The bootstrap enablement step is already done; do not re-check it.';
+
+/**
+ * The ordered load steps for the two-file entry chain (issue #498, Part B): read the
+ * provider entry stub, load the framework GATE (AGENT-BOOTSTRAP.md), then — since
+ * paqad is ON — load the ROUTER (AGENT-ROUTER.md) and route + load the always-load
+ * contract, and finally write the sentinel. Enablement is step 1, already resolved
+ * by the gate. There is no hardcoded workflow count here (it used to live in this
+ * prose and drifted); the router names the workflows.
+ *
+ * @param {string} entryFile the provider entry file (CLAUDE.md, AGENTS.md, …)
+ * @returns {string[]} one `[paqad]` line per step, in order
+ */
+export function loadSteps(entryFile) {
+  return [
+    '[paqad]   1. Enablement — ON, already resolved by this gate; do not re-probe it.',
+    `[paqad]   2. Read ${entryFile}`,
+    '[paqad]   3. Resolve .paqad/framework-path.txt and load the framework gate (AGENT-BOOTSTRAP.md in the install); its enablement step is already satisfied (step 1)',
+    '[paqad]   4. Since paqad is ON, load AGENT-ROUTER.md (same install directory) and route the message to one paqad workflow, then load docs/instructions/{stack,design-system,workflows}; load the rule contract (.paqad/context/session-context.md, else docs/instructions/rules) ONLY for feature-development',
+    '[paqad]   5. Write .paqad/.agent-entry-loaded with timestamp + entry-file path',
+  ];
+}

package/runtime/hooks/stage-writer.mjs

@@ -34,21 +34,15 @@ async function main(input) {
     const sessionId = payload?.session_id ?? null;
 
     const liveUrl = new URL('../../dist/stage-evidence/live-writer.js', import.meta.url);
-    const narrationUrl = new URL('../../dist/stage-evidence/narration.js', import.meta.url);
-    const [{ recordLiveStageEdit }, { narrateStageEntry }] = await Promise.all([
-      import(liveUrl.href),
-      import(narrationUrl.href),
-    ]);
-
-    // On-entry narration (Step 5a): compute the "▸ paqad · <stage>" line BEFORE
-    // recording, so the first-entry check reads the pre-edit ledger state, then print
-    // it as a user-visible line via Claude's `systemMessage` hook channel. Null when
-    // this edit does not newly enter a stage (idempotent / out-of-order / non-source).
-    const line = narrateStageEntry({ projectRoot, sessionId, targetPath });
-    if (line) {
-      process.stdout.write(`${JSON.stringify({ systemMessage: line })}\n`);
-    }
-
+    const { recordLiveStageEdit } = await import(liveUrl.href);
+
+    // Record the edit into the stage-evidence ledger. The on-entry "▸ paqad · <stage>"
+    // narration is NOT printed from this hook: the model speaks that line itself in its
+    // final message (the narration contract). A top-level `{systemMessage}` is a
+    // user-facing warning field, and Claude Code now renders a PreToolUse one on Desktop
+    // as a literal "PreToolUse:<Tool> says:" line (the same leak the Stop seam hit), so
+    // echoing it here would duplicate the model's narration in the developer's chat on
+    // every edit. The ledger write below still runs, so the record is never silent.
     recordLiveStageEdit({ projectRoot, sessionId, toolName, targetPath });
     return 0;
   } catch {