@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.a5a2de8

package/dist/resources/extensions/gsd/rule-registry.js

@@ -10,6 +10,9 @@ import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { parseUnitId } from "./unit-id.js";
+import { queryJournal } from "./journal.js";
+import { readUnitRuntimeRecord } from "./unit-runtime.js";
+import { extractFrontmatterVerdict } from "./verdict-parser.js";
 // ─── Artifact Path Resolution ──────────────────────────────────────────────
 export function resolveHookArtifactPath(basePath, unitId, artifactName) {
     const { milestone, slice, task } = parseUnitId(unitId);
@@ -38,6 +41,28 @@ export function convertDispatchRules(rules) {
 }
 // ─── RuleRegistry ─────────────────────────────────────────────────────────
 const HOOK_STATE_FILE = "hook-state.json";
+const FAILED_HOOK_RUNTIME_PHASES = new Set([
+    "timeout",
+    "finalize-timeout",
+    "crashed",
+    "paused",
+]);
+const HOOK_OUTCOME_VERDICTS = new Set([
+    "pass",
+    "advisory",
+    "needs-rework",
+    "needs-remediation",
+    "needs-attention",
+]);
+function isBlockingHook(config) {
+    return config?.criticality === "blocking";
+}
+function hookMaxCycles(config) {
+    return config.max_cycles ?? 1;
+}
+function hookCycleKey(config, trigger) {
+    return `${config.name}/${trigger.triggerUnitType}/${trigger.triggerUnitId}`;
+}
 export class RuleRegistry {
     /** Static dispatch rules provided at construction time. */
     dispatchRules;
@@ -47,6 +72,8 @@ export class RuleRegistry {
     cycleCounts = new Map();
     retryPending = false;
     retryTrigger = null;
+    hookFailure = null;
+    gateBlockPending = null;
     constructor(dispatchRules) {
         this.dispatchRules = dispatchRules;
     }
@@ -71,6 +98,7 @@ export class RuleRegistry {
                     artifact: hook.artifact,
                     retry_on: hook.retry_on,
                     max_cycles: hook.max_cycles,
+                    criticality: hook.criticality,
                 },
             });
         }
@@ -117,7 +145,9 @@ export class RuleRegistry {
     evaluatePostUnit(completedUnitType, completedUnitId, basePath) {
         // If we just completed a hook unit, handle its result
         if (this.activeHook) {
-            return this._handleHookCompletion(basePath);
+            const observedCleanExecution = completedUnitType === `hook/${this.activeHook.hookName}` &&
+                completedUnitId === this.activeHook.triggerUnitId;
+            return this._handleHookCompletion(basePath, observedCleanExecution);
         }
         // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
         // Don't trigger hooks for triage units or quick-task units
@@ -141,75 +171,371 @@ export class RuleRegistry {
     _dequeueNextHook(basePath) {
         while (this.hookQueue.length > 0) {
             const entry = this.hookQueue.shift();
-            const { config, triggerUnitType, triggerUnitId } = entry;
-            // Check idempotency — if artifact already exists, skip
-            if (config.artifact) {
+            const { config, triggerUnitType, triggerUnitId, forceRun } = entry;
+            // Advisory hooks preserve existing idempotency: any configured artifact
+            // means the hook already ran. Blocking gates must verify outcome first.
+            if (config.artifact && !forceRun) {
                 const artifactPath = resolveHookArtifactPath(basePath, triggerUnitId, config.artifact);
-                if (existsSync(artifactPath))
-                    continue;
+                if (existsSync(artifactPath)) {
+                    const completion = this._assessConfiguredHookCompletion(basePath, config.name, triggerUnitId);
+                    if (completion.outcome === "failed") {
+                        return this._handleFailedHookCompletion(basePath, {
+                            hookName: config.name,
+                            triggerUnitType,
+                            triggerUnitId,
+                            cycle: this.cycleCounts.get(hookCycleKey(config, { triggerUnitType, triggerUnitId })) ?? 0,
+                            pendingRetry: false,
+                        }, config, completion.reason);
+                    }
+                    if (!isBlockingHook(config))
+                        continue;
+                    const decision = this._handleExistingBlockingArtifact(config, { triggerUnitType, triggerUnitId }, basePath);
+                    if (decision === "skip")
+                        continue;
+                    return decision;
+                }
+            }
+            const dispatch = this._startHook(config, triggerUnitType, triggerUnitId);
+            if (dispatch)
+                return dispatch;
+            if (isBlockingHook(config)) {
+                const cycleKey = hookCycleKey(config, { triggerUnitType, triggerUnitId });
+                const maxCycles = hookMaxCycles(config);
+                const currentCycle = this.cycleCounts.get(cycleKey) ?? 0;
+                if (currentCycle >= maxCycles) {
+                    this._setGateBlock(config, { triggerUnitType, triggerUnitId }, {
+                        action: "pause",
+                        reason: `gate cycle budget exhausted before ${config.name} produced a passing outcome`,
+                        cycle: currentCycle,
+                        maxCycles,
+                    });
+                    return null;
+                }
             }
-            // Check cycle limit
-            const cycleKey = `${config.name}/${triggerUnitType}/${triggerUnitId}`;
-            const currentCycle = (this.cycleCounts.get(cycleKey) ?? 0) + 1;
-            const maxCycles = config.max_cycles ?? 1;
-            if (currentCycle > maxCycles)
-                continue;
-            this.cycleCounts.set(cycleKey, currentCycle);
-            this.activeHook = {
-                hookName: config.name,
-                triggerUnitType,
-                triggerUnitId,
-                cycle: currentCycle,
-                pendingRetry: false,
-            };
-            // Build prompt with variable substitution
-            const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
-            let prompt = config.prompt
-                .replace(/\{milestoneId\}/g, mid ?? "")
-                .replace(/\{sliceId\}/g, sid ?? "")
-                .replace(/\{taskId\}/g, tid ?? "");
-            // Inject browser safety instruction
-            prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
-            return {
-                hookName: config.name,
-                prompt,
-                model: config.model,
-                unitType: `hook/${config.name}`,
-                unitId: triggerUnitId,
-            };
         }
         // No more hooks — clear active state
         this.activeHook = null;
         return null;
     }
-    _handleHookCompletion(basePath) {
+    _handleHookCompletion(basePath, observedCleanExecution) {
         const hook = this.activeHook;
         const hooks = resolvePostUnitHooks(basePath);
         const config = hooks.find(h => h.name === hook.hookName);
+        if (!config) {
+            this.activeHook = null;
+            return this._dequeueNextHook(basePath);
+        }
+        const completion = this._assessHookCompletion(basePath, hook);
+        if (completion.outcome === "failed") {
+            return this._handleFailedHookCompletion(basePath, hook, config, completion.reason);
+        }
         // Check if retry was requested via retry_on artifact
-        if (config?.retry_on) {
+        if (config.retry_on) {
             const retryArtifactPath = resolveHookArtifactPath(basePath, hook.triggerUnitId, config.retry_on);
             if (existsSync(retryArtifactPath)) {
-                const cycleKey = `${config.name}/${hook.triggerUnitType}/${hook.triggerUnitId}`;
-                const currentCycle = this.cycleCounts.get(cycleKey) ?? 1;
-                const maxCycles = config.max_cycles ?? 1;
-                if (currentCycle < maxCycles) {
+                if (this._requestTriggerRetry(config, hook, config.retry_on)) {
+                    return null;
+                }
+                if (isBlockingHook(config)) {
+                    this._setGateBlock(config, hook, {
+                        action: "pause",
+                        reason: `gate cycle budget exhausted after ${config.retry_on} requested rework`,
+                        retryArtifact: config.retry_on,
+                    });
                     this.activeHook = null;
                     this.hookQueue = [];
-                    this.retryPending = true;
-                    this.retryTrigger = {
-                        unitType: hook.triggerUnitType,
-                        unitId: hook.triggerUnitId,
-                        retryArtifact: config.retry_on,
-                    };
                     return null;
                 }
             }
         }
+        if (isBlockingHook(config)) {
+            return this._handleBlockingGateCompletion(config, hook, basePath, observedCleanExecution);
+        }
         // Hook completed normally — try next hook in queue
         this.activeHook = null;
         return this._dequeueNextHook(basePath);
     }
+    _startHook(config, triggerUnitType, triggerUnitId) {
+        const cycleKey = `${config.name}/${triggerUnitType}/${triggerUnitId}`;
+        const currentCycle = (this.cycleCounts.get(cycleKey) ?? 0) + 1;
+        const maxCycles = config.max_cycles ?? 1;
+        if (currentCycle > maxCycles)
+            return null;
+        this.cycleCounts.set(cycleKey, currentCycle);
+        this.activeHook = {
+            hookName: config.name,
+            triggerUnitType,
+            triggerUnitId,
+            cycle: currentCycle,
+            pendingRetry: false,
+        };
+        const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
+        let prompt = config.prompt
+            .replace(/\{milestoneId\}/g, mid ?? "")
+            .replace(/\{sliceId\}/g, sid ?? "")
+            .replace(/\{taskId\}/g, tid ?? "");
+        prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
+        return {
+            hookName: config.name,
+            prompt,
+            model: config.model,
+            unitType: `hook/${config.name}`,
+            unitId: triggerUnitId,
+        };
+    }
+    _assessHookCompletion(basePath, hook) {
+        return this._assessConfiguredHookCompletion(basePath, hook.hookName, hook.triggerUnitId);
+    }
+    _assessConfiguredHookCompletion(basePath, hookName, unitId) {
+        const unitType = `hook/${hookName}`;
+        const latestUnitEnd = this._latestHookUnitEnd(basePath, unitType, unitId);
+        if (latestUnitEnd) {
+            const data = latestUnitEnd.data ?? {};
+            const status = data.status;
+            const artifactVerified = data.artifactVerified;
+            if (status === "completed" && artifactVerified !== false) {
+                return { outcome: "success" };
+            }
+            return {
+                outcome: "failed",
+                reason: this._formatHookFailureReason(status, artifactVerified, data.errorContext),
+            };
+        }
+        const runtime = readUnitRuntimeRecord(basePath, unitType, unitId);
+        if (runtime && FAILED_HOOK_RUNTIME_PHASES.has(runtime.phase)) {
+            return { outcome: "failed", reason: `runtime phase ${runtime.phase}` };
+        }
+        return { outcome: "unknown" };
+    }
+    _latestHookUnitEnd(basePath, unitType, unitId) {
+        const unitEnds = queryJournal(basePath, { eventType: "unit-end", unitId })
+            .filter(entry => entry.data?.unitType === unitType);
+        return unitEnds[unitEnds.length - 1] ?? null;
+    }
+    _formatHookFailureReason(status, artifactVerified, errorContext) {
+        const parts = [`status ${typeof status === "string" ? status : "unknown"}`];
+        if (artifactVerified === false) {
+            parts.push("artifact not verified");
+        }
+        if (typeof errorContext === "object" && errorContext !== null && "message" in errorContext) {
+            const message = errorContext.message;
+            if (typeof message === "string" && message.length > 0) {
+                parts.push(message);
+            }
+        }
+        return parts.join("; ");
+    }
+    _handleFailedHookCompletion(basePath, hook, config, reason) {
+        if (config) {
+            const retry = this._startHook(config, hook.triggerUnitType, hook.triggerUnitId);
+            if (retry)
+                return retry;
+        }
+        this.hookFailure = {
+            hookName: hook.hookName,
+            unitType: `hook/${hook.hookName}`,
+            unitId: hook.triggerUnitId,
+            reason,
+        };
+        this.activeHook = null;
+        this.hookQueue = [];
+        this.persistState(basePath);
+        return null;
+    }
+    _handleExistingBlockingArtifact(config, trigger, basePath) {
+        const outcome = this._readGateOutcome(config, trigger, basePath);
+        switch (outcome.verdict) {
+            case "pass":
+            case "advisory":
+                return "skip";
+            case "needs-rework":
+                return this._routeNeedsRework(config, trigger, outcome);
+            case "needs-remediation":
+            case "needs-attention":
+                this._pauseForGate(config, trigger, outcome, `gate reported ${outcome.verdict}`);
+                return null;
+            case "failed":
+            case undefined:
+                return this._rerunGateOrBlock(config, trigger, basePath, {
+                    reason: outcome.reason ?? `gate artifact reported verdict=${outcome.verdict}`,
+                    outcome,
+                });
+        }
+        return this._rerunGateOrBlock(config, trigger, basePath, {
+            reason: `gate artifact reported unsupported verdict=${String(outcome.verdict)}`,
+            outcome,
+        });
+    }
+    _handleBlockingGateCompletion(config, hook, basePath, observedCleanExecution) {
+        if (!observedCleanExecution) {
+            return this._rerunGateOrBlock(config, hook, basePath, {
+                reason: `hook/${config.name} did not complete cleanly before the trigger unit resumed`,
+            });
+        }
+        const outcome = this._readGateOutcome(config, hook, basePath);
+        switch (outcome.verdict) {
+            case "pass":
+            case "advisory":
+                this.activeHook = null;
+                return this._dequeueNextHook(basePath);
+            case "needs-rework":
+                return this._routeNeedsRework(config, hook, outcome);
+            case "needs-remediation":
+            case "needs-attention":
+                return this._pauseForGate(config, hook, outcome, `gate reported ${outcome.verdict}`);
+            case "failed":
+            case undefined:
+                return this._rerunGateOrBlock(config, hook, basePath, {
+                    reason: outcome.reason ?? `gate artifact reported verdict=${outcome.verdict}`,
+                    outcome,
+                });
+        }
+        return this._rerunGateOrBlock(config, hook, basePath, {
+            reason: `gate artifact reported unsupported verdict=${String(outcome.verdict)}`,
+            outcome,
+        });
+    }
+    _routeNeedsRework(config, trigger, outcome) {
+        const action = config.on_block?.action ?? "retry-unit";
+        if (action === "retry-task" || action === "retry-unit") {
+            if (this._requestTriggerRetry(config, trigger, config.on_block?.artifact)) {
+                return null;
+            }
+            this._setGateBlock(config, trigger, {
+                action: "pause",
+                reason: "gate cycle budget exhausted after needs-rework",
+                outcome,
+                retryArtifact: config.on_block?.artifact,
+            });
+            this.activeHook = null;
+            this.hookQueue = [];
+            return null;
+        }
+        return this._pauseForGate(config, trigger, outcome, `gate reported needs-rework; configured on_block action is ${action}`);
+    }
+    _pauseForGate(config, trigger, outcome, reason) {
+        this._setGateBlock(config, trigger, {
+            action: config.on_block?.action ?? "pause",
+            reason,
+            outcome,
+            retryArtifact: config.on_block?.artifact,
+        });
+        this.activeHook = null;
+        this.hookQueue = [];
+        return null;
+    }
+    _requestTriggerRetry(config, hook, retryArtifact) {
+        const cycleKey = hookCycleKey(config, hook);
+        const currentCycle = this.cycleCounts.get(cycleKey) ?? 1;
+        const maxCycles = hookMaxCycles(config);
+        if (currentCycle >= maxCycles)
+            return false;
+        this.activeHook = null;
+        this.hookQueue = [];
+        this.retryPending = true;
+        this.retryTrigger = {
+            unitType: hook.triggerUnitType,
+            unitId: hook.triggerUnitId,
+        };
+        if (retryArtifact !== undefined) {
+            this.retryTrigger.retryArtifact = retryArtifact;
+        }
+        return true;
+    }
+    _rerunGateOrBlock(config, trigger, basePath, opts) {
+        const cycleKey = hookCycleKey(config, trigger);
+        const currentCycle = this.cycleCounts.get(cycleKey) ?? 0;
+        const maxCycles = hookMaxCycles(config);
+        if (currentCycle < maxCycles) {
+            this.activeHook = null;
+            this.hookQueue.unshift({
+                config,
+                triggerUnitType: trigger.triggerUnitType,
+                triggerUnitId: trigger.triggerUnitId,
+                forceRun: true,
+            });
+            return this._dequeueNextHook(basePath);
+        }
+        this._setGateBlock(config, trigger, {
+            action: "pause",
+            reason: `${opts.reason}; gate cycle budget exhausted`,
+            outcome: opts.outcome,
+            cycle: currentCycle,
+            maxCycles,
+        });
+        this.activeHook = null;
+        this.hookQueue = [];
+        return null;
+    }
+    _readGateOutcome(config, trigger, basePath) {
+        if (!config.artifact) {
+            return { reason: "blocking gate has no configured artifact" };
+        }
+        const artifactPath = resolveHookArtifactPath(basePath, trigger.triggerUnitId, config.artifact);
+        if (!existsSync(artifactPath)) {
+            return {
+                artifact: config.artifact,
+                artifactPath,
+                reason: `missing required gate artifact ${config.artifact}`,
+            };
+        }
+        let content = "";
+        try {
+            content = readFileSync(artifactPath, "utf-8");
+        }
+        catch (e) {
+            return {
+                artifact: config.artifact,
+                artifactPath,
+                reason: `could not read gate artifact ${config.artifact}: ${e.message}`,
+            };
+        }
+        const rawVerdict = extractFrontmatterVerdict(content);
+        if (!rawVerdict) {
+            return {
+                artifact: config.artifact,
+                artifactPath,
+                reason: `gate artifact ${config.artifact} is missing frontmatter verdict`,
+            };
+        }
+        if (rawVerdict === "failed") {
+            return {
+                artifact: config.artifact,
+                artifactPath,
+                verdict: "failed",
+                reason: `gate artifact ${config.artifact} reported verdict=failed`,
+            };
+        }
+        if (!HOOK_OUTCOME_VERDICTS.has(rawVerdict)) {
+            return {
+                artifact: config.artifact,
+                artifactPath,
+                reason: `gate artifact ${config.artifact} has unsupported verdict=${rawVerdict}`,
+            };
+        }
+        return {
+            artifact: config.artifact,
+            artifactPath,
+            verdict: rawVerdict,
+        };
+    }
+    _setGateBlock(config, trigger, opts) {
+        const cycleKey = hookCycleKey(config, trigger);
+        const cycle = opts.cycle ?? this.cycleCounts.get(cycleKey) ?? 0;
+        this.gateBlockPending = {
+            hookName: config.name,
+            triggerUnitType: trigger.triggerUnitType,
+            triggerUnitId: trigger.triggerUnitId,
+            artifact: opts.outcome?.artifact ?? config.artifact,
+            artifactPath: opts.outcome?.artifactPath,
+            verdict: opts.outcome?.verdict,
+            action: opts.action,
+            reason: opts.reason,
+            cycle,
+            maxCycles: opts.maxCycles ?? hookMaxCycles(config),
+            retryArtifact: opts.retryArtifact,
+        };
+    }
     // ── Pre-dispatch hook evaluation (sync, all-matching with compose) ──
     /**
      * Replicate exact semantics of runPreDispatchHooks from post-unit-hooks.ts:
@@ -275,6 +601,16 @@ export class RuleRegistry {
     isRetryPending() {
         return this.retryPending;
     }
+    consumeHookFailure() {
+        if (!this.hookFailure)
+            return null;
+        const failure = { ...this.hookFailure };
+        this.hookFailure = null;
+        return failure;
+    }
+    isGateBlockPending() {
+        return this.gateBlockPending !== null;
+    }
     /**
      * Returns the trigger unit info for a pending retry, or null.
      * Clears the retry state after reading.
@@ -287,22 +623,42 @@ export class RuleRegistry {
         this.retryTrigger = null;
         return trigger;
     }
-    /** Clear all mutable state (activeHook, hookQueue, cycleCounts, retryPending, retryTrigger). */
+    /**
+     * Returns a pending post-unit gate block, or null.
+     * Clears the block state after reading.
+     */
+    consumeGateBlock() {
+        if (!this.gateBlockPending)
+            return null;
+        const block = { ...this.gateBlockPending };
+        this.gateBlockPending = null;
+        return block;
+    }
+    /** Clear all mutable hook lifecycle state. */
     resetState() {
         this.activeHook = null;
         this.hookQueue = [];
         this.cycleCounts.clear();
         this.retryPending = false;
         this.retryTrigger = null;
+        this.hookFailure = null;
+        this.gateBlockPending = null;
     }
     // ── Persistence ─────────────────────────────────────────────────────
     _hookStatePath(basePath) {
         return join(basePath, ".gsd", HOOK_STATE_FILE);
     }
-    /** Persist current hook cycle counts to disk. */
+    /** Persist current hook state to disk. */
     persistState(basePath) {
         const state = {
             cycleCounts: Object.fromEntries(this.cycleCounts),
+            activeHook: this.activeHook ? { ...this.activeHook } : null,
+            hookQueue: this.hookQueue.map(entry => ({
+                hookName: entry.config.name,
+                triggerUnitType: entry.triggerUnitType,
+                triggerUnitId: entry.triggerUnitId,
+                forceRun: entry.forceRun,
+            })),
             savedAt: new Date().toISOString(),
         };
         try {
@@ -315,7 +671,7 @@ export class RuleRegistry {
             logWarning("registry", `failed to persist hook state: ${e.message}`);
         }
     }
-    /** Restore hook cycle counts from disk after a crash/restart. */
+    /** Restore hook state from disk after a crash/restart. */
     restoreState(basePath) {
         try {
             const filePath = this._hookStatePath(basePath);
@@ -331,6 +687,24 @@ export class RuleRegistry {
                     }
                 }
             }
+            this.activeHook = state.activeHook && typeof state.activeHook === "object"
+                ? { ...state.activeHook }
+                : null;
+            this.hookQueue = [];
+            if (Array.isArray(state.hookQueue)) {
+                const hooks = resolvePostUnitHooks(basePath);
+                for (const entry of state.hookQueue) {
+                    const config = hooks.find(h => h.name === entry.hookName);
+                    if (config) {
+                        this.hookQueue.push({
+                            config,
+                            triggerUnitType: entry.triggerUnitType,
+                            triggerUnitId: entry.triggerUnitId,
+                            forceRun: entry.forceRun,
+                        });
+                    }
+                }
+            }
         }
         catch (e) {
             logWarning("registry", `failed to restore hook state: ${e.message}`);
@@ -341,7 +715,7 @@ export class RuleRegistry {
         try {
             const filePath = this._hookStatePath(basePath);
             if (existsSync(filePath)) {
-                writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, savedAt: new Date().toISOString() }, null, 2), "utf-8");
+                writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2), "utf-8");
             }
         }
         catch (e) {
@@ -365,6 +739,7 @@ export class RuleRegistry {
                 type: "post",
                 enabled: hook.enabled !== false,
                 targets: hook.after,
+                criticality: hook.criticality ?? "advisory",
                 activeCycles,
             });
         }
@@ -436,9 +811,10 @@ export class RuleRegistry {
             lines.push("Post-Unit Hooks (run after unit completes):");
             for (const hook of postHooks) {
                 const status = hook.enabled ? "enabled" : "disabled";
+                const criticality = hook.criticality ?? "advisory";
                 const cycles = Object.keys(hook.activeCycles).length;
                 const cycleInfo = cycles > 0 ? ` (${cycles} active cycle${cycles === 1 ? "" : "s"})` : "";
-                lines.push(`  ${hook.name} [${status}] → after: ${hook.targets.join(", ")}${cycleInfo}`);
+                lines.push(`  ${hook.name} [${status}, ${criticality}] → after: ${hook.targets.join(", ")}${cycleInfo}`);
             }
             lines.push("");
         }

package/dist/resources/extensions/gsd/state.js

@@ -724,8 +724,8 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
         }
     }
     // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
-    // next task. `awaiting_review` tasks (continueWithDefault=true) are NOT
-    // surfaced here — they let the loop continue.
+    // next task. `awaiting_review` tasks (continueWithDefault=true) still pause
+    // here so silence is never treated as consent.
     //
     // We do NOT gate this on `phases.mid_execution_escalation` — creation of
     // new escalations is gated at the write site (tools/complete-task.ts:315),

package/dist/resources/extensions/gsd/templates/plan.md

@@ -132,14 +132,16 @@
   Verify field rules:
   - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
   - MUST NOT use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`
+  - For absence checks, use `! grep -q "pattern" file` or `! rg -q "pattern" file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches
   - MUST NOT use inline `node -e` assertions for verification; put assertions in a real test file and run it with `node --test` or a package test script
   - For content/document tasks: verify file existence, section count, YAML validity, or word count
     NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
   - If no command can verify the output, write: "Manual review — file exists and is non-empty"
   - BAD: `python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5`
+  - BAD: `grep -c "old_api" src/index.ts`
   - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
   - GOOD: `python3 -m pytest tests/ -q --tb=short`
-  - GOOD: `node --test tests/verify-doc.test.js`, `grep -q "Required heading" doc.md`, `test -s doc.md`
+  - GOOD: `node --test tests/verify-doc.test.js`, `grep -q "Required heading" doc.md`, `! grep -q "old_api" src/index.ts`, `test -s doc.md`
 
   Integration closure rule:
   - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening

package/dist/resources/extensions/gsd/tool-contract.js

@@ -2,8 +2,10 @@
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
+    const surfaceContract = getUnitToolSurfaceContract(unitType);
     if (!manifest) {
         return {
             ok: false,
@@ -12,6 +14,8 @@ export function compileUnitToolContract(unitType) {
         };
     }
     const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
+        .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool));
     if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
         return {
@@ -27,6 +31,7 @@ export function compileUnitToolContract(unitType) {
             contextMode: manifest.contextMode,
             toolsPolicy: manifest.tools,
             requiredWorkflowTools,
+            forbiddenWorkflowTools,
             promptObligations: [
                 `context-mode:${manifest.contextMode}`,
                 `tools-policy:${manifest.tools.mode}`,