hadara 0.2.0-rc.2 → 0.2.0-rc.3

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.2-blue">
+  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.3-blue">
   <img alt="Node.js" src="https://img.shields.io/badge/node-%3E%3D22-brightgreen">
   <img alt="License" src="https://img.shields.io/badge/license-MIT-lightgrey">
 </p>
@@ -23,10 +23,10 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 The current source checkout targets:
 
 ```text
-hadara@0.2.0-rc.2
+hadara@0.2.0-rc.3
 ```
 
-T-0282 refreshes the npm release-candidate source state for `0.2.0-rc.2` after the init scaffold protocol guidance follow-up. T-0275 published the previous `0.2.0-rc.1` RC after the installed-package recycle fixes.
+T-0287 prepares the source checkout for `0.2.0-rc.3` after the rc2 dogfooding findings and the T-0284 through T-0286 proof reliability hardening. `hadara@0.2.0-rc.3` is a publish candidate until an operator explicitly runs an approval-gated publish capsule. The latest npm-published release candidate remains `hadara@0.2.0-rc.2`.
 
 Current publish boundaries:
 
@@ -35,8 +35,9 @@ Current publish boundaries:
 | npm package | Primary release target. |
 | `hadara@0.1.0-rc.0` | Published first RC. |
 | `hadara@0.2.0-rc.0` | Superseded internal publish candidate after recycle findings. |
-| `hadara@0.2.0-rc.1` | Current published npm RC until rc.2 is operator-published. |
-| `hadara@0.2.0-rc.2` | Current source version and next npm RC target. |
+| `hadara@0.2.0-rc.1` | Previous published npm RC. |
+| `hadara@0.2.0-rc.2` | Current published npm RC. |
+| `hadara@0.2.0-rc.3` | Current source publish candidate; not published by this capsule. |
 | GitHub Release | Secondary target, still approval-gated. |
 | Docker image | Deferred. |
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
@@ -48,7 +49,7 @@ No release command should publish, create a GitHub Release, build Docker images,
 
 Requires Node.js 22.
 
-Install the current RC:
+Install the current published RC:
 
 ```bash
 npm install -g hadara@0.2.0-rc.2
@@ -64,7 +65,7 @@ npx hadara@0.2.0-rc.2 doctor --json
 npx hadara@0.2.0-rc.2 tools list --json
 ```
 
-Previous published RCs: `hadara@0.2.0-rc.1` and `hadara@0.1.0-rc.0` remain available on npm for comparison or rollback, but new installs should use the current RC after the operator publishes it.
+After an operator publishes rc3, use `hadara@0.2.0-rc.3` in the install and npx commands above. Previous published RCs remain available on npm for comparison or rollback.
 
 ## What HADARA Gives You
 
@@ -114,6 +115,9 @@ Evidence and handoff:
 hadara evidence collect --task T-0001 --json
 hadara evidence add-command --task T-0001 --summary "Focused validation passed." --result passed --json
 hadara evidence list --task T-0001 --json
+hadara proof status --task T-0001 --json
+hadara proof explain --task T-0001 --json
+hadara ci gate --mode advisory --task T-0001 --json
 hadara handoff suggest --task T-0001 --json
 ```
 
@@ -151,7 +155,7 @@ hadara task status --task T-XXXX --json
 
 # Do the scoped work.
 
-hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --idempotency-key "command:T-XXXX:check" --json
 
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json

package/dist/cli/ci.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCiCommand = handleCiCommand;
+const args_1 = require("./args");
+const ci_gate_1 = require("../services/ci-gate");
+function handleCiCommand(input) {
+    if (input.args[0] !== 'ci' || input.args[1] !== 'gate')
+        return false;
+    const mode = parseCiGateMode((0, args_1.getStringOption)(input.args, '--mode', 'advisory') ?? 'advisory');
+    const report = (0, ci_gate_1.createCiGateReport)(input.projectRoot, mode, {
+        taskId: (0, args_1.getStringOption)(input.args, '--task'),
+        allowEmpty: (0, args_1.getFlag)(input.args, '--allow-empty')
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(`[HADARA] ci gate ${mode}: ${report.ok ? 'ok' : 'blocked'} | blockers ${report.blockers.length} | warnings ${report.warnings.length}`);
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function parseCiGateMode(value) {
+    if (value === 'advisory' || value === 'strict')
+        return value;
+    throw new Error(`unsupported ci gate mode: ${value}`);
+}

package/dist/cli/evidence-json.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEvidenceCollectReport = createEvidenceCollectReport;
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const evidence_1 = require("../evidence/evidence");
 const task_capsule_1 = require("../task/task-capsule");
@@ -25,19 +24,20 @@ function createEvidenceCollectReport(projectRoot, input) {
             ]
         };
     }
-    let markdownPath;
+    let appendResult;
     try {
-        markdownPath = (0, evidence_1.appendEvidence)(projectRoot, {
+        appendResult = (0, evidence_1.appendEvidenceWithResult)(projectRoot, {
             taskId: input.taskId,
             kind: input.kind,
             path: input.path,
             summary: input.summary,
             result: input.result,
-            visibility: input.visibility
+            visibility: input.visibility,
+            idempotencyKey: input.idempotencyKey
         });
     }
     catch (error) {
-        if (error instanceof workspace_1.WorkspaceFileError || error instanceof evidence_1.EvidenceArtifactPolicyError) {
+        if (error instanceof workspace_1.WorkspaceFileError || error instanceof evidence_1.EvidenceArtifactPolicyError || error instanceof evidence_1.EvidenceAppendLockError) {
             return {
                 schemaVersion: 'hadara.evidence.collect.v1',
                 command: 'evidence.collect',
@@ -53,23 +53,20 @@ function createEvidenceCollectReport(projectRoot, input) {
         }
         throw error;
     }
-    const indexRecord = readLastEvidenceIndexRecord(task.dir);
     return {
         schemaVersion: 'hadara.evidence.collect.v1',
         command: 'evidence.collect',
         ok: true,
         evidence: {
-            ...indexRecord,
-            markdownPath: toPortablePath(node_path_1.default.relative(projectRoot, markdownPath))
+            ...appendResult.evidence,
+            markdownPath: toPortablePath(node_path_1.default.relative(projectRoot, appendResult.markdownPath)),
+            markdownAppended: appendResult.markdownAppended,
+            jsonlAppended: appendResult.jsonlAppended,
+            existing: appendResult.existing
         },
         issues: []
     };
 }
-function readLastEvidenceIndexRecord(taskDir) {
-    const indexPath = node_path_1.default.join(taskDir, 'evidence.jsonl');
-    const lines = node_fs_1.default.readFileSync(indexPath, 'utf8').trim().split(/\r?\n/);
-    return JSON.parse(lines.at(-1) ?? '{}');
-}
 function toPortablePath(value) {
     return value.split(node_path_1.default.sep).join('/');
 }

package/dist/cli/evidence.js

@@ -78,21 +78,28 @@ function handleEvidenceCommand(input) {
         const summary = (0, args_1.getStringOption)(input.args, '--summary') ?? 'Command completed.';
         const result = parseEvidenceResult((0, args_1.getStringOption)(input.args, '--result', 'unknown') ?? 'unknown');
         const visibility = parseEvidenceVisibility((0, args_1.getStringOption)(input.args, '--visibility', 'public') ?? 'public', (0, args_1.getFlag)(input.args, '--private'));
+        const idempotencyKey = (0, args_1.getStringOption)(input.args, '--idempotency-key');
         if (input.jsonOutput) {
             const report = (0, evidence_json_1.createEvidenceCollectReport)(input.projectRoot, {
                 taskId,
                 kind: 'command-log',
                 summary,
                 result,
-                visibility
+                visibility,
+                idempotencyKey
             });
             console.log(JSON.stringify({ ...report, command: 'evidence.add-command' }, null, 2));
             if (!report.ok)
                 process.exitCode = 6;
         }
         else {
-            const filePath = (0, evidence_1.appendEvidence)(input.projectRoot, { taskId, kind: 'command-log', summary, result, visibility });
-            console.log(`[HADARA] Command evidence updated: ${filePath}`);
+            const appendResult = (0, evidence_1.appendEvidenceWithResult)(input.projectRoot, { taskId, kind: 'command-log', summary, result, visibility, idempotencyKey });
+            if (appendResult.existing) {
+                console.log(`[HADARA] Command evidence already exists: ${persistedEvidenceId(appendResult.evidence)}`);
+            }
+            else {
+                console.log(`[HADARA] Command evidence recorded: ${appendResult.markdownPath}`);
+            }
         }
         return true;
     }
@@ -104,6 +111,7 @@ function handleEvidenceCommand(input) {
     const result = parseEvidenceResult((0, args_1.getStringOption)(input.args, '--result', 'unknown') ?? 'unknown');
     const evidenceFile = (0, args_1.getStringOption)(input.args, '--path');
     const visibility = parseEvidenceVisibility((0, args_1.getStringOption)(input.args, '--visibility', 'public') ?? 'public', (0, args_1.getFlag)(input.args, '--private'));
+    const idempotencyKey = (0, args_1.getStringOption)(input.args, '--idempotency-key');
     if (input.jsonOutput) {
         const report = (0, evidence_json_1.createEvidenceCollectReport)(input.projectRoot, {
             taskId,
@@ -111,18 +119,27 @@ function handleEvidenceCommand(input) {
             path: evidenceFile,
             summary,
             result,
-            visibility
+            visibility,
+            idempotencyKey
         });
         console.log(JSON.stringify(report, null, 2));
         if (!report.ok)
             process.exitCode = 6;
     }
     else {
-        const filePath = (0, evidence_1.appendEvidence)(input.projectRoot, { taskId, kind, path: evidenceFile, summary, result, visibility });
-        console.log(`[HADARA] Evidence updated: ${filePath}`);
+        const appendResult = (0, evidence_1.appendEvidenceWithResult)(input.projectRoot, { taskId, kind, path: evidenceFile, summary, result, visibility, idempotencyKey });
+        if (appendResult.existing) {
+            console.log(`[HADARA] Evidence already exists: ${persistedEvidenceId(appendResult.evidence)}`);
+        }
+        else {
+            console.log(`[HADARA] Evidence recorded: ${appendResult.markdownPath}`);
+        }
     }
     return true;
 }
+function persistedEvidenceId(record) {
+    return record.schemaVersion === 'hadara.evidence.v2' && record.id ? record.id : 'evidence.jsonl';
+}
 function parseEvidenceKind(value) {
     if (['test-log', 'command-log', 'diff-summary', 'screenshot', 'note'].includes(value)) {
         return value;

package/dist/cli/init.js

@@ -963,7 +963,7 @@ hadara task status --task T-XXXX --json
 
 # Do the scoped work.
 
-hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --idempotency-key "command:T-XXXX:check" --json
 
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json
@@ -985,7 +985,7 @@ hadara task audit-close --task T-XXXX --json
 |---|---|---|
 | \`task next\` | Read-only | Recommends work; does not create tasks. |
 | \`task status\` | Read-only | \`ok\` means report generation succeeded; readiness is in \`state.ready\`, \`summary.blockers\`, and \`issues\`. |
-| \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands. |
+| \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands; optional \`--idempotency-key\` prevents duplicate same-key records. |
 | \`task ready\` | Read-only | Checks readiness; does not mutate evidence or status docs. |
 | \`task finish\` | Dry-run by default; writes only with \`--execute\` | Bounded to \`TASK.md\` and \`docs/TASK_BOARD.md\`. |
 | \`task close\` | Dry-run by default; writes only with \`--execute\` | Bounded to close evidence append. |
@@ -1010,7 +1010,7 @@ Before running \`task ready\` and \`task close\`, finish all close-source edits:
 1. Do not hand-edit Task Capsule \`evidence.jsonl\`.
 2. Append evidence through HADARA commands so schema, visibility, and artifact-safety checks run consistently.
 3. Record failed or blocked checks honestly. Do not replace them later with optimistic summaries; add newer evidence that explains the fix or residual risk.
-4. Use \`hadara evidence add-command --task <task-id> --summary <text> --result passed|failed|blocked|unknown --json\` for command results when no artifact file is attached.
+4. Use \`hadara evidence add-command --task <task-id> --summary <text> --result passed|failed|blocked|unknown --json\` for command results when no artifact file is attached. Add \`--idempotency-key <key>\` when rerunning the same logical check should report one durable evidence identity instead of appending duplicates.
 5. Use \`hadara evidence lint --task <task-id> --json\` when evidence drift is suspected or before close if evidence files were touched manually by mistake.
 
 ## Session End
@@ -1177,7 +1177,7 @@ hadara task status --task T-XXXX --json
 
 # Do the scoped work.
 
-hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --idempotency-key "command:T-XXXX:check" --json
 
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json
@@ -1210,7 +1210,7 @@ Before close, finish all close-source edits: Task Capsule docs, acceptance/tests
 | \`task next\` | Read-only | Recommends work; does not create tasks. |
 | \`task status\` | Read-only | \`ok\` means report generation succeeded; readiness is in \`state.ready\`, \`summary.blockers\`, and \`issues\`. |
 | \`task create\` | Write | Creates a Draft Task Capsule and Task Board row. It does not imply the task is ready or done. |
-| \`evidence add-command\` | Write | Appends operator-supplied command-log evidence. It does not execute shell commands or capture stdout/stderr. |
+| \`evidence add-command\` | Write | Appends operator-supplied command-log evidence. It does not execute shell commands or capture stdout/stderr; optional \`--idempotency-key\` prevents duplicate same-key records. |
 | \`task finish\` | Dry-run by default; writes only with \`--execute\` | Updates only \`TASK.md\` status bookkeeping and the matching \`docs/TASK_BOARD.md\` row. |
 | \`task ready\` | Read-only | Checks whether the task can satisfy the requested readiness level after finish. |
 | \`task complete\` | Read-only | Summarizes the current completion stage and next command; it does not execute lifecycle writes. |
@@ -1224,7 +1224,7 @@ Before close, finish all close-source edits: Task Capsule docs, acceptance/tests
 - \`task ready\` checks readiness; it does not write evidence or status.
 - \`harness validate\` is a direct diagnostic for Task Capsule structure and done-level gates; it is not a replacement for close evidence.
 - \`task complete\` is a read-only workflow compressor. It may report the next lifecycle command, but it must not execute finish, ready, close, or audit commands.
-- \`evidence add-command\` records an operator-supplied command result; it does not run the command.
+- \`evidence add-command\` records an operator-supplied command result; it does not run the command. \`--idempotency-key\` is optional; when supplied, same-key repeats return the existing record without appending duplicate Markdown or JSONL rows.
 - \`task finish\` may update only the Task Capsule \`TASK.md\` status and matching \`docs/TASK_BOARD.md\` status/path row.
 - \`task close\` may append only close evidence. It must not update status docs, Task Board rows, handoff, Project State, roadmap docs, or arbitrary evidence.
 - After \`task close --execute --json\`, close-source document edits intentionally invalidate the previous close proof. Make those edits before close, or rerun ready/close/audit if the edit is unavoidable.

package/dist/cli/main.js

@@ -62,10 +62,13 @@ Usage:
   hadara task audit-close --task <task-id> [--json]
   hadara task ready --task <task-id> [--level done] [--json]
   hadara evidence collect --task <task-id> [--kind note|test-log|command-log|diff-summary|screenshot] [--path <path>] [--summary <text>] [--result passed|failed|blocked|unknown] [--private|--visibility public|private]
-  hadara evidence add-command --task <task-id> --summary <text> [--result passed|failed|blocked|unknown] [--private|--visibility public|private] [--json]
+  hadara evidence add-command --task <task-id> --summary <text> [--result passed|failed|blocked|unknown] [--idempotency-key <key>] [--private|--visibility public|private] [--json]
   hadara evidence list --task <task-id> [--limit <n>] [--include-private] [--json]
   hadara evidence lint --task <task-id> [--json]
   hadara evidence migrate --task <task-id> --to v2 [--execute --before-hash <hash>] [--json]
+  hadara proof status --task <task-id> [--json]
+  hadara proof explain --task <task-id> [--json]
+  hadara ci gate [--mode advisory|strict] [--task <task-id>] [--allow-empty] [--json]
   hadara debt list [--json]
   hadara debt show <id> [--json]
   hadara protocol doctor [--json]
@@ -150,6 +153,18 @@ async function main(args = process.argv.slice(2)) {
                 return;
             break;
         }
+        case 'proof': {
+            const { handleProofCommand } = await Promise.resolve().then(() => __importStar(require('./proof')));
+            if (handleProofCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
+                return;
+            break;
+        }
+        case 'ci': {
+            const { handleCiCommand } = await Promise.resolve().then(() => __importStar(require('./ci')));
+            if (handleCiCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
+                return;
+            break;
+        }
         case 'tools': {
             const { handleToolsCommand } = await Promise.resolve().then(() => __importStar(require('./tools')));
             if (handleToolsCommand({ args, jsonOutput }))

package/dist/cli/proof.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleProofCommand = handleProofCommand;
+const args_1 = require("./args");
+const proof_status_1 = require("../services/proof-status");
+function handleProofCommand(input) {
+    if (input.args[0] !== 'proof')
+        return false;
+    const sub = input.args[1];
+    if (sub !== 'status' && sub !== 'explain')
+        return false;
+    const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
+    const report = (0, proof_status_1.createProofStatusReport)(input.projectRoot, taskId, sub);
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(`[HADARA] proof ${sub} ${taskId}: ${report.verdict}`);
+        console.log(`freshness: ${report.freshness.status}`);
+        for (const issue of [...report.blockers, ...report.warnings]) {
+            console.log(`[${issue.severity}] ${issue.code}: ${issue.message}`);
+        }
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}

package/dist/evidence/evidence.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EvidenceArtifactPolicyError = void 0;
+exports.EvidenceAppendLockError = exports.EvidenceArtifactPolicyError = void 0;
 exports.persistedEvidenceKind = persistedEvidenceKind;
 exports.persistedEvidenceResult = persistedEvidenceResult;
 exports.persistedEvidencePath = persistedEvidencePath;
@@ -11,6 +11,7 @@ exports.appendEvidence = appendEvidence;
 exports.appendEvidenceWithResult = appendEvidenceWithResult;
 exports.appendEvidenceTextArtifact = appendEvidenceTextArtifact;
 exports.createPublicEvidenceArtifactPolicyReport = createPublicEvidenceArtifactPolicyReport;
+exports.persistedEvidenceIdempotencyKey = persistedEvidenceIdempotencyKey;
 exports.createSessionEvidenceDirs = createSessionEvidenceDirs;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -39,6 +40,14 @@ class EvidenceArtifactPolicyError extends Error {
     }
 }
 exports.EvidenceArtifactPolicyError = EvidenceArtifactPolicyError;
+class EvidenceAppendLockError extends Error {
+    code = 'EVIDENCE_APPEND_LOCK_TIMEOUT';
+    constructor(message) {
+        super(message);
+        this.name = 'EvidenceAppendLockError';
+    }
+}
+exports.EvidenceAppendLockError = EvidenceAppendLockError;
 function appendEvidence(projectRoot, record) {
     return appendEvidenceWithResult(projectRoot, record).markdownPath;
 }
@@ -49,8 +58,14 @@ function appendEvidenceWithResult(projectRoot, record) {
     }
     const time = new Date().toISOString();
     const visibility = record.visibility ?? 'public';
-    const attachedPath = copyPublicEvidenceArtifact({ projectRoot, taskDir, kind: record.kind, sourcePath: record.path, time, visibility });
-    return appendEvidenceRecord({ projectRoot, taskDir, time, record, visibility, attachedPath });
+    return appendEvidenceRecord({
+        projectRoot,
+        taskDir,
+        time,
+        record,
+        visibility,
+        createAttachedPath: () => copyPublicEvidenceArtifact({ projectRoot, taskDir, kind: record.kind, sourcePath: record.path, time, visibility })
+    });
 }
 function appendEvidenceTextArtifact(projectRoot, record, artifact, options = {}) {
     const taskDir = findTaskDir(projectRoot, record.taskId);
@@ -59,18 +74,24 @@ function appendEvidenceTextArtifact(projectRoot, record, artifact, options = {})
     }
     const time = new Date().toISOString();
     const visibility = record.visibility ?? 'public';
-    const attachedPath = visibility === 'public'
-        ? writePublicEvidenceTextArtifact({
-            taskDir,
-            kind: record.kind,
-            time,
-            fileName: artifact.fileName,
-            content: artifact.content,
-            artifactDirName: artifact.artifactDirName,
-            policyOptions: options
-        })
-        : undefined;
-    return appendEvidenceRecord({ projectRoot, taskDir, time, record, visibility, attachedPath });
+    return appendEvidenceRecord({
+        projectRoot,
+        taskDir,
+        time,
+        record,
+        visibility,
+        createAttachedPath: () => visibility === 'public'
+            ? writePublicEvidenceTextArtifact({
+                taskDir,
+                kind: record.kind,
+                time,
+                fileName: artifact.fileName,
+                content: artifact.content,
+                artifactDirName: artifact.artifactDirName,
+                policyOptions: options
+            })
+            : undefined
+    });
 }
 function createPublicEvidenceArtifactPolicyReport(content, options = {}) {
     const redaction = (0, redaction_1.createRedactionReport)(content, { patterns: options.redactionPatterns });
@@ -95,41 +116,128 @@ function createPublicEvidenceArtifactPolicyReport(content, options = {}) {
 function appendEvidenceIndex(taskDir, record) {
     node_fs_1.default.appendFileSync(node_path_1.default.join(taskDir, 'evidence.jsonl'), `${JSON.stringify(record)}\n`, 'utf8');
 }
+function readEvidenceIndex(taskDir) {
+    const indexPath = node_path_1.default.join(taskDir, 'evidence.jsonl');
+    if (!node_fs_1.default.existsSync(indexPath))
+        return [];
+    return node_fs_1.default
+        .readFileSync(indexPath, 'utf8')
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== '')
+        .map((line) => JSON.parse(line));
+}
+function persistedEvidenceIdempotencyKey(record) {
+    if (record.schemaVersion !== 'hadara.evidence.v2')
+        return undefined;
+    if (record.idempotencyKey)
+        return record.idempotencyKey;
+    const tag = record.tags.find((item) => item.startsWith('idempotency:'));
+    return tag ? tag.replace(/^idempotency:/, '') : undefined;
+}
+function withEvidenceAppendLock(projectRoot, taskId, fn) {
+    const lockRoot = node_path_1.default.join(projectRoot, '.hadara', 'local', 'locks', 'evidence');
+    (0, fs_1.ensureDir)(lockRoot);
+    const lockDir = node_path_1.default.join(lockRoot, `${safeFilePart(taskId)}.lock`);
+    const lockPortablePath = toPortablePath(node_path_1.default.relative(projectRoot, lockDir));
+    const started = Date.now();
+    const timeoutMs = 5000;
+    while (true) {
+        try {
+            node_fs_1.default.mkdirSync(lockDir);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() - started >= timeoutMs) {
+                throw new EvidenceAppendLockError(`Timed out waiting for the evidence append lock for ${taskId}. Lock directory: ${lockPortablePath}. ` +
+                    `If no HADARA process is writing evidence, the lock is stale (inspect ${lockPortablePath}/lock.json for the owning pid); remove the lock directory and retry.`);
+            }
+            sleepSync(25);
+        }
+    }
+    writeLockMetadata(lockDir, taskId);
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup; later writers fail closed through the timeout.
+        }
+    }
+}
+function writeLockMetadata(lockDir, taskId) {
+    try {
+        node_fs_1.default.writeFileSync(node_path_1.default.join(lockDir, 'lock.json'), `${JSON.stringify({ pid: process.pid, taskId, command: 'evidence.append', createdAt: new Date().toISOString() })}\n`, 'utf8');
+    }
+    catch {
+        // Lock ownership is held by the directory; metadata is a best-effort diagnostic aid only.
+    }
+}
+function sleepSync(ms) {
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(signal, 0, 0, ms);
+}
 function appendEvidenceRecord(input) {
     const summary = (0, redaction_1.redactSecrets)(input.record.summary.replace(/\|/g, '/'));
     const markdownPath = node_path_1.default.join(input.taskDir, 'EVIDENCE.md');
-    const rowSummary = input.visibility === 'private' || !input.attachedPath ? summary : `${summary} (${input.attachedPath})`;
-    const jsonlMarker = input.visibility === 'public' && input.attachedPath ? input.attachedPath : 'evidence.jsonl';
-    const row = `| ${input.time} | ${input.record.kind} | ${rowSummary} | ${input.record.result} | ${input.visibility} | ${jsonlMarker} |\n`;
-    if (!node_fs_1.default.existsSync(markdownPath)) {
-        node_fs_1.default.writeFileSync(markdownPath, '# Evidence\n\n| Time | Kind | Summary | Result | Visibility | JSONL |\n|---|---|---|---|---|---|\n', 'utf8');
-    }
-    node_fs_1.default.appendFileSync(markdownPath, row, 'utf8');
-    const evidence = createEvidenceV2Record({
-        time: input.time,
-        taskId: input.record.taskId,
-        kind: input.record.kind,
-        summary,
-        result: input.record.result,
-        visibility: input.visibility,
-        attachedPath: input.attachedPath,
-        tags: input.record.tags,
-        idempotencyKey: input.record.idempotencyKey,
-        actor: input.record.actor
-    });
-    appendEvidenceIndex(input.taskDir, evidence);
-    if (input.visibility === 'private') {
-        (0, private_manifest_1.writePrivateEvidenceManifest)({
-            projectRoot: input.projectRoot,
+    return withEvidenceAppendLock(input.projectRoot, input.record.taskId, () => {
+        const idempotencyKey = input.record.idempotencyKey;
+        if (idempotencyKey) {
+            const existing = readEvidenceIndex(input.taskDir).find((record) => persistedEvidenceIdempotencyKey(record) === idempotencyKey);
+            if (existing) {
+                return {
+                    markdownPath,
+                    evidence: existing,
+                    markdownAppended: false,
+                    jsonlAppended: false,
+                    existing: true
+                };
+            }
+        }
+        const attachedPath = input.createAttachedPath();
+        const rowSummary = input.visibility === 'private' || !attachedPath ? summary : `${summary} (${attachedPath})`;
+        const jsonlMarker = input.visibility === 'public' && attachedPath ? attachedPath : 'evidence.jsonl';
+        const row = `| ${input.time} | ${input.record.kind} | ${rowSummary} | ${input.record.result} | ${input.visibility} | ${jsonlMarker} |\n`;
+        if (!node_fs_1.default.existsSync(markdownPath)) {
+            node_fs_1.default.writeFileSync(markdownPath, '# Evidence\n\n| Time | Kind | Summary | Result | Visibility | JSONL |\n|---|---|---|---|---|---|\n', 'utf8');
+        }
+        node_fs_1.default.appendFileSync(markdownPath, row, 'utf8');
+        const evidence = createEvidenceV2Record({
+            time: input.time,
             taskId: input.record.taskId,
             kind: input.record.kind,
             summary,
             result: input.record.result,
-            sourcePath: input.record.path,
-            time: input.time
+            visibility: input.visibility,
+            attachedPath,
+            tags: input.record.tags,
+            idempotencyKey: input.record.idempotencyKey,
+            actor: input.record.actor
         });
-    }
-    return { markdownPath, evidence };
+        appendEvidenceIndex(input.taskDir, evidence);
+        if (input.visibility === 'private') {
+            (0, private_manifest_1.writePrivateEvidenceManifest)({
+                projectRoot: input.projectRoot,
+                taskId: input.record.taskId,
+                kind: input.record.kind,
+                summary,
+                result: input.record.result,
+                sourcePath: input.record.path,
+                time: input.time
+            });
+        }
+        return {
+            markdownPath,
+            evidence,
+            markdownAppended: true,
+            jsonlAppended: true,
+            existing: false
+        };
+    });
 }
 function createEvidenceV2Record(input) {
     const legacy = {

package/dist/services/ci-gate.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCiGateReport = createCiGateReport;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const proof_status_1 = require("./proof-status");
+const evidence_lint_1 = require("./evidence-lint");
+const protocol_consistency_1 = require("./protocol-consistency");
+const task_capsule_1 = require("../task/task-capsule");
+function createCiGateReport(projectRoot, mode, options = {}) {
+    const allowEmpty = options.allowEmpty ?? false;
+    const tasks = selectTasks(projectRoot, options.taskId);
+    const checks = [];
+    const blockers = [];
+    const warnings = [];
+    applyScopeGuard({ taskId: options.taskId, mode, allowEmpty, taskCount: tasks.length, checks, blockers, warnings });
+    const protocol = options.taskId ? (0, protocol_consistency_1.createTaskProtocolConsistencyReport)(projectRoot, options.taskId) : (0, protocol_consistency_1.createAllProtocolConsistencyReport)(projectRoot);
+    checks.push({
+        id: options.taskId ? `protocol:${options.taskId}` : 'protocol:all',
+        source: 'protocol',
+        ok: protocol.ok,
+        ...(options.taskId ? { taskId: options.taskId } : {}),
+        summary: protocol.ok ? 'Protocol checks passed.' : 'Protocol checks reported issues.'
+    });
+    for (const issue of protocol.issues) {
+        const target = issue.severity === 'error' ? blockers : warnings;
+        target.push({ severity: issue.severity, source: 'protocol', code: issue.code, message: issue.message, path: issue.path });
+    }
+    for (const task of tasks) {
+        const evidence = (0, evidence_lint_1.createEvidenceLintReport)(projectRoot, task.id);
+        checks.push({
+            id: `evidence:${task.id}`,
+            source: 'evidence',
+            ok: evidence.ok,
+            taskId: task.id,
+            summary: evidence.ok ? 'Evidence lint passed.' : 'Evidence lint reported issues.'
+        });
+        for (const issue of evidence.issues) {
+            const target = issue.severity === 'error' ? blockers : warnings;
+            target.push({ severity: issue.severity, source: 'evidence', code: issue.code, message: issue.message, taskId: task.id, path: issue.path });
+        }
+        if (taskLooksDone(task.dir) || options.taskId) {
+            const proof = (0, proof_status_1.createProofStatusReport)(projectRoot, task.id);
+            checks.push(toProofCheck(task.id, proof));
+            for (const issue of proof.blockers)
+                blockers.push({ ...issue, source: 'proof', taskId: task.id });
+            for (const issue of proof.warnings)
+                warnings.push({ ...issue, source: 'proof', taskId: task.id });
+        }
+    }
+    checks.push({
+        id: 'release:deferred',
+        source: 'release',
+        ok: true,
+        summary: 'Release gate aggregation is deferred unless release work is explicitly requested.'
+    });
+    return {
+        schemaVersion: 'hadara.ci.gate.v1',
+        command: 'ci.gate',
+        ok: mode === 'advisory' ? true : blockers.length === 0,
+        mode,
+        scope: { ...(options.taskId ? { taskId: options.taskId } : {}), taskCount: tasks.length, allowEmpty },
+        checks,
+        blockers,
+        warnings
+    };
+}
+function applyScopeGuard(input) {
+    if (input.taskCount > 0) {
+        input.checks.push({
+            id: 'scope:tasks',
+            source: 'proof',
+            ok: true,
+            ...(input.taskId ? { taskId: input.taskId } : {}),
+            summary: `Validating ${input.taskCount} task capsule${input.taskCount === 1 ? '' : 's'}.`
+        });
+        return;
+    }
+    if (input.taskId) {
+        input.checks.push({ id: 'scope:tasks', source: 'proof', ok: false, taskId: input.taskId, summary: `Requested task ${input.taskId} was not found.` });
+        input.blockers.push({
+            severity: 'error',
+            source: 'proof',
+            code: 'CI_GATE_TASK_NOT_FOUND',
+            message: `CI gate found no Task Capsule for ${input.taskId}. Pass an existing task id.`,
+            taskId: input.taskId
+        });
+        return;
+    }
+    const emptyScopeIsBlocking = input.mode === 'strict' && !input.allowEmpty;
+    input.checks.push({ id: 'scope:tasks', source: 'proof', ok: !emptyScopeIsBlocking, summary: 'No Done Task Capsules were found to validate.' });
+    const issue = {
+        severity: emptyScopeIsBlocking ? 'error' : 'warning',
+        source: 'proof',
+        code: 'CI_GATE_NO_DONE_TASKS',
+        message: emptyScopeIsBlocking
+            ? 'Strict CI gate found no Done Task Capsules to validate. Pass --task <id> to scope a specific task, or --allow-empty only for bootstrap projects.'
+            : 'CI gate found no Done Task Capsules to validate; proof checks were skipped.'
+    };
+    (emptyScopeIsBlocking ? input.blockers : input.warnings).push(issue);
+}
+function selectTasks(projectRoot, taskId) {
+    const tasks = (0, task_capsule_1.listTaskCapsules)(projectRoot);
+    if (taskId)
+        return tasks.filter((task) => task.id === taskId);
+    return tasks.filter((task) => taskLooksDone(task.dir));
+}
+function taskLooksDone(taskDir) {
+    const taskPath = node_path_1.default.join(taskDir, 'TASK.md');
+    if (!node_fs_1.default.existsSync(taskPath))
+        return false;
+    return /\| Status \| Done \|/.test(node_fs_1.default.readFileSync(taskPath, 'utf8'));
+}
+function toProofCheck(taskId, proof) {
+    return {
+        id: `proof:${taskId}`,
+        source: 'proof',
+        ok: proof.ok,
+        taskId,
+        summary: `Proof verdict ${proof.verdict}; freshness ${proof.freshness.status}.`
+    };
+}

package/dist/services/proof-status.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProofStatusReport = createProofStatusReport;
+const node_path_1 = __importDefault(require("node:path"));
+const normalizer_1 = require("../evidence/normalizer");
+const semantics_1 = require("../evidence/semantics");
+const task_capsule_1 = require("../task/task-capsule");
+const task_close_1 = require("../task/task-close");
+const evidence_lint_1 = require("./evidence-lint");
+function createProofStatusReport(projectRoot, taskId, mode = 'status') {
+    const task = (0, task_capsule_1.findTaskCapsule)(projectRoot, taskId);
+    if (!task) {
+        return {
+            schemaVersion: mode === 'explain' ? 'hadara.proof.explain.v1' : 'hadara.proof.status.v1',
+            command: mode === 'explain' ? 'proof.explain' : 'proof.status',
+            ok: false,
+            target: { kind: 'task', taskId },
+            claim: 'task-readiness',
+            verdict: 'unknown',
+            freshness: { status: 'unknown', checkedSources: [] },
+            summary: { passed: 0, failed: 0, blocked: 0, privateOnlySubstantive: 0, substantivePositive: 0 },
+            supportingEvidence: [],
+            blockers: [{ severity: 'error', code: 'TASK_NOT_FOUND', message: `Task Capsule not found: ${taskId}` }],
+            warnings: [],
+            nextActions: [{ id: 'create-task', message: `Create or select an existing Task Capsule for ${taskId}.` }],
+            ...(mode === 'explain' ? { explanation: createExplanation([], []) } : {})
+        };
+    }
+    const lint = (0, evidence_lint_1.createEvidenceLintReport)(projectRoot, taskId);
+    const audit = (0, task_close_1.createTaskAuditCloseReport)(projectRoot, taskId);
+    const normalized = (0, normalizer_1.normalizeEvidenceRecordsInMemoryOrder)(lint.records, { taskDir: task.dir });
+    const semanticIssues = lint.issues.filter((issue) => issue.code.startsWith('TASK_DONE_'));
+    const freshnessIssues = audit.issues.map((issue) => ({
+        severity: 'warning',
+        code: issue.code,
+        message: issue.message,
+        path: issue.path
+    }));
+    const blockers = semanticIssues.filter((issue) => issue.severity === 'error').map(toProofIssue);
+    const warnings = [...semanticIssues.filter((issue) => issue.severity === 'warning').map(toProofIssue), ...freshnessIssues];
+    const summary = summarizeProofEvidence(normalized);
+    const freshness = createFreshness(projectRoot, task.dir, audit);
+    const verdict = selectVerdict({ blockers, warnings, summary, freshnessStatus: freshness.status });
+    return {
+        schemaVersion: mode === 'explain' ? 'hadara.proof.explain.v1' : 'hadara.proof.status.v1',
+        command: mode === 'explain' ? 'proof.explain' : 'proof.status',
+        ok: blockers.length === 0,
+        target: { kind: 'task', taskId },
+        claim: 'task-readiness',
+        verdict,
+        freshness,
+        summary,
+        supportingEvidence: normalized.filter((record) => (0, semantics_1.classifyEvidenceStrength)(record) === 'substantive-positive').slice(-5).map(toEvidenceRef),
+        blockers,
+        warnings,
+        nextActions: createNextActions(taskId, verdict, blockers, freshness.status),
+        ...(mode === 'explain' ? { explanation: createExplanation(semanticIssues, freshnessIssues) } : {})
+    };
+}
+function summarizeProofEvidence(records) {
+    const substantive = records.filter((record) => (0, semantics_1.classifyEvidenceStrength)(record) === 'substantive-positive');
+    return {
+        passed: records.filter((record) => record.outcome === 'passed').length,
+        failed: records.filter((record) => record.outcome === 'failed').length,
+        blocked: records.filter((record) => record.outcome === 'blocked').length,
+        privateOnlySubstantive: substantive.length > 0 && substantive.every((record) => record.visibility === 'private') ? substantive.length : 0,
+        substantivePositive: substantive.length
+    };
+}
+function createFreshness(projectRoot, taskDir, audit) {
+    // Freshness is derived from the task close audit, whose source hash covers the full
+    // close-relevant document set; expose that same set plus the evidence files the proof reads.
+    const checkedSources = Array.from(new Set([
+        ...(0, task_close_1.closeRelevantSourceRelativePaths)(projectRoot, taskDir),
+        toPortablePath(node_path_1.default.relative(projectRoot, node_path_1.default.join(taskDir, 'evidence.jsonl'))),
+        toPortablePath(node_path_1.default.relative(projectRoot, node_path_1.default.join(taskDir, 'EVIDENCE.md')))
+    ])).sort();
+    const verdict = audit.auditVerdict.verdict;
+    const status = !audit.auditVerdict.closeEvidenceFound
+        ? 'missing'
+        : audit.auditVerdict.verdict === 'closed-valid'
+            ? 'fresh'
+            : 'stale';
+    return {
+        status,
+        checkedSources,
+        closeVerdict: verdict,
+        ...(audit.auditVerdict.reportHashMatches !== undefined ? { reportHashMatches: audit.auditVerdict.reportHashMatches } : {}),
+        ...(audit.auditVerdict.sourceHashMatches !== undefined ? { sourceHashMatches: audit.auditVerdict.sourceHashMatches } : {})
+    };
+}
+function selectVerdict(input) {
+    const codes = new Set(input.blockers.map((issue) => issue.code));
+    if (codes.has('TASK_DONE_WITH_FAILED_EVIDENCE') || codes.has('TASK_DONE_WITH_UNEXPLAINED_BLOCKED_EVIDENCE'))
+        return 'blocked';
+    if (input.summary.substantivePositive === 0 || codes.has('TASK_DONE_WITHOUT_SUBSTANTIVE_EVIDENCE') || codes.has('TASK_DONE_WITH_ONLY_WEAK_EVIDENCE')) {
+        return 'insufficient';
+    }
+    if (input.blockers.length > 0)
+        return 'blocked';
+    if (input.warnings.length > 0 || input.summary.privateOnlySubstantive > 0 || input.freshnessStatus !== 'fresh')
+        return 'warning';
+    return 'sufficient';
+}
+function createNextActions(taskId, verdict, blockers, freshnessStatus) {
+    const actions = [];
+    if (blockers.length > 0)
+        actions.push({ id: 'inspect-evidence-lint', command: `hadara evidence lint --task ${taskId} --json`, message: 'Inspect semantic evidence blockers.' });
+    if (freshnessStatus !== 'fresh')
+        actions.push({ id: 'refresh-close-proof', command: `hadara task close --task ${taskId} --json`, message: 'Review close proof freshness and append a fresh close proof when appropriate.' });
+    if (verdict === 'insufficient')
+        actions.push({ id: 'add-substantive-evidence', command: `hadara evidence add-command --task ${taskId} --summary "..." --result passed --json`, message: 'Record substantive public evidence for the readiness claim.' });
+    return actions;
+}
+function createExplanation(semanticIssues, freshnessIssues) {
+    return {
+        rules: [
+            'Substantive passed evidence is required for a sufficient task-readiness claim.',
+            'Unresolved failed or unexplained blocked evidence makes the proof blocked.',
+            'Private-only substantive evidence and stale or missing close proof produce warnings.',
+            'Freshness is derived from task close audit source/report hash comparison.'
+        ],
+        semanticIssueCodes: semanticIssues.map((issue) => issue.code),
+        freshnessIssueCodes: freshnessIssues.map((issue) => issue.code)
+    };
+}
+function toProofIssue(issue) {
+    return {
+        severity: issue.severity,
+        code: issue.code,
+        message: issue.message,
+        ...(issue.evidenceId ? { evidenceId: issue.evidenceId } : {}),
+        ...(issue.path ? { path: issue.path } : {})
+    };
+}
+function toEvidenceRef(record) {
+    return {
+        id: record.id,
+        time: record.time,
+        category: record.category,
+        outcome: record.outcome,
+        visibility: record.visibility,
+        summary: record.summary
+    };
+}
+function toPortablePath(value) {
+    return value.split(node_path_1.default.sep).join('/');
+}

package/dist/task/task-close.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTaskCloseReport = createTaskCloseReport;
+exports.closeRelevantSourceRelativePaths = closeRelevantSourceRelativePaths;
 exports.executeTaskCloseEvidence = executeTaskCloseEvidence;
 exports.createTaskAuditCloseReport = createTaskAuditCloseReport;
 exports.formatTaskAuditCloseReport = formatTaskAuditCloseReport;
@@ -298,8 +299,8 @@ function hashValidationInputs(validation, evidenceLint, protocolDoctor) {
     });
     return `sha256:${node_crypto_1.default.createHash('sha256').update(payload, 'utf8').digest('hex')}`;
 }
-function hashCloseRelevantSource(projectRoot, taskDir) {
-    const relativePaths = [
+function closeRelevantSourceRelativePaths(projectRoot, taskDir) {
+    return [
         node_path_1.default.relative(projectRoot, node_path_1.default.join(taskDir, 'TASK.md')),
         node_path_1.default.relative(projectRoot, node_path_1.default.join(taskDir, 'PLAN.md')),
         node_path_1.default.relative(projectRoot, node_path_1.default.join(taskDir, 'CONTEXT.md')),
@@ -313,6 +314,9 @@ function hashCloseRelevantSource(projectRoot, taskDir) {
     ]
         .map(toPortablePath)
         .sort();
+}
+function hashCloseRelevantSource(projectRoot, taskDir) {
+    const relativePaths = closeRelevantSourceRelativePaths(projectRoot, taskDir);
     const payload = relativePaths.map((relativePath) => {
         const absolutePath = node_path_1.default.join(projectRoot, relativePath);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadara",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.0-rc.3",
   "private": false,
   "license": "MIT",
   "description": "HADARA: portable agentic development workbench",