dsh-doublecheck 0.5.0 → 0.7.0

package/lib/domain/projection.js

@@ -12,6 +12,7 @@
  */
 import { isTestCommand, isTestFilePath, joinTextBlocks, mutationTargetPath, parseRawArguments, shellCommand, testOutcome, } from "./evidence.js";
 import { SPEC_TOOL_NAME } from "./stages.js";
+import { countRedChecks } from "./gate.js";
 /** State for the empty log. */
 export function emptyDoublecheckState() {
     return {
@@ -21,6 +22,8 @@ export function emptyDoublecheckState() {
         specGoal: '',
         reviewed: false,
         editCount: 0,
+        gateVerdict: 'none',
+        gateRedCount: 0,
         pendingSpecCalls: {},
         pendingTestCalls: {},
     };
@@ -98,6 +101,13 @@ export function applyDoublecheckEvent(state, event, detection) {
             }
             return state;
         }
+        case 'doublecheck/gate': {
+            const gate = event.data;
+            const redCount = countRedChecks(Object.values(gate.phases));
+            if (state.gateVerdict === gate.verdict && state.gateRedCount === redCount)
+                return state;
+            return { ...state, gateVerdict: gate.verdict, gateRedCount: redCount };
+        }
         default:
             return state;
     }
@@ -128,5 +138,7 @@ export function viewDoublecheck(state) {
         specGoal: state.specGoal,
         reviewed: state.reviewed,
         editCount: state.editCount,
+        gateVerdict: state.gateVerdict,
+        gateRedCount: state.gateRedCount,
     };
 }

package/lib/domain/vocabulary.d.ts

@@ -20,6 +20,8 @@ export interface GrilledSpec {
     /** What the user explicitly does not want. */
     nonGoals: string;
 }
+/** All six spec fields, in declaration order. */
+export declare const SPEC_FIELD_NAMES: readonly (keyof GrilledSpec)[];
 /** One structured objection from the adversary review. */
 export interface ReviewFinding {
     /** How much the finding threatens the delivery claim. */

package/lib/domain/vocabulary.js

@@ -5,6 +5,10 @@
  *
  * @module dsh-doublecheck/domain/vocabulary
  */
+/** All six spec fields, in declaration order. */
+export const SPEC_FIELD_NAMES = [
+    'goal', 'scope', 'acceptanceCriteria', 'failureModes', 'priorities', 'nonGoals',
+];
 /** All verify dimensions, in spec order. */
 export const VERIFY_DIMENSIONS = [
     'goal',

package/lib/events.d.ts

@@ -15,13 +15,15 @@
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { Session, SessionEventMap } from '@deepseek-ai/dsh-session';
 import type { GrilledSpec, ReviewFinding, ReviewVerdict, ReportVerdict, VerifyCheck } from './domain/vocabulary.ts';
+import type { GateState, GateVerdict } from './domain/gate.ts';
 export type { GrilledSpec, ReviewFinding, ReviewVerdict, ReportVerdict, VerifyCheck } from './domain/vocabulary.ts';
+export type { GateState } from './domain/gate.ts';
 /** Guard enforcement strength. */
 export type GuardIntensity = 'remind' | 'warn' | 'block';
 /** Which discipline gate produced a guard reaction. */
-export type GuardGate = 'grill' | 'tdd' | 'delivery';
+export type GuardGate = 'grill' | 'tdd' | 'delivery' | 'gate';
 /** Policy outcome of one guard reaction. */
-export type GuardVerdict = 'reminded' | 'held' | 'denied' | 'green-pending' | 'report-expected';
+export type GuardVerdict = 'reminded' | 'held' | 'denied' | 'green-pending' | 'report-expected' | 'gate-red';
 declare module '@deepseek-ai/dsh-session' {
     interface SessionEventMap {
         /**
@@ -34,6 +36,14 @@ declare module '@deepseek-ai/dsh-session' {
         'doublecheck/state': {
             enabled: boolean;
         };
+        /**
+         * One settled delivery-gate run written by `/gate run`: the full gate
+         * state (checklist statuses, red items, verdict, engine, timestamp).
+         * Audit-safe by construction — counts, ids, and verdicts only — and the
+         * replayable source the `/gate status` panel and the turn-boundary red
+         * notice re-derive from. Rides `ignorable: true` like the state switch.
+         */
+        'doublecheck/gate': GateState;
     }
 }
 /**
@@ -46,6 +56,15 @@ export interface StateAppend {
         ignorable: true;
     }): void;
 }
+/**
+ * `Session.append` narrowed to the `doublecheck/gate` event, with the same
+ * `ignorable: true` envelope marker as the state switch.
+ */
+export interface GateAppend {
+    (type: 'doublecheck/gate', data: SessionEventMap['doublecheck/gate'], options: {
+        ignorable: true;
+    }): void;
+}
 declare module '@deepseek-ai/dsh-llm' {
     interface MessageSourceMap {
         /**
@@ -59,6 +78,17 @@ declare module '@deepseek-ai/dsh-llm' {
             verdict: ReviewVerdict;
             findings: ReviewFinding[];
         };
+        /**
+         * The delivery-gate red notice injected at the turn boundary: the
+         * model-facing text is the short gate notice (role statement first), and
+         * the structured verdict + red count ride this source so the durable
+         * once-semantics and the report folds read them without re-parsing prose.
+         */
+        'doublecheck-gate': {
+            kind: 'doublecheck-gate';
+            verdict: GateVerdict;
+            redCount: number;
+        };
     }
 }
 declare module '@deepseek-ai/cordis' {
@@ -151,5 +181,17 @@ declare module '@deepseek-ai/cordis' {
             path: string | null;
             written: boolean;
         }): void;
+        /**
+         * One delivery-gate run settled: the full gate state the `/gate run`
+         * command derived, after the durable `doublecheck/gate` session event was
+         * appended. Observability only — listeners must not veto or reroute.
+         * @param payload.session - the gated session.
+         * @param payload.state - the settled gate state (redacted by construction).
+         * @mode emit
+         */
+        'doublecheck/gate'(payload: {
+            session: Session;
+            state: GateState;
+        }): void;
     }
 }

package/lib/grill/index.js

@@ -18,7 +18,7 @@ import z from '@deepseek-ai/schemastery';
 import { DEFAULT_MUTATION_TOOLS, DEFAULT_TEST_COMMAND_PATTERNS, DEFAULT_TEST_FILE_PATTERNS, DEFAULT_TEST_TOOL_NAMES, compileDetection, } from "../domain/evidence.js";
 import { SPEC_TOOL_NAME } from "../domain/stages.js";
 import { buildVerifyScript, deriveReportVerdict, foldReportFacts, renderReportMarkdown, VERIFY_META, } from "../domain/report.js";
-import { VERIFY_DIMENSIONS } from "../domain/vocabulary.js";
+import { SPEC_FIELD_NAMES, VERIFY_DIMENSIONS } from "../domain/vocabulary.js";
 import { BundledSkillProvider, PROVIDER_NAME } from "./provider.js";
 export const name = 'doublecheck-grill';
 export const inject = ['skills', 'tools'];
@@ -215,6 +215,13 @@ export function apply(ctx, config) {
                 priorities: args.priorities,
                 nonGoals: args.nonGoals,
             };
+            // Fail fast at the commit: an empty dimension would satisfy the gate
+            // shape while recording an uncheckable contract. The grill must settle
+            // every dimension before the spec counts.
+            const empty = SPEC_FIELD_NAMES.filter(field => spec[field].trim() === '');
+            if (empty.length > 0) {
+                throw new Error(`doublecheck_spec: the spec dimension(s) ${empty.join(', ')} must not be empty; finish the requirements grill before committing the spec`);
+            }
             const outcome = await writeSpecFile(ctx, spec, args.filePath ?? config.specFile, exec);
             if (exec.agent !== undefined) {
                 ctx.emit('doublecheck/spec', { session: exec.agent.session, spec, ...outcome });

package/lib/guard/command.d.ts

@@ -34,6 +34,13 @@ export interface CommandDeps {
     snapshotOf: (session: Session) => Snapshot;
     /** The compiled test-run detection shared with the tdd/adversary gates. */
     detection: TestRunDetection;
+    /**
+     * The effective session switch — the exact reader the gates use (local
+     * override → durable `doublecheck/state` → configured default), so the
+     * command answers consistently with what the gates enforce, including on
+     * rc.6 hosts where the override is process-local.
+     */
+    effectiveEnabled: (session: Session) => boolean;
     /** Whether the host append surface stamps `ignorable` (see {@link hostStampsIgnorable}). */
     stampsIgnorable: () => boolean;
     /** Record a process-local switch override when the durable write is unavailable. */

package/lib/guard/command.js

@@ -16,6 +16,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { Session, SessionId } from '@deepseek-ai/dsh-session';
 import { deriveReportVerdict, foldReportFacts, renderReportMarkdown } from "../domain/report.js";
+import { PROSE } from "./prose.js";
 /**
  * Whether this host's `Session.append` stamps the `ignorable` envelope marker.
  * Detected once per process on a detached probe session: hosts without the
@@ -54,14 +55,11 @@ export function effectiveDoublecheckEnabled(events, fallback) {
     return fallback;
 }
 /** The switch notice injected after `/doublecheck on|off`. */
-function switchNotice(enabled, durable) {
+function switchNotice(enabled, durable, prose) {
     const source = { kind: 'plugin', plugin: 'dsh-doublecheck', form: 'notice', summary: 'doublecheck state' };
-    const scope = durable
-        ? 'for this session'
-        : 'for this process only (this harness build predates the ignorable append surface, so the switch is not durable)';
     const text = enabled
-        ? `Double-check discipline was switched ON ${scope} (changed by the user): the requirements grill, the red/green gates, and the delivery review are active again.`
-        : `Double-check discipline was switched OFF ${scope} (changed by the user): the discipline gates defer to the human approval chain until switched back on.`;
+        ? durable ? prose.switchOnDurable : prose.switchOnLocal
+        : durable ? prose.switchOffDurable : prose.switchOffLocal;
     return createUserMessage({ content: [{ type: 'text', text }], source });
 }
 /**
@@ -70,26 +68,35 @@ function switchNotice(enabled, durable) {
  * @returns the command handler for `ctx.commands.register`.
  */
 export function doublecheckHandler(deps) {
-    const { config, snapshotOf, detection, stampsIgnorable, setLocalOverride } = deps;
+    const { config, snapshotOf, detection, stampsIgnorable, setLocalOverride, effectiveEnabled } = deps;
+    const prose = PROSE[config.language];
     return (invocation) => {
         const agent = invocation.agent;
         if (agent === undefined) {
-            return { kind: 'error', text: '/doublecheck needs an agent session to inspect.' };
+            return { kind: 'error', text: prose.commandNoAgent };
         }
         const session = agent.session;
         const input = invocation.rawInput.trim().toLowerCase();
-        const enabled = effectiveDoublecheckEnabled(session.events, config.enableByDefault);
+        const enabled = effectiveEnabled(session);
         if (input === 'status' || input === '') {
             const snapshot = snapshotOf(session);
             const discipline = snapshot.discipline;
             return {
                 kind: 'success',
-                text: [
-                    `Double-check discipline is ${enabled ? 'ON' : 'OFF'} for this session. (/doublecheck on|off)`,
-                    `Modules: grill=${config.modules.grill ? 'on' : 'off'}, tdd=${config.modules.tdd ? 'on' : 'off'}, adversary=${config.modules.adversary ? 'on' : 'off'} (cordis.yml).`,
-                    `Stage: spec=${discipline.hasSpec ? 'committed' : 'missing'}, tests=${discipline.color}, review=${snapshot.lastReviewSeq >= 0 ? 'on record' : 'not run'}.`,
-                    'Usage: /doublecheck status|report|on|off',
-                ].join('\n'),
+                text: prose.commandStatus({
+                    enabled,
+                    defaultEnabled: config.enableByDefault,
+                    modules: config.modules,
+                    intensity: config.intensity,
+                    remindOnce: config.remindOnce,
+                    hasSpec: discipline.hasSpec,
+                    color: discipline.color,
+                    reviewed: snapshot.lastReviewSeq >= 0,
+                    editCount: discipline.editCount,
+                    gate: snapshot.lastGate === null
+                        ? null
+                        : { verdict: snapshot.lastGate.verdict, redCount: snapshot.lastGate.redCount },
+                }),
             };
         }
         if (input === 'report') {
@@ -104,11 +111,11 @@ export function doublecheckHandler(deps) {
             return { kind: 'success', text: renderReportMarkdown(report) };
         }
         if (input !== 'on' && input !== 'off') {
-            return { kind: 'error', text: `Unknown /doublecheck argument "${invocation.rawInput.trim()}". Usage: /doublecheck status|report|on|off` };
+            return { kind: 'error', text: prose.commandUnknown(invocation.rawInput.trim()) };
         }
         const target = input === 'on';
         if (enabled === target) {
-            return { kind: 'success', text: `Double-check discipline is already ${input.toUpperCase()} for this session.` };
+            return { kind: 'success', text: target ? prose.commandAlreadyOn : prose.commandAlreadyOff };
         }
         // Adaptive durable write: only hosts that stamp `ignorable` may write the
         // state event; on rc.6 the options bag is ignored and an unmarked foreign
@@ -121,12 +128,12 @@ export function doublecheckHandler(deps) {
         else {
             setLocalOverride(session, target);
         }
-        agent.inject(switchNotice(target, durable));
+        agent.inject(switchNotice(target, durable, prose));
         return {
             kind: 'success',
-            text: durable
-                ? `Double-check discipline ${input.toUpperCase()} for this session.`
-                : `Double-check discipline ${input.toUpperCase()} for this process only (not durable on this harness).`,
+            text: target
+                ? durable ? prose.commandOnDurable : prose.commandOnLocal
+                : durable ? prose.commandOffDurable : prose.commandOffLocal,
         };
     };
 }

package/lib/guard/gate.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The delivery gate runner: orchestrates the four-phase quality checklist
+ * over one session's durable evidence and settles the deliverable/rework
+ * decision.
+ *
+ * - **requirements** + **tests** — deterministic folds of the session log
+ *   (no model calls): the key-question checklist against the committed
+ *   spec, and the test-run/coverage evidence.
+ * - **consistency** — a local forked reviewer audits the diff ↔ requirement
+ *   mapping (every edit must serve a spec dimension).
+ * - **review** — the delivery conclusion. With `engine: auto`, the
+ *   dsh-auto-review engine's durable verdict records (`autoReview/verdict` /
+ *   `autoReview/rejection`) are the evidence; when the engine is not
+ *   installed or has no records this session, the phase degrades to the
+ *   local forked reviewer and says so. `engine: local` always uses the
+ *   local reviewer. The gate never synthesizes approval requests: that
+ *   chain may reach a human.
+ *
+ * Everything a run settles is audit-safe: counts, ids, verdicts, and
+ * redacted findings only. The settled state rides the durable
+ * `doublecheck/gate` session event (replay IS the state), the workspace
+ * `gate-report.md`, and the `/gate run` command result.
+ *
+ * @module dsh-doublecheck/guard/gate
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type Schema from '@deepseek-ai/schemastery';
+import type { TestRunDetection } from '../domain/evidence.ts';
+import { type GateQuestion, type GateState, type GateVerdict } from '../domain/gate.ts';
+import type { GuardProse, ProseLanguage } from './prose.ts';
+/** The reviewer knobs shared by the consistency and review phases. */
+export interface GateReviewerConfig {
+    enabled: boolean;
+    /** Subagent provider name the local reviewer runs on (default `fork`). */
+    provider: string;
+    /** Model route for the local reviewer; null means the main model reviews. */
+    model: string | null;
+    /** Tools the local reviewer may call (read-only by default). */
+    tools: string[];
+    /** Hard time budget for one local reviewer run. */
+    timeoutMs: number;
+    /** Maximum structured findings per phase. */
+    maxFindings: number;
+}
+/** The delivery-gate configuration block of the guard row. */
+export interface GateConfig {
+    /** Master switch for the gate panel and the turn-boundary red notice. */
+    enabled: boolean;
+    /** Suggest re-opening in plan mode when the verdict is rework. */
+    planSuggestion: boolean;
+    /** Workspace file (relative to the session cwd) receiving the gate report. */
+    reportFile: string;
+    /** The requirements-interrogation phase. */
+    requirements: {
+        enabled: boolean;
+        /** The configurable key-question checklist. */
+        checklist: GateQuestion[];
+        /** Minimum required questions that must be confirmed for the phase to pass. */
+        minConfirmed: number;
+        /** Tool name whose calls count as user interrogation evidence. */
+        interrogateTool: string;
+    };
+    /** The test-evidence phase. */
+    tests: {
+        enabled: boolean;
+        /** Require a passing test run as the latest evidence. */
+        requirePassingRun: boolean;
+        /** Failing runs after the latest green allowed before the gate turns red. */
+        allowFailingRuns: number;
+        /** Require coverage evidence in the test output. */
+        requireCoverage: boolean;
+        /** Minimum coverage percentage when coverage is required. */
+        minCoveragePct: number;
+        /** Regex (one capture group) parsing a coverage percentage from test output. */
+        coveragePattern: string;
+    };
+    /** The implementation-consistency phase (local forked reviewer). */
+    consistency: GateReviewerConfig;
+    /** The review-conclusion phase (engine verdict records + local degrade). */
+    review: GateReviewerConfig & {
+        /** `auto` = dsh-auto-review verdict records when present, else local. */
+        engine: 'auto' | 'local';
+    };
+}
+/** The default gate configuration: every phase on, the six key questions required. */
+export declare const DEFAULT_GATE_CONFIG: GateConfig;
+/** The delivery-gate configuration schema (the pluggable checklist + knobs). */
+export declare const GateConfigSchema: Schema<GateConfig>;
+/**
+ * Validate the gate configuration fail-loud: checklist ids unique and
+ * non-empty, valid spec-dimension bindings, bounded thresholds, compilable
+ * coverage regex, and sound reviewer knobs. A bad gate config must not
+ * silently produce an uncheckable checklist.
+ * @param gate - the gate config block.
+ */
+export declare function validateGateConfig(gate: GateConfig): void;
+/**
+ * Run the full delivery gate over the agent's session and settle the state.
+ * The deterministic phases fold first; the two reviewer phases run in
+ * parallel. Failures degrade to honest skip notices, never to throws.
+ * @param ctx - plugin context (subagents, commands, fs seams).
+ * @param config - the gate configuration.
+ * @param detection - the compiled test-run detection knobs.
+ * @param agent - the gated agent.
+ * @param signal - the caller's cancellation signal.
+ * @param language - prose language for the reviewer tasks.
+ * @returns the settled gate state.
+ */
+export declare function runGate(ctx: Context, config: GateConfig, detection: TestRunDetection, agent: Agent, signal: AbortSignal, language: ProseLanguage): Promise<GateState>;
+/**
+ * Settle one gate run's side effects: the durable `doublecheck/gate` session
+ * event (when the host stamps `ignorable`), the observability announcement,
+ * and the workspace `gate-report.md` copy. Failures of the file write never
+ * fail the run — the command result and the durable event remain.
+ * @param ctx - plugin context.
+ * @param config - the gate configuration.
+ * @param state - the settled gate state.
+ * @param agent - the gated agent.
+ * @param signal - the caller's cancellation signal.
+ * @param stampsIgnorable - whether the host stamps the `ignorable` marker.
+ */
+export declare function settleGate(ctx: Context, config: GateConfig, state: GateState, agent: Agent, signal: AbortSignal, stampsIgnorable: boolean): Promise<void>;
+/** The closures the `/gate` command reads; all live inside the guard's `apply` scope. */
+export interface GateCommandDeps {
+    config: GateConfig;
+    detection: TestRunDetection;
+    prose: GuardProse;
+    /** Runs the full gate and returns the settled state. */
+    runGate: (agent: Agent, signal: AbortSignal) => Promise<GateState>;
+    /** Settles the durable append, the announcement, and the workspace file. */
+    settleGate: (state: GateState, agent: Agent, signal: AbortSignal) => Promise<void>;
+    /** Whether the host stamps the `ignorable` marker (the durable write gate). */
+    stampsIgnorable: () => boolean;
+    /** The optional plan-mode service (weak seam: `ctx.get('planMode')`). */
+    planMode?: {
+        get(agent: Agent): {
+            active?: boolean;
+        } | undefined;
+    };
+}
+/**
+ * The `/gate` command handler: `status` renders the live checklist progress
+ * plus the latest settled run; `run` settles the full gate and returns the
+ * PR-ready markdown report; `config` renders the effective checklist.
+ * @param deps - the guard closures the handler reads.
+ * @returns the command handler for `ctx.commands.register`.
+ */
+export declare function gateHandler(deps: GateCommandDeps): (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+/**
+ * The injected gate-red notice message: short model-facing prose (role
+ * statement first) with the structured verdict and red count riding the
+ * durable `doublecheck-gate` message source, so the durable once-semantics
+ * and the report folds read the record without re-parsing the prose.
+ * @param verdict - the settled verdict.
+ * @param redCount - the red-item count.
+ * @param text - the model-facing notice text.
+ * @returns the injection-ready user message.
+ */
+export declare function gateInjection(verdict: GateVerdict, redCount: number, text: string): UserMessage;
+/**
+ * Render the effective gate configuration as markdown — the `/gate config`
+ * output: the pluggable checklist, the thresholds, and the reviewer knobs.
+ * Configuration contains no secrets by construction; nothing is redacted.
+ * @param config - the gate configuration.
+ * @returns the configuration document.
+ */
+export declare function renderGateConfigMarkdown(config: GateConfig): string;