paqad-ai 1.76.1 → 1.76.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # paqad-ai
 
+## 1.76.2
+
+### Patch Changes
+
+- 7ce4c34: fix: stop the `Stop says:` narration leak — silence Stop-hook `{systemMessage}` prose
+
+  Claude Code changed how it renders Stop-hook output: a Stop-hook `{systemMessage}` now renders on Desktop as literal `Stop says:` lines, inverting the premise the #368/#409 narration design was built on (that the channel was invisible, so the agent speaks the receipt and the hook echo is a silent backchannel). With the host inverted, paqad's three Stop-event emitters poured user-facing prose into that channel on every turn, across every onboarded repo and machine — duplicating the receipt the agent already speaks and leaking the model-only narration advisory into the developer's chat.
+
+  The Stop hooks no longer emit user-facing `{systemMessage}` prose:
+
+  - `runtime/scripts/verify-backstop.mjs` (`hook-completion`): writes nothing on a pass/inconclusive turn and only a model-only `{decision:'block'}` reason on a hard failure. Enforcement is unchanged — the block reason reaches the model (never rendered on either host) and the git/CI backstop still hard-fails with exit 2.
+  - `runtime/hooks/capability-gate.mjs` (`completion` seam): no longer echoes narration on the allow path; the `pre-mutation` (PreToolUse) seam is unchanged.
+  - `runtime/hooks/stage-marker-parse.mjs`: still records every parsed marker to the ledger; only the chat echo is removed.
+
+  The developer-facing channel is the agent's own final message (the #409 contract), which was always the intended primary channel. The narration contract docs and the verification module doc are corrected to state the new host behavior. Decision `D-01KZV9HFGDXZ03J0S6P9BTQ53Q` records the approach.
+
 ## 1.76.1
 
 ### Patch Changes

package/dist/cli/index.js

@@ -36251,7 +36251,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.76.1";
+var VERSION = "1.76.2";
 
 // src/cli/commands/audit.ts
 init_esm_shims();

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paqad-ai",
-  "version": "1.76.1",
+  "version": "1.76.2",
   "description": "Spec-driven development framework — AI agents that think before they type",
   "type": "module",
   "license": "MIT",

package/runtime/AGENT-BOOTSTRAP.md

@@ -155,12 +155,15 @@ Emit the `start` marker as you begin the stage and the `end` marker as you finis
 
 | Channel | Claude Code CLI | Claude Code Desktop |
 | --- | --- | --- |
-| Hook `{systemMessage}` (PreToolUse / Stop) | rendered | **not rendered** — recorded as a hook attachment |
+| 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** |
 
-**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 their narration rides `{systemMessage}`, so on Desktop it is recorded and never shown (issue #409: a full six-stage run emitted eleven stage lines and the developer saw none of them, while the evidence bundle was complete). 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".
+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:
 

package/runtime/hooks/capability-gate.mjs

@@ -130,12 +130,20 @@ export async function main(input, seam = SEAM) {
       }
       return 2;
     }
-    // Allow path: surface narration + advisory findings through the host's
-    // user-message channel (`systemMessage`), not bare stdout — bare stdout is
+    // 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).
-    const visible = [result.narration, result.summary].filter(Boolean).join('\n');
-    if (visible) {
-      process.stdout.write(`${JSON.stringify({ systemMessage: visible })}\n`);
+    //
+    // 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`);
+      }
     }
     return 0;
   } catch {

package/runtime/hooks/stage-marker-parse.mjs

@@ -31,22 +31,17 @@ async function main(input) {
     if (!transcriptText) return 0;
 
     const distUrl = new URL('../../dist/stage-evidence/marker-parse.js', import.meta.url);
-    const narrationUrl = new URL('../../dist/stage-evidence/narration.js', import.meta.url);
-    const [{ parseAndRecordMarkers }, { markerBatchNarration }] = await Promise.all([
-      import(distUrl.href),
-      import(narrationUrl.href),
-    ]);
-    const recorded = parseAndRecordMarkers({
+    const { parseAndRecordMarkers } = await import(distUrl.href);
+    // Record every parsed marker to the ledger (issue #307 — the ledger write is
+    // non-negotiable). The chat echo that used to ride `{systemMessage}` is gone: this is a
+    // Stop hook, and Claude Code now RENDERS a Stop-hook `{systemMessage}` on Desktop as
+    // literal "Stop says:" lines, so echoing here duplicated the stage lines the agent
+    // already speaks itself (issue #409) and leaked into the developer's chat.
+    parseAndRecordMarkers({
       projectRoot,
       transcriptText,
       sessionId: payload?.session_id ?? null,
     });
-    // Narration and ledger are both non-negotiable (issue #307): every row this
-    // parse just minted is shown to the user via the host's user-message channel.
-    const narration = markerBatchNarration(recorded);
-    if (narration) {
-      process.stdout.write(`${JSON.stringify({ systemMessage: narration })}\n`);
-    }
     return 0;
   } catch {
     /* v8 ignore next */

package/runtime/scripts/verify-backstop.mjs

@@ -128,33 +128,34 @@ export async function runVerificationBackstop({
     // hook (it is a PreToolUse mechanism), so the old `return 2` was both invisible AND
     // a no-op. git/CI keep the exit-code-gated path below.
     if (origin === 'hook-completion') {
-      // Issue #409 — the voice backstop. `{systemMessage}` is exactly backwards for a
-      // receipt (the model reads it, the Desktop developer never sees it), which is why
-      // the agent must speak the receipt itself. But that same property makes it the
-      // right channel for an advisory ABOUT the narration: the audience is the model.
-      // So when this change recorded stages the agent never said out loud, the advisory
-      // rides along here, and is folded into the block reason below when a block is
-      // already firing for a real gate failure. It never causes a block of its own — a
-      // silent turn is a voice defect, not a broken change (INV-1).
-      const payload = {
-        systemMessage: verdict.narrationAdvisory
-          ? `${receipt}\n\n${verdict.narrationAdvisory}`
-          : receipt,
-      };
+      // The Stop hook no longer emits a `{systemMessage}`. Claude Code changed: a
+      // Stop-hook `{systemMessage}` now RENDERS on Desktop as literal "Stop says:" lines,
+      // inverting the #368/#409 premise that this channel was invisible. Routing the
+      // receipt through it duplicated the narration the agent already speaks (the #409
+      // contract) and leaked the model-only narration advisory into the developer's chat
+      // (the "Stop says:" narration leak). So the developer-facing channel is the agent's
+      // own final message; enforcement rides the `{decision:'block'}` reason below, which
+      // is NOT rendered on either host (it reaches the model only), plus the git/CI
+      // backstop.
+      const payload = {};
       // Give the gate real teeth on a HARD failure (a gate reported `fail`, e.g. a
       // mandatory stage missing or a red checks report): tell the model to keep working
       // and resolve it before the turn ends. An Inconclusive verdict (no failing gate —
-      // only unproven signals) is surfaced but never blocks: "do not over-trust", not
-      // "you must fix". The loop guard (`loopActive`, from Claude's `stop_hook_active`)
-      // means the gate already bit once this turn, so a second block would loop — step
-      // aside and let the session end (git/CI remains the hard gate).
+      // only unproven signals) never blocks: "do not over-trust", not "you must fix". The
+      // loop guard (`loopActive`, from Claude's `stop_hook_active`) means the gate already
+      // bit once this turn, so a second block would loop — step aside and let the session
+      // end (git/CI remains the hard gate). The narration advisory (issue #409) still rides
+      // the model-only reason when a block is already firing; on a clean turn there is no
+      // model-facing decision to convey, so the hook stays silent.
       if (verdictHasHardFailure(verdict) && !loopActive) {
         payload.decision = 'block';
         payload.reason = verdict.narrationAdvisory
           ? `${blockReason(verdict)}\n\n${verdict.narrationAdvisory}`
           : blockReason(verdict);
       }
-      out.write(`${JSON.stringify(payload)}\n`);
+      if (payload.decision) {
+        out.write(`${JSON.stringify(payload)}\n`);
+      }
       return 0;
     }