dsh-doublecheck 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to dsh-doublecheck are recorded here, newest first.
 
+## [0.9.0] - 2026-08-26
+
+### Added
+
+- **Headless CI gate report (JSON/SARIF).** `/gate run` now also writes a `gate-report.json` next to `gate-report.md` — the same settled `GateState` as lossless JSON. The new `doublecheck-gate` CLI serializes that state to JSON or SARIF 2.1.0 for GitHub Actions PR comments/status checks (`doublecheck-gate --format json|sarif --input gate-report.json`), exiting `0` on `deliverable` and `1` on `rework`. The CLI never re-runs the four-phase gate or the evidence folds — it only serializes the already-settled state.
+
 ## [0.8.0] - 2026-08-23
 
 ### Added

package/README.es.md

@@ -192,6 +192,19 @@ Las luces rojas son comprobaciones fallidas (un spec ausente, una última ejecuc
 - counts, ids, and verdicts only: no file contents or session text are embedded, and recognized secrets are redacted.
 ````
 
+## Salida de CI
+
+`/gate run` también escribe un `gate-report.json` (el mismo estado asentado que el JSON sin pérdida, junto a `gate-report.md`). El CLI `doublecheck-gate` convierte ese archivo en salida legible por máquina para GitHub Actions:
+
+```sh
+# JSON (comentario de PR / payload de estado)
+doublecheck-gate --format json --input gate-report.json
+# SARIF 2.1.0 (subida de code-scanning / verificación de estado)
+doublecheck-gate --format sarif < gate-report.json
+```
+
+El CLI solo serializa el `GateState` ya asentado — nunca vuelve a ejecutar la puerta de cuatro fases ni los pliegues de evidencia. Su código de salida mapea el veredicto: `0` = entregable, `1` = retrabajo, `2` = error de uso/análisis.
+
 ## Permisos y datos
 
 - **Lee**: el registro de sesión (`tool/call` / `tool/result` / `tool/code-dispatch`, fuentes `user/message` inyectadas y los registros de veredicto ajenos `autoReview/*`) solo en proceso; el estado opcional del servicio de modo plan.

package/README.hi.md

@@ -192,6 +192,19 @@ dsh --profile web --dump-config | grep -E -A3 'id: doublecheck-(grill|guard)'
 - counts, ids, and verdicts only: no file contents or session text are embedded, and recognized secrets are redacted.
 ````
 
+## CI आउटपुट
+
+`/gate run` एक `gate-report.json` भी लिखता है (दोषरहित JSON जैसी ही स्थापित स्थिति, `gate-report.md` के पास)। `doublecheck-gate` CLI उस फ़ाइल को GitHub Actions के लिए मशीन-पठनीय आउटपुट में बदलता है:
+
+```sh
+# JSON (PR टिप्पणी / स्थिति पेलोड)
+doublecheck-gate --format json --input gate-report.json
+# SARIF 2.1.0 (code-scanning अपलोड / स्थिति जाँच)
+doublecheck-gate --format sarif < gate-report.json
+```
+
+CLI केवल पहले से स्थापित `GateState` को क्रमबद्ध करता है — यह कभी चार-चरणीय द्वार या साक्ष्य तहों को दोबारा नहीं चलाता। इसका निकास कोड निर्णय को मैप करता है: `0` = डिलीवर करने योग्य, `1` = पुनः कार्य, `2` = उपयोग/पार्स त्रुटि।
+
 ## अनुमतियाँ और डेटा
 
 - **पढ़ता है**: सत्र लॉग (`tool/call` / `tool/result` / `tool/code-dispatch`, इंजेक्ट किए गए `user/message` स्रोत, और बाहरी `autoReview/*` निर्णय रिकॉर्ड) केवल प्रक्रिया के भीतर; वैकल्पिक प्लान-मोड सेवा स्थिति।

package/README.md

@@ -193,10 +193,23 @@ Red lights are failed checks (a missing spec, a failing latest run, coverage bel
 - counts, ids, and verdicts only: no file contents or session text are embedded, and recognized secrets are redacted.
 ````
 
+## CI output
+
+`/gate run` also writes a `gate-report.json` (the same settled state as lossless JSON, next to `gate-report.md`). The `doublecheck-gate` CLI turns that file into machine-readable output for GitHub Actions:
+
+```sh
+# JSON (PR comment / status payload)
+doublecheck-gate --format json --input gate-report.json
+# SARIF 2.1.0 (code-scanning upload / status check)
+doublecheck-gate --format sarif < gate-report.json
+```
+
+The CLI only serializes the already-settled `GateState` — it never re-runs the four-phase gate or the evidence folds. Its exit code maps the verdict: `0` = deliverable, `1` = rework, `2` = usage/parse error.
+
 ## Permissions & data
 
 - **Reads**: the session log (`tool/call` / `tool/result` / `tool/code-dispatch`, injected `user/message` sources, and the foreign `autoReview/*` verdict records) in-process only; the optional plan-mode service state.
-- **Writes**: `doublecheck-spec.md`, `doublecheck-report.md`, and `gate-report.md` in the session workspace (paths configurable) through the `ctx.fs` seam; the durable `doublecheck/state` and `doublecheck/gate` session events.
+- **Writes**: `doublecheck-spec.md`, `doublecheck-report.md`, `gate-report.md`, and `gate-report.json` in the session workspace (paths configurable) through the `ctx.fs` seam; the durable `doublecheck/state` and `doublecheck/gate` session events.
 - **Model calls**: the gate's consistency and local-review phases (one subagent each per `/gate run`), the optional adversary review, and the `doublecheck_report` verification workflow start subagent runs; nothing else calls a model or the network.
 - **Never touched**: credentials, environment variables, or any file outside the session workspace. The workshop manifest declares `filesystem:read` and `filesystem:write` only. Gate reports carry counts, ids, and verdicts only; recognized secrets in reviewer texts are redacted before storage or display.
 

package/README.pt.md

@@ -192,6 +192,19 @@ As luzes vermelhas são verificações que falharam (um spec ausente, uma últim
 - counts, ids, and verdicts only: no file contents or session text are embedded, and recognized secrets are redacted.
 ````
 
+## Saída do CI
+
+`/gate run` também grava um `gate-report.json` (o mesmo estado assentado que o JSON sem perda, ao lado de `gate-report.md`). O CLI `doublecheck-gate` converte esse arquivo em saída legível por máquina para o GitHub Actions:
+
+```sh
+# JSON (comentário de PR / payload de status)
+doublecheck-gate --format json --input gate-report.json
+# SARIF 2.1.0 (upload de code-scanning / verificação de status)
+doublecheck-gate --format sarif < gate-report.json
+```
+
+O CLI apenas serializa o `GateState` já assentado — nunca reexecuta a porta de quatro fases nem as dobras de evidência. Seu código de saída mapeia o veredicto: `0` = entregável, `1` = retrabalho, `2` = erro de uso/análise.
+
 ## Permissões e dados
 
 - **Lê**: o registro de sessão (`tool/call` / `tool/result` / `tool/code-dispatch`, fontes `user/message` injetadas e os registros de veredicto alheios `autoReview/*`) somente em processo; o estado opcional do serviço de modo plano.

package/README.zh.md

@@ -192,6 +192,19 @@ dsh --profile web --dump-config | grep -E -A3 'id: doublecheck-(grill|guard)'
 - counts, ids, and verdicts only: no file contents or session text are embedded, and recognized secrets are redacted.
 ````
 
+## CI 输出
+
+`/gate run` 还会写一个 `gate-report.json`（与无损 JSON 相同的已定状态，位于 `gate-report.md` 旁边）。`doublecheck-gate` CLI 把该文件转成可供 GitHub Actions 使用的机器可读输出：
+
+```sh
+# JSON（PR 评论 / 状态载荷）
+doublecheck-gate --format json --input gate-report.json
+# SARIF 2.1.0（code-scanning 上传 / 状态检查）
+doublecheck-gate --format sarif < gate-report.json
+```
+
+CLI 只序列化已定的 `GateState` —— 它从不重新运行四阶段门禁或证据折叠。其退出码映射裁决：`0` = 可交付，`1` = 返工，`2` = 用法/解析错误。
+
 ## 权限与数据
 
 - **读取**：仅进程内读取会话日志（`tool/call` / `tool/result` / `tool/code-dispatch`、注入的 `user/message` 来源，以及外部的 `autoReview/*` 裁决记录）；可选的计划模式服务状态。

package/lib/ci.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Headless gate-report CLI for CI (`doublecheck-gate`).
+ *
+ * Consumes a serialized {@link GateState} (the JSON the gate settles and
+ * writes next to `gate-report.md`) and emits a machine-readable report for a
+ * GH Actions PR comment or status check. It does NOT re-run the four-phase
+ * gate — it only serializes the already-settled state — so the gate runner
+ * and the evidence folds stay exactly as they are.
+ *
+ * Usage:
+ *   doublecheck-gate --format json --input gate-report.json
+ *   doublecheck-gate --format sarif < gate-report.json
+ *
+ * Exit code: 0 = deliverable, 1 = rework, 2 = usage/parse error.
+ *
+ * @module dsh-doublecheck/ci
+ */
+export {};

package/lib/ci.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Headless gate-report CLI for CI (`doublecheck-gate`).
+ *
+ * Consumes a serialized {@link GateState} (the JSON the gate settles and
+ * writes next to `gate-report.md`) and emits a machine-readable report for a
+ * GH Actions PR comment or status check. It does NOT re-run the four-phase
+ * gate — it only serializes the already-settled state — so the gate runner
+ * and the evidence folds stay exactly as they are.
+ *
+ * Usage:
+ *   doublecheck-gate --format json --input gate-report.json
+ *   doublecheck-gate --format sarif < gate-report.json
+ *
+ * Exit code: 0 = deliverable, 1 = rework, 2 = usage/parse error.
+ *
+ * @module dsh-doublecheck/ci
+ */
+import { readFileSync } from 'node:fs';
+import { renderGateReportJson, renderGateReportSarif } from "./domain/gate.js";
+/** Parse CLI arguments into `{ format, input }`. */
+function parseArgs(argv) {
+    let format = 'json';
+    let input = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--format' || arg === '-f') {
+            const next = argv[index + 1];
+            if (next !== 'json' && next !== 'sarif')
+                throw new Error(`--format must be json or sarif, got ${JSON.stringify(next)}`);
+            format = next;
+            index += 1;
+        }
+        else if (arg === '--input' || arg === '-i') {
+            input = argv[index + 1] ?? null;
+            if (input === null)
+                throw new Error('--input requires a file path');
+            index += 1;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            throw new Error('usage: doublecheck-gate [--format json|sarif] [--input <file>]');
+        }
+        else if (!arg.startsWith('-')) {
+            input = arg;
+        }
+        else {
+            throw new Error(`unknown argument ${JSON.stringify(arg)}`);
+        }
+    }
+    return { format, input };
+}
+/** Read the gate-state JSON from the input file or stdin (fd 0). */
+function readState(input) {
+    const raw = input !== null ? readFileSync(input, 'utf8') : readFileSync(0, 'utf8');
+    return JSON.parse(raw);
+}
+/** Render and print the report, returning the process exit code. */
+function main(argv) {
+    let format;
+    let input;
+    try {
+        ;
+        ({ format, input } = parseArgs(argv));
+        const state = readState(input);
+        process.stdout.write((format === 'sarif' ? renderGateReportSarif : renderGateReportJson)(state) + '\n');
+        return state.verdict === 'rework' ? 1 : 0;
+    }
+    catch (error) {
+        process.stderr.write(`doublecheck-gate: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}
+process.exitCode = main(process.argv.slice(2));

package/lib/domain/gate.d.ts

@@ -322,3 +322,50 @@ export declare function renderGateReportMarkdown(state: GateState, planSuggestio
 export declare function renderPhaseMarkdown(result: GatePhaseResult): string[];
 /** Human-readable phase headings (stable English audit ids). */
 export declare function phaseLabel(phase: GatePhase): string;
+/**
+ * The machine-readable CI report derived from a settled gate state. Lossless
+ * JSON over the same counts/ids/verdicts the markdown report carries — no
+ * session text or file contents — so a GH Actions step can consume it for a
+ * PR comment or status check. The four-phase runner and the evidence folds
+ * are unchanged; this is a pure serialization of their settled output.
+ */
+export interface CiReport {
+    readonly schemaVersion: 1;
+    readonly tool: 'dsh-doublecheck';
+    readonly verdict: GateVerdict;
+    /** Convenience boolean: true when the delivery may proceed. */
+    readonly deliverable: boolean;
+    readonly reviewEngine: GateReviewEngine;
+    readonly at: string;
+    /** Number of failing (red) checks across enabled phases. */
+    readonly redChecks: number;
+    readonly phases: Array<{
+        readonly phase: GatePhase;
+        readonly enabled: boolean;
+        readonly status: GateCheckStatus;
+        readonly checks: Array<{
+            readonly id: string;
+            readonly label: string;
+            readonly status: GateCheckStatus;
+            readonly summary: string;
+            readonly suggestion: string;
+        }>;
+    }>;
+}
+/** Build the JSON-safe CI report from a settled gate state. */
+export declare function buildCiReport(state: GateState): CiReport;
+/**
+ * Render the settled gate state as headless JSON for CI (`--ci` output).
+ * @param state - the settled gate state.
+ * @returns the pretty-printed JSON report.
+ */
+export declare function renderGateReportJson(state: GateState): string;
+/**
+ * Render the settled gate state as a SARIF 2.1.0 document for CI
+ * (GitHub code-scanning / status checks). Each failing check is an `error`
+ * result and each warning is a `warning` result; passing/skipped/pending
+ * checks are declared as rules but produce no result.
+ * @param state - the settled gate state.
+ * @returns the pretty-printed SARIF document.
+ */
+export declare function renderGateReportSarif(state: GateState): string;

package/lib/domain/gate.js

@@ -750,3 +750,87 @@ export function phaseLabel(phase) {
         case 'review': return 'Review conclusion';
     }
 }
+/** Build the JSON-safe CI report from a settled gate state. */
+export function buildCiReport(state) {
+    return {
+        schemaVersion: 1,
+        tool: 'dsh-doublecheck',
+        verdict: state.verdict,
+        deliverable: state.verdict === 'deliverable',
+        reviewEngine: state.reviewEngine,
+        at: state.at,
+        redChecks: countRedChecks(Object.values(state.phases)),
+        phases: GATE_PHASES.map(phase => {
+            const result = state.phases[phase];
+            return {
+                phase,
+                enabled: result?.enabled ?? false,
+                status: result?.status ?? 'pending',
+                checks: (result?.checks ?? []).map(check => ({
+                    id: check.id,
+                    label: check.label,
+                    status: check.status,
+                    summary: check.summary,
+                    suggestion: check.suggestion,
+                })),
+            };
+        }),
+    };
+}
+/**
+ * Render the settled gate state as headless JSON for CI (`--ci` output).
+ * @param state - the settled gate state.
+ * @returns the pretty-printed JSON report.
+ */
+export function renderGateReportJson(state) {
+    return JSON.stringify(buildCiReport(state), null, 2);
+}
+/**
+ * Render the settled gate state as a SARIF 2.1.0 document for CI
+ * (GitHub code-scanning / status checks). Each failing check is an `error`
+ * result and each warning is a `warning` result; passing/skipped/pending
+ * checks are declared as rules but produce no result.
+ * @param state - the settled gate state.
+ * @returns the pretty-printed SARIF document.
+ */
+export function renderGateReportSarif(state) {
+    const rules = [];
+    const results = [];
+    for (const phase of GATE_PHASES) {
+        const result = state.phases[phase];
+        if (result === undefined || !result.enabled)
+            continue;
+        for (const check of result.checks) {
+            const ruleId = `doublecheck/${phase}/${check.id}`;
+            rules.push({ id: ruleId, shortDescription: { text: `${phaseLabel(phase)} — ${check.label}` } });
+            if (check.status === 'pass' || check.status === 'skip' || check.status === 'pending')
+                continue;
+            results.push({
+                ruleId,
+                level: check.status === 'fail' ? 'error' : 'warning',
+                message: { text: check.suggestion !== '' ? `${check.summary} — rework: ${check.suggestion}` : check.summary },
+            });
+        }
+    }
+    const sarif = {
+        version: '2.1.0',
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [{
+                tool: {
+                    driver: {
+                        name: 'dsh-doublecheck',
+                        informationUri: 'https://github.com/PerryLink/dsh-doublecheck',
+                        rules,
+                    },
+                },
+                properties: {
+                    verdict: state.verdict,
+                    deliverable: state.verdict === 'deliverable',
+                    reviewEngine: state.reviewEngine,
+                    at: state.at,
+                },
+                results,
+            }],
+    };
+    return JSON.stringify(sarif, null, 2);
+}

package/lib/guard/gate.js

@@ -25,7 +25,7 @@
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import z from '@deepseek-ai/schemastery';
-import { attachEvalChecks, countRedChecks, DEFAULT_COVERAGE_PATTERN, DEFAULT_EVAL_REPORTS_CONFIG, DEFAULT_GATE_QUESTIONS, deriveGateVerdict, evaluateConsistency, evaluateRequirements, evaluateReview, evaluateTests, foldAutoReviewEvidence, foldRequirementsEvidence, foldTestEvidence, GATE_FINDINGS_SCHEMA, parseEvalReport, renderGateReportMarkdown, renderPhaseMarkdown, skippedPhase, } from "../domain/gate.js";
+import { attachEvalChecks, countRedChecks, DEFAULT_COVERAGE_PATTERN, DEFAULT_EVAL_REPORTS_CONFIG, DEFAULT_GATE_QUESTIONS, deriveGateVerdict, evaluateConsistency, evaluateRequirements, evaluateReview, evaluateTests, foldAutoReviewEvidence, foldRequirementsEvidence, foldTestEvidence, GATE_FINDINGS_SCHEMA, parseEvalReport, renderGateReportJson, renderGateReportMarkdown, renderPhaseMarkdown, skippedPhase, } from "../domain/gate.js";
 import { sortFindings } from "./review.js";
 import { PROSE } from "./prose.js";
 /** The default gate configuration: every phase on, the six key questions required. */
@@ -396,19 +396,30 @@ async function writeGateFile(ctx, filePath, state, agent, signal) {
     const fs = ctx.get('fs');
     if (fs === undefined)
         return;
-    let target;
     try {
-        target = await fs.resolve(filePath, {
+        const markdownTarget = await fs.resolve(filePath, {
             ...agent.session.header.cwd !== undefined ? { cwd: agent.session.header.cwd } : {},
             signal,
         });
-        await fs.writeText(target, renderGateReportMarkdown(state, true), undefined, signal);
+        await fs.writeText(markdownTarget, renderGateReportMarkdown(state, true), undefined, signal);
+        // The headless CI copy: the same settled state as JSON, for the
+        // `doublecheck-gate` CLI (PR comment / status checks). Additive output —
+        // the markdown report and the four-phase runner are unchanged.
+        const ciTarget = await fs.resolve(ciReportPath(filePath), {
+            ...agent.session.header.cwd !== undefined ? { cwd: agent.session.header.cwd } : {},
+            signal,
+        });
+        await fs.writeText(ciTarget, renderGateReportJson(state), undefined, signal);
     }
     catch (error) {
         signal.throwIfAborted();
         ctx.logger.debug(`dsh-doublecheck: gate report file write skipped: ${String(error)}`);
     }
 }
+/** Derive the JSON CI-report path from the markdown report path. */
+function ciReportPath(filePath) {
+    return filePath.endsWith('.md') ? `${filePath.slice(0, -3)}.json` : `${filePath}.json`;
+}
 /**
  * Read and fold the dsh-eval report through the filesystem seam. A missing
  * seam, a missing file, malformed JSON, or a wrong document shape all settle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-doublecheck",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Delivery quality gate for DeepSeek Harness: grill the requirements, test the implementation, prove the delivery, and gate the handoff with a deliverable/rework decision.",
   "packageManager": "pnpm@11.7.0",
   "repository": {
@@ -14,6 +14,9 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "bin": {
+    "doublecheck-gate": "lib/ci.js"
+  },
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",