continuous-improvement 3.12.3 → 3.15.0

package/plugins/continuous-improvement/commands/dashboard.md

@@ -1,56 +1,56 @@
----
-name: dashboard
-description: Visual dashboard showing instinct health, observation stats, and learning progress
----
-
-# Instinct Dashboard
-
-Generate a visual dashboard for this project's continuous-improvement status.
-
-## Instructions
-
-1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars
-2. **Read observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
-3. **Read instincts:** Load all `*.yaml` files from project dir + `global/`
-4. **Read instinct packs:** Check if any packs from `instinct-packs/` have been loaded
-
-## Display Format
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║              continuous-improvement Dashboard                ║
-╠══════════════════════════════════════════════════════════════╣
-║                                                              ║
-║  Project: <name>              Level: <CAPTURE|ANALYZE|...>   ║
-║  Sessions: ~<obs/10>          Mode: <beginner|expert>        ║
-║                                                              ║
-║  ┌─ Observations ────────────────────────────────────────┐   ║
-║  │  Total: <n>    Unprocessed: <n>    Last: <date>       │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Instincts ───────────────────────────────────────────┐   ║
-║  │  Total: <n>                                           │   ║
-║  │  ████████░░ Auto-apply (0.7+): <n>                    │   ║
-║  │  █████░░░░░ Suggest (0.5-0.69): <n>                   │   ║
-║  │  ██░░░░░░░░ Silent (< 0.5): <n>                       │   ║
-║  │  Global: <n>    Project: <n>                          │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Top Instincts ───────────────────────────────────────┐   ║
-║  │  <list top 5 instincts by confidence with bars>       │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Health ──────────────────────────────────────────────┐   ║
-║  │  Stale (30+ days): <n>    Decaying: <n>               │   ║
-║  │  Recently reinforced: <n>                             │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-## After Display
-
-- If stale instincts > 0: suggest reviewing them
-- If unprocessed observations > 20: suggest running analysis
-- If no instincts exist: explain the auto-leveling timeline
-- Show available instinct packs that haven't been loaded yet
+---
+name: dashboard
+description: Visual dashboard showing instinct health, observation stats, and learning progress
+---
+
+# Instinct Dashboard
+
+Generate a visual dashboard for this project's continuous-improvement status.
+
+## Instructions
+
+1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars
+2. **Read observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
+3. **Read instincts:** Load all `*.yaml` files from project dir + `global/`
+4. **Read instinct packs:** Check if any packs from `instinct-packs/` have been loaded
+
+## Display Format
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║              continuous-improvement Dashboard                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Project: <name>              Level: <CAPTURE|ANALYZE|...>   ║
+║  Sessions: ~<obs/10>          Mode: <beginner|expert>        ║
+║                                                              ║
+║  ┌─ Observations ────────────────────────────────────────┐   ║
+║  │  Total: <n>    Unprocessed: <n>    Last: <date>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Instincts ───────────────────────────────────────────┐   ║
+║  │  Total: <n>                                           │   ║
+║  │  ████████░░ Auto-apply (0.7+): <n>                    │   ║
+║  │  █████░░░░░ Suggest (0.5-0.69): <n>                   │   ║
+║  │  ██░░░░░░░░ Silent (< 0.5): <n>                       │   ║
+║  │  Global: <n>    Project: <n>                          │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Top Instincts ───────────────────────────────────────┐   ║
+║  │  <list top 5 instincts by confidence with bars>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Health ──────────────────────────────────────────────┐   ║
+║  │  Stale (30+ days): <n>    Decaying: <n>               │   ║
+║  │  Recently reinforced: <n>                             │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## After Display
+
+- If stale instincts > 0: suggest reviewing them
+- If unprocessed observations > 20: suggest running analysis
+- If no instincts exist: explain the auto-leveling timeline
+- Show available instinct packs that haven't been loaded yet

package/plugins/continuous-improvement/commands/model-forward.md

@@ -0,0 +1,13 @@
+---
+name: model-forward
+description: Restate the model-forward stance — go with Claude, not against it; skills are scaffolding; the durable core is goal-driven execution plus guardrails.
+---
+
+# /model-forward
+
+Load the `model-forward` skill and apply its stance to the current session.
+
+1. Restate the two invariants: goal-driven execution (anchor on the highest stated goal) and self-discipline guardrails (the 7 Laws).
+2. Audit the current task for places where custom scaffolding fights a native Claude Code capability; list each with the native alternative.
+3. Apply the decision rules from the skill before adding any new skill, hook, or wrapper to the workflow.
+4. Close with one line naming which native capability was preferred, which scaffold (if any) was proposed for retirement, and that the operator decides.

package/plugins/continuous-improvement/commands/production-readiness-review.md

@@ -0,0 +1,53 @@
+---
+name: production-readiness-review
+description: "Parallel multi-agent readiness gate — fan blind reviewers across performance, security, UI/UX, and test coverage, each grounding findings in real code/logs/live data, then reconcile into one deduplicated, severity-ranked punch-list. Reports only; never fixes, merges, or deploys."
+---
+
+# /production-readiness-review
+
+The review-side sibling of `/ship`. Fans a set of blind, specialized reviewers across distinct dimensions, then reconciles their findings into a single prioritized punch-list. It reports — it does not fix. Fixing a finding is a separate `/ship` run.
+
+Pure routing over existing skills and agents. Adds no new code.
+
+## Usage
+
+```
+/production-readiness-review [scope]
+```
+
+`scope` defaults to the current branch diff against `origin/main`. Pass a path or PR number to narrow it.
+
+## Behavior
+
+1. **Scope** — establish ground truth: the diff under review and which changes are recent (`git diff`; `reconcile` fallback for branch/base state). Recent changes get extra scrutiny because they are the likeliest source of self-inflicted defects.
+2. **Fan out** — `superpowers:dispatching-parallel-agents` launches four reviewers, each blind to the others. Every reviewer is instructed to ground each finding in real code, logs, or live queries, and never to assume or fabricate state:
+   - **Performance & bundle-size** — hot paths, N+1 queries, unbounded work, regressions.
+   - **Security & data-access** (`security-auditor`) — authn/authz, input handling, injection, secret exposure, unsafe data access.
+   - **UI/UX correctness** — verified live with Playwright when the MCP is available, else static review of the changed surface.
+   - **Test coverage & flaky/stale mocks** (`test-engineer`) — uncovered branches, stale mocks, timing-flaky tests.
+3. **Reconcile** — a final pass dedupes findings across reviewers, ranks each CRITICAL / HIGH / MEDIUM / LOW by severity and confidence, and explicitly flags any defect introduced by the changes under review.
+4. **Present** — emit the consolidated punch-list, severity-ranked, with file references. **Stop.**
+
+## Hard stops (report, never act)
+
+- Does not fix, edit, commit, merge, or deploy anything — output is a punch-list only.
+- A reviewer that cannot ground a finding marks it `unverified` rather than asserting it.
+- If a dimension's tooling is unavailable (e.g. no Playwright MCP), it says so rather than silently skipping coverage.
+
+## Anti-patterns this command refuses
+
+- **Fabricated state.** No finding may rest on an assumed SHA, row, or log line — ground it or mark it `unverified`.
+- **Silent skip.** A dimension that cannot run is reported as not-run, never dropped from the summary.
+- **Drive-by fix.** Findings become `/ship` tasks; this command does not touch code.
+
+## Composition
+
+Routes through: `reconcile` (scope/ground truth) → `superpowers:dispatching-parallel-agents` (fan-out) → the `security-auditor` and `test-engineer` agents (two of the four dimensions) → a reconciliation pass that ranks and dedupes. Each step falls back to its inline behavior when the preferred skill or agent is not installed.
+
+## Example
+
+```
+/production-readiness-review #246
+```
+
+Scopes PR #246's diff, fans four blind reviewers across performance, security, UI/UX, and test coverage, then returns one deduplicated severity-ranked punch-list — flagging anything the PR's own changes introduced — and stops for you to prioritize.

package/plugins/continuous-improvement/commands/seven-laws.md

@@ -1,16 +1,16 @@
----
-name: seven-laws
-description: "Brand-aligned alias for /continuous-improvement. Reflect on the current session, analyze observations for patterns, and show instinct status under the 7 Laws of AI Agent Discipline."
----
-
-# /seven-laws
-
-Brand-aligned alias for [`/continuous-improvement`](continuous-improvement.md). Both commands run the exact same three-step workflow under the 7 Laws of AI Agent Discipline:
-
-1. **Reflect** (Law 5) — generate a reflection block for this session.
-2. **Analyze** (Law 7) — process pending observations into instincts.
-3. **Status** — show all instincts for the project + global with confidence and current level.
-
-Run the workflow defined in [`continuous-improvement.md`](continuous-improvement.md). Subcommands `weekly` and `always-on` work identically.
-
-`/continuous-improvement` remains supported indefinitely for backward compatibility. Prefer `/seven-laws` going forward — it matches the brand and the SKILL.md spec.
+---
+name: seven-laws
+description: "Brand-aligned alias for /continuous-improvement. Reflect on the current session, analyze observations for patterns, and show instinct status under the 7 Laws of AI Agent Discipline."
+---
+
+# /seven-laws
+
+Brand-aligned alias for [`/continuous-improvement`](continuous-improvement.md). Both commands run the exact same three-step workflow under the 7 Laws of AI Agent Discipline:
+
+1. **Reflect** (Law 5) — generate a reflection block for this session.
+2. **Analyze** (Law 7) — process pending observations into instincts.
+3. **Status** — show all instincts for the project + global with confidence and current level.
+
+Run the workflow defined in [`continuous-improvement.md`](continuous-improvement.md). Subcommands `weekly` and `always-on` work identically.
+
+`/continuous-improvement` remains supported indefinitely for backward compatibility. Prefer `/seven-laws` going forward — it matches the brand and the SKILL.md spec.

package/plugins/continuous-improvement/commands/ship.md

@@ -0,0 +1,57 @@
+---
+name: ship
+description: "Single-defect fast path — walk one bug from ground-truth audit through a TDD fix, full verification, a single-concern commit, and an open PR, then stop. Never auto-merges, never deploys. For multi-PR rollouts use /release-train instead."
+---
+
+# /ship
+
+The one-defect fast path. `/release-train` is for stacked multi-PR rollouts and `/proceed-with-the-recommendation` walks an arbitrary recommendation list; `/ship` is the common case: fix one defect, open one PR, hand it back for review.
+
+Pure routing over existing skills. It adds no new orchestration logic and it does NOT bypass branch protection, force-push, auto-merge, or deploy.
+
+## Usage
+
+```
+/ship <one-line description of the defect>
+```
+
+If the description is ambiguous or names more than one concern, `/ship` halts and asks you to narrow it — one defect per run.
+
+## Behavior
+
+In order, for the single defect:
+
+1. **Ground truth** — `reconcile` (or its inline fallback): confirm the working tree is clean and on a feature branch cut from an up-to-date `origin/<base>`. If on a protected branch or a stale base, halt and ask.
+2. **Reproduce (RED)** — `tdd-workflow`: write a failing test that reproduces the defect; watch it fail. Pre-test implementation code is deleted, not kept.
+3. **Fix (GREEN)** — write the minimal change that makes the test pass; watch it pass. One concern only.
+4. **Verify** — `verification-loop`: run the project's verify ladder (build, types, tests). Build-green is evidence of mechanism, not of the fix — confirm the defect itself no longer reproduces.
+5. **Commit** — one commit, one concern, staged by explicit filename (never `git add -A`). Use a Windows-safe commit message: a single-line `-m` (repeat `-m` for paragraphs) or `git commit -F <tempfile>` — no multi-line here-docs/here-strings.
+6. **Open PR** — `commit-commands:commit-push-pr` (or `gh pr create`): push the branch and open a single-concern PR that cites the plan or issue. **Stop here.** The merge is yours.
+7. **Deploy receipt (advisory)** — after you merge, `deploy-receipt` verifies the deployed SHA matches the merge SHA. Advisory only; `/ship` does not deploy.
+
+## Hard stops (halt and ask, never improvise)
+
+- Ambiguous or multi-concern defect description.
+- Working tree not clean, or branch is protected / cut from a stale base.
+- Any verification step fails with a non-obvious fix.
+- The fix would touch more than 15 non-generated files (that is no longer one concern — split it, or use `/release-train`).
+- Push would target a protected branch.
+
+## Anti-patterns this command refuses
+
+- **Auto-merge.** Never merges the PR it opens, even when CI is green.
+- **Deploy.** Never runs a deploy; `deploy-receipt` only verifies after you merge.
+- **Bypass.** No `--admin`, `--force`, `--no-verify`.
+- **Bundled concerns.** Will not fold an unrelated fix into the same commit; logs it as a deferred follow-up instead.
+
+## Composition
+
+Routes through, in order: `reconcile` → `tdd-workflow` → `verification-loop` → `commit-commands:commit-push-pr` → `deploy-receipt`. Each step falls back to its inline behavior when the preferred skill is not installed.
+
+## Example
+
+```
+/ship registration form accepts a negative deposit amount
+```
+
+Reconciles git state, writes a failing test asserting deposits must be positive, implements the guard, runs the verify ladder, commits one concern with a single-line message, opens the PR, and stops for your review.

package/plugins/continuous-improvement/commands/workspace-surface-audit.md

@@ -1,77 +1,77 @@
----
-name: workspace-surface-audit
-description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
----
-
-# /workspace-surface-audit
-
-Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
-
-## Usage
-
-```
-/workspace-surface-audit
-```
-
-## What It Checks
-
-1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
-2. **Environment surface** — `.env*` files (key names only, no secrets)
-3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
-4. **continuous-improvement surface** — existing skills, commands, hooks, agents
-
-## Output Format
-
-```
-=== Workspace Surface Audit ===
-
-## Current Surface
-- [What is usable right now]
-
-## Parity
-- [Where continuous-improvement matches or exceeds benchmarks]
-
-## Primitive-Only Gaps
-- [Tools exist, but continuous-improvement lacks clean operator skills]
-
-## Missing Integrations
-- [Capabilities not available yet]
-
-## Top 3-5 Next Moves
-1. [Concrete continuous-improvement-native addition]
-2. [Ordered by impact]
-```
-
-## Rules
-
-- **Never print secrets** — only provider names, capability names, file paths
-- **Prefer continuous-improvement** over generic "install another plugin" advice
-- **Organize by workflows**, not API brands
-- **Specific recommendations** — concrete enough to implement without another discovery pass
-
-## Example Output
-
-```
-## Current Surface
-- MCP: filesystem, github, playwright
-- Plugins: beginner, expert (continuous-improvement)
-- Env: STRIPE_API_KEY, FAL_KEY configured
-- Framework: Next.js 15, React 19, TypeScript
-
-## Parity
-- Continuous improvement: covered (native)
-- Testing discipline: covered (TDD workflows)
-
-## Primitive-Only Gaps
-- Stripe connected but no billing-operator skill
-- GitHub MCP available but no issue-triage workflow
-
-## Missing Integrations
-- No Linear connector detected
-- No Slack webhook configured
-
-## Top 3-5 Next Moves
-1. Create billing-operator skill (Stripe integration)
-2. Create github-ops workflow for issue triage
-3. Add Linear connector skill for project management
-```
+---
+name: workspace-surface-audit
+description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
+---
+
+# /workspace-surface-audit
+
+Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
+
+## Usage
+
+```
+/workspace-surface-audit
+```
+
+## What It Checks
+
+1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
+2. **Environment surface** — `.env*` files (key names only, no secrets)
+3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
+4. **continuous-improvement surface** — existing skills, commands, hooks, agents
+
+## Output Format
+
+```
+=== Workspace Surface Audit ===
+
+## Current Surface
+- [What is usable right now]
+
+## Parity
+- [Where continuous-improvement matches or exceeds benchmarks]
+
+## Primitive-Only Gaps
+- [Tools exist, but continuous-improvement lacks clean operator skills]
+
+## Missing Integrations
+- [Capabilities not available yet]
+
+## Top 3-5 Next Moves
+1. [Concrete continuous-improvement-native addition]
+2. [Ordered by impact]
+```
+
+## Rules
+
+- **Never print secrets** — only provider names, capability names, file paths
+- **Prefer continuous-improvement** over generic "install another plugin" advice
+- **Organize by workflows**, not API brands
+- **Specific recommendations** — concrete enough to implement without another discovery pass
+
+## Example Output
+
+```
+## Current Surface
+- MCP: filesystem, github, playwright
+- Plugins: beginner, expert (continuous-improvement)
+- Env: STRIPE_API_KEY, FAL_KEY configured
+- Framework: Next.js 15, React 19, TypeScript
+
+## Parity
+- Continuous improvement: covered (native)
+- Testing discipline: covered (TDD workflows)
+
+## Primitive-Only Gaps
+- Stripe connected but no billing-operator skill
+- GitHub MCP available but no issue-triage workflow
+
+## Missing Integrations
+- No Linear connector detected
+- No Slack webhook configured
+
+## Top 3-5 Next Moves
+1. Create billing-operator skill (Stripe integration)
+2. Create github-ops workflow for issue triage
+3. Add Linear connector skill for project management
+```

package/plugins/continuous-improvement/hooks/companion-preference.mjs

@@ -12,11 +12,17 @@
  *                             (when installed) or the install hint (when not).
  *
  * Fail-open: any unexpected error reading stdin / parsing settings / probing
- * the filesystem → emit { decision: "allow" } and exit 0. The hook never
- * blocks on its own bugs.
+ * the filesystem → exit 0 with empty stdout (allow). The hook never blocks
+ * on its own bugs.
  *
  * Stdin  : JSON { tool_name, tool_input }
- * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Stdout : empty on allow (no output = no opinion, the call proceeds); on
+ *          deny, the documented PreToolUse shape:
+ *          { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *            permissionDecision: "deny", permissionDecisionReason } }
+ *          A bare { decision: "allow" } is not schema-valid for PreToolUse
+ *          (the deprecated enum is "approve" | "block") and surfaces as a
+ *          "Hook JSON output validation failed" error on every tool call.
  * Exit   : 0 always — decision lives in stdout, never in the exit code.
  *
  * OVERRIDES map must stay row-aligned with skills/superpowers.md
@@ -50,8 +56,20 @@ const OVERRIDES = {
         plugin: "oh-my-claudecode",
     },
 };
-function emitAndExit(d) {
-    process.stdout.write(`${JSON.stringify(d)}\n`);
+// Allow = empty stdout + exit 0. Emitting JSON here is wrong: PreToolUse has
+// no { decision: "allow" } shape, and the invalid output surfaces as a
+// per-tool-call "Hook JSON output validation failed" error in the client.
+function emitAllowAndExit() {
+    process.exit(0);
+}
+function emitDenyAndExit(reason) {
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    })}\n`);
     process.exit(0);
 }
 function readStdin() {
@@ -137,19 +155,19 @@ function main() {
         payload = JSON.parse(raw);
     }
     catch {
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     if (payload.tool_name !== "Skill") {
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     const skill = payload.tool_input?.skill;
     if (typeof skill !== "string" || skill.length === 0) {
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     const normalized = normalizeSkill(skill);
     const override = OVERRIDES[normalized];
     if (!override) {
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     const home = resolveHome();
     const mode = readMode(home);
@@ -166,25 +184,19 @@ function main() {
         // Shadow row: what companions-first would have done. This is the data
         // set that earns a future default-flip decision.
         writeTelemetry(home, { ...baseEvent, mode, action: "observation" });
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     if (mode === "companions-first") {
         process.stderr.write(`[continuous-improvement] companion_preference=companions-first → prefer \`${override.companion}\` over \`ci:${normalized}\`.\n`);
         writeTelemetry(home, { ...baseEvent, mode, action: "advisory" });
-        emitAndExit({ decision: "allow" });
+        emitAllowAndExit();
     }
     // strict-companions: always block; reason depends on install state.
     if (installed) {
         writeTelemetry(home, { ...baseEvent, mode, action: "block" });
-        emitAndExit({
-            decision: "block",
-            reason: `companion_preference=strict-companions: route to \`${override.companion}\` instead of \`ci:${normalized}\`. The CI fallback is suppressed by your setting.`,
-        });
+        emitDenyAndExit(`companion_preference=strict-companions: route to \`${override.companion}\` instead of \`ci:${normalized}\`. The CI fallback is suppressed by your setting.`);
     }
     writeTelemetry(home, { ...baseEvent, mode, action: "block-not-installed" });
-    emitAndExit({
-        decision: "block",
-        reason: `companion_preference=strict-companions: companion plugin \`${override.plugin}\` is not installed. Install with \`/plugin install ${override.plugin}@continuous-improvement\` or relax the setting to \`companions-first\` or \`ci-first\` in ~/.claude/settings.json.`,
-    });
+    emitDenyAndExit(`companion_preference=strict-companions: companion plugin \`${override.plugin}\` is not installed. Install with \`/plugin install ${override.plugin}@continuous-improvement\` or relax the setting to \`companions-first\` or \`ci-first\` in ~/.claude/settings.json.`);
 }
 main();

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -3,7 +3,13 @@
  * Runtime PreToolUse gateguard hook.
  *
  * Stdin  : JSON { tool_name, tool_input }
- * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Stdout : empty on allow (no output = no opinion, the call proceeds); on
+ *          deny, the documented PreToolUse shape:
+ *          { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *            permissionDecision: "deny", permissionDecisionReason } }
+ *          A bare { decision: "allow" } is not schema-valid for PreToolUse
+ *          (the deprecated enum is "approve" | "block") and surfaces as a
+ *          "Hook JSON output validation failed" error on every tool call.
  * Exit   : 0 always (decision is in stdout, fail-open on parse error).
  *
  * Three-stage gate per skills/gateguard.md:
@@ -132,7 +138,7 @@ function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
         "",
         "Then clear the gate and retry the same call. Either route works:",
         `  A. Bash (always works — run verbatim): node ${quotePath(CLEAR_CLI_PATH)} --state ${quotePath(stateFilePath)} ${quoted.join(" ")}`,
-        `  B. MCP tool (when the continuous-improvement server is connected): ci_gateguard_clear  {file_paths: [${quoted.join(", ")}]}`,
+        `  B. MCP tool (when the continuous-improvement server is connected): ci_gateguard_clear  {file_paths: [${quoted.join(", ")}], state_path: ${quotePath(stateFilePath)}}`,
         "  Both canonicalize paths — drive-letter case and separators don't matter.",
         "  (Harnesses that forward unknown tool params may instead retry the call with",
         "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
@@ -151,13 +157,26 @@ function buildDestructiveBashReason(command) {
 }
 function buildCapReachedReason() {
     return [
-        `Gateguard session clearance cap reached (${MAX_CLEARED_FILES} distinct files).`,
-        "Start a new Claude Code session to reset the gate. The cap exists to bound",
-        "stuck-loop or rogue-agent clearance from compounding within a single session.",
+        `Gateguard clearance cap reached (${MAX_CLEARED_FILES} distinct files this session).`,
+        "The cap is per-session: start a new Claude Code session to reset it, or wait",
+        "for the state file to self-heal. It bounds stuck-loop or rogue-agent clearance",
+        "from compounding within one session without affecting your other sessions.",
     ].join("\n");
 }
-function emit(decision) {
-    process.stdout.write(`${JSON.stringify(decision)}\n`);
+// Allow = empty stdout + exit 0. Emitting JSON here is wrong: PreToolUse has
+// no { decision: "allow" } shape, and the invalid output surfaces as a
+// per-tool-call "Hook JSON output validation failed" error in the client.
+function emitAllow() {
+    process.exit(0);
+}
+function emitDeny(reason) {
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    })}\n`);
     process.exit(0);
 }
 function main() {
@@ -166,7 +185,7 @@ function main() {
         raw = readFileSync(0, "utf8");
     }
     catch {
-        emit({ decision: "allow" });
+        emitAllow();
         return;
     }
     let payload;
@@ -174,23 +193,26 @@ function main() {
         payload = JSON.parse(raw);
     }
     catch {
-        emit({ decision: "allow" }); // fail-open
+        emitAllow(); // fail-open
         return;
     }
     const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
     const toolInput = payload.tool_input ?? {};
     const gate = classifyTool(toolName, toolInput);
     if (gate === "allow") {
-        emit({ decision: "allow" });
+        emitAllow();
         return;
     }
     if (gate === "destructive-bash") {
         const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
-        emit({ decision: "block", reason: buildDestructiveBashReason(cmd) });
+        emitDeny(buildDestructiveBashReason(cmd));
         return;
     }
-    // mutating-file
-    const sessionDir = resolveSessionDir();
+    // mutating-file — scope state to THIS session so the clearance cap never
+    // bleeds across concurrent same-day sessions. session_id is the standard hook
+    // stdin field (see recall-briefing / observe-event); absent → legacy dir.
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : undefined;
+    const sessionDir = resolveSessionDir(sessionId);
     const stateFilePath = join(sessionDir, "gateguard-session.json");
     const state = loadState(sessionDir);
     const filePaths = extractFilePaths(toolInput);
@@ -199,12 +221,12 @@ function main() {
     const alreadyCleared = filePaths.length > 0 && filePaths.every((path) => isFileCleared(state, path));
     const newFileCount = countDistinctNewFilePaths(filePaths, state);
     if (!factsFlagged && !alreadyCleared) {
-        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePaths.length > 0 ? filePaths : [filePath], stateFilePath) });
+        emitDeny(buildMutatingFileReason(toolName, filePaths.length > 0 ? filePaths : [filePath], stateFilePath));
         return;
     }
     if (factsFlagged && !alreadyCleared) {
         if (isCapReached(state) || Object.keys(state.cleared_files).length + newFileCount > MAX_CLEARED_FILES) {
-            emit({ decision: "block", reason: buildCapReachedReason() });
+            emitDeny(buildCapReachedReason());
             return;
         }
         let nextState = state;
@@ -214,6 +236,6 @@ function main() {
         if (filePaths.length > 0)
             saveState(sessionDir, nextState);
     }
-    emit({ decision: "allow" });
+    emitAllow();
 }
 main();