hadara 0.2.0-rc.1 → 0.2.0-rc.3

package/README.md

@@ -1,11 +1,11 @@
 # HADARA
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ictseoyoungmin/HADARA-dev/main/docs/assets/hadara_sub_right_name.png" alt="HADARA" width="720">
+  <img src="https://raw.githubusercontent.com/ictseoyoungmin/HADARA/main/docs/assets/hadara_sub_right_name.png" alt="HADARA" width="720">
 </p>
 
 <p align="center">
-  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.1-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.1
+hadara@0.2.0-rc.3
 ```
 
-T-0275 refreshes package smoke, clean-checkout smoke, release artifact, release dry-run, and publish dry-run evidence for `0.2.0-rc.1`. T-0269 prepared the previous `0.2.0-rc.0` publish path, but rc.1 supersedes it 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,10 +35,12 @@ 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 source and publish-candidate version. |
+| `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 | Advisory preview only. |
+| PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
 | Installer scripts / USB launchers | Deferred. |
 
 No release command should publish, create a GitHub Release, build Docker images, upload artifacts, or load token values unless an operator explicitly approves the mutation path for the active release capsule.
@@ -47,10 +49,10 @@ 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.1
+npm install -g hadara@0.2.0-rc.2
 hadara doctor --json
 hadara task list --json
 hadara tools list --json
@@ -59,11 +61,11 @@ hadara tools list --json
 Run without a global install:
 
 ```bash
-npx hadara@0.2.0-rc.1 doctor --json
-npx hadara@0.2.0-rc.1 tools list --json
+npx hadara@0.2.0-rc.2 doctor --json
+npx hadara@0.2.0-rc.2 tools list --json
 ```
 
-Previous published RC: `hadara@0.1.0-rc.0` remains available on npm for comparison or rollback, but new installs should use the current RC once it is published.
+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
 
@@ -99,9 +101,9 @@ Task workflow:
 hadara task next --json
 hadara task create "implement a focused change" --json
 hadara task status --task T-0001 --json
-hadara task ready --task T-0001 --level done --json
 hadara task finish --task T-0001 --json
 hadara task finish --task T-0001 --execute --json
+hadara task ready --task T-0001 --level done --json
 hadara task close --task T-0001 --json
 hadara task close --task T-0001 --execute --json
 hadara task audit-close --task T-0001 --json
@@ -113,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
 ```
 
@@ -150,15 +155,18 @@ 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
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
 hadara task ready --task T-XXXX --level done --json
 
 # Optional workflow compression / next action preview:
 hadara task complete --task T-XXXX --json
 
-hadara task finish --task T-XXXX --json
-hadara task finish --task T-XXXX --execute --json
-
 hadara task close --task T-XXXX --json
 hadara task close --task T-XXXX --execute --json
 
@@ -175,6 +183,8 @@ Important distinctions:
 | `task close --execute` | Appends close evidence only. |
 | `task audit-close` | Read-only close proof audit. |
 
+Before `task close --execute`, finish Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, Task Board updates, and tracked state docs. After close execute, changing those close-source docs intentionally invalidates the previous close proof and requires rerunning ready/close/audit. Use stable wording for close results instead of pasting volatile close evidence ids into close-source docs.
+
 ## Initialize a Project
 
 ```bash
@@ -184,6 +194,8 @@ hadara init --profile standard
 hadara init --profile governed
 ```
 
+Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current evidence, ready, finish, close, and audit-close loop.
+
 | Profile | Use When |
 |---|---|
 | `basic` | Small project, only task/handoff discipline needed. |

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

@@ -14,9 +14,9 @@ const args_1 = require("./args");
 const INIT_PROFILE_SPECS = {
     basic: {
         profile: 'basic',
-        generatedDocsDescription: 'Core session docs only',
+        generatedDocsDescription: 'Core session docs plus task workflow commands',
         intendedUse: 'Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead.',
-        specialNotes: 'SOP required reading references only core docs plus active Task Capsule docs.',
+        specialNotes: 'SOP required reading references core docs, task workflow docs, and active Task Capsule docs.',
         docs: {
             architecture: false,
             developmentSlices: false,
@@ -141,6 +141,7 @@ function createGeneratedScaffoldFiles(profile) {
         { path: 'docs/TASK_BOARD.md', content: '# TASK_BOARD\n\n| ID | Title | Status | Capsule | Notes |\n|---|---|---|---|---|\n' },
         { path: 'docs/AGENT_HANDOFF.md', content: createAgentHandoffDoc() },
         { path: 'docs/IMPLEMENTATION_SOP.md', content: createImplementationSopDoc(spec) },
+        { path: 'docs/TASK_WORKFLOW_COMMANDS.md', content: createTaskWorkflowCommandsDoc() },
         { path: 'AGENTS.md', content: createAgentsDoc(spec) },
         { path: '.gitignore', content: createGitignoreDoc() }
     ];
@@ -163,7 +164,7 @@ function createGeneratedScaffoldFiles(profile) {
 function createInitDoctorReport(projectRoot) {
     const issues = [];
     const actions = [];
-    const requiredCore = ['AGENTS.md', '.gitignore', 'docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md'];
+    const requiredCore = ['AGENTS.md', '.gitignore', 'docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/TASK_WORKFLOW_COMMANDS.md'];
     for (const relativePath of requiredCore) {
         if (!node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath))) {
             issues.push({ severity: 'error', code: 'INIT_CORE_DOC_MISSING', path: relativePath, message: `${relativePath} is missing from the init scaffold.` });
@@ -391,6 +392,7 @@ const CANONICAL_TABLE_HEADERS = {
     'docs/AGENT_HANDOFF.md': ['| Area | State | Notes |', '| Task | Summary | Evidence |', '| Issue | Impact | Next Step |', '| Step | Reason | Done Evidence |', '| Check | Latest Evidence | Notes |', '| History Type | Path | When to Use |'],
     'docs/TASK_BOARD.md': ['| ID | Title | Status | Capsule | Notes |'],
     'docs/IMPLEMENTATION_SOP.md': ['| Document | When to Read | Purpose |', '| Profile | Scale | Generated Docs | Intended Use | Special Notes |', '| Document | Required Structure |'],
+    'docs/TASK_WORKFLOW_COMMANDS.md': ['| Command | Default Write Behavior | Notes |'],
     'docs/ARCHITECTURE.md': ['| Field | Value |', '| Boundary | Rule | Notes |', '| Component | Path / Surface | Responsibility | Status |'],
     'docs/DEVELOPMENT_SLICES.md': ['| Order | Slice | Capsule | Purpose | Done Evidence |'],
     'docs/DECISIONS.md': ['| ID | Date | Decision | Status | Rationale | Evidence |'],
@@ -493,7 +495,8 @@ function sopRequiredReadingRowsForProfile(profile) {
         ['`docs/PROJECT_STATE.md`', 'Every session', 'Current product state and source-of-truth map.'],
         ['`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact handoff and next recommended step.'],
         ['`docs/TASK_BOARD.md`', 'Every session', 'Work queue and task status.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
     if (profile === 'standard' || profile === 'governed') {
         rows.push(['`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.'], ['`docs/DEVELOPMENT_SLICES.md`', 'Starting, completing, or reclassifying slices', 'Roadmap ordering and completion evidence.'], ['`docs/DECISIONS.md`', 'Project-level decision work', 'Durable decisions that affect architecture or workflow.'], ['`docs/TEST_STRATEGY.md`', 'Validation planning or completion checks', 'Routine suites and special-case smoke boundaries.']);
@@ -508,7 +511,8 @@ function agentsRequiredReadingRowsForProfile(profile) {
         { document: '`docs/PROJECT_STATE.md`', when: 'Every session', purpose: 'Current product and capability state.' },
         { document: '`docs/AGENT_HANDOFF.md`', when: 'Every session', purpose: 'Compact continuation state.' },
         { document: '`docs/TASK_BOARD.md`', when: 'Every session', purpose: 'Current task queue and status.' },
-        { document: '`docs/IMPLEMENTATION_SOP.md`', when: 'Every session', purpose: 'Local workflow and required-reading registry.' }
+        { document: '`docs/IMPLEMENTATION_SOP.md`', when: 'Every session', purpose: 'Local workflow and required-reading registry.' },
+        { document: '`docs/TASK_WORKFLOW_COMMANDS.md`', when: 'Starting, finishing, closing, auditing, or explaining task workflow commands', purpose: 'Standard task loop, dry-run boundaries, and command `ok` semantics.' }
     ];
     if (profile === 'standard' || profile === 'governed') {
         rows.push({ document: '`docs/ARCHITECTURE.md`', when: 'Architecture, component, or boundary work', purpose: 'Current system shape and ownership boundaries.' }, { document: '`docs/DEVELOPMENT_SLICES.md`', when: 'Starting, completing, or reclassifying a development slice', purpose: 'Roadmap ordering, prerequisites, and completion evidence.' }, { document: '`docs/DECISIONS.md`', when: 'Project-level decision work', purpose: 'Durable project decisions.' }, { document: '`docs/TEST_STRATEGY.md`', when: 'Validation planning or completion checks', purpose: 'Routine suites and special-case checks.' });
@@ -632,7 +636,7 @@ function inferProfileFromGeneratedDocs(projectRoot) {
     return 'basic';
 }
 function requiredDocsForProfile(profile) {
-    const docs = ['docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md'];
+    const docs = ['docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/TASK_WORKFLOW_COMMANDS.md'];
     if (profile === 'standard' || profile === 'governed') {
         docs.push('docs/ARCHITECTURE.md', 'docs/DEVELOPMENT_SLICES.md', 'docs/DECISIONS.md', 'docs/TEST_STRATEGY.md');
     }
@@ -765,7 +769,7 @@ function createAgentHandoffDoc() {
 | Area | State | Notes |
 |---|---|---|
 | Scaffold | Initialized | HADARA protocol scaffold is initialized. |
-| Required Reading | Pending | Read \`PROJECT_STATE\`, \`TASK_BOARD\`, and \`IMPLEMENTATION_SOP\` before starting. |
+| Required Reading | Pending | Read \`PROJECT_STATE\`, \`AGENT_HANDOFF\`, \`TASK_BOARD\`, \`IMPLEMENTATION_SOP\`, and \`TASK_WORKFLOW_COMMANDS\` before starting. |
 
 ## Last 3 Completed Tasks
 
@@ -843,7 +847,8 @@ function createImplementationSopDoc(spec) {
         ['`docs/PROJECT_STATE.md`', 'Every session', 'Current product state and source-of-truth map.'],
         ['`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact handoff and next recommended step.'],
         ['`docs/TASK_BOARD.md`', 'Every session', 'Work queue and task status.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
     if (spec.docs.architecture) {
         requiredReadingRows.push(['`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.']);
@@ -872,7 +877,8 @@ function createImplementationSopDoc(spec) {
         ['`docs/PROJECT_STATE.md`', 'Product, Current Phase, Current Status, and Single Source of Truth sections.'],
         ['`docs/AGENT_HANDOFF.md`', 'Current State, Last 3 Completed Tasks, Current Known Problems, Next Recommended Step, Validation Baseline, and Historical Index sections.'],
         ['`docs/TASK_BOARD.md`', 'One task table with ID, Title, Status, Capsule, and Notes columns.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Session Start, Required Reading, Init Profile Matrix, Scaffold Document Structure, Implementation, Validation, Session End, and Handoff Compaction sections.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Session Start, Required Reading, Project-Specific Documents, Init Profile Matrix, Scaffold Document Structure, Implementation, Standard Task Workflow Loop, Validation, Evidence Records, Session End, and Handoff Compaction sections.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Standard Task Loop, Command Semantics, Non-Overlap Rules, and State Documents sections.']
     ];
     if (spec.docs.architecture)
         structureRows.push(['`docs/ARCHITECTURE.md`', 'Overview, Boundaries, and Current Components sections.']);
@@ -905,14 +911,23 @@ ${numberedList(sessionStart)}
 |---|---|---|
 ${requiredReadingRows.map(formatTableRow).join('\n')}
 
-When adding project-specific specs, contracts, or roadmap files, add them to this table and explain when agents must read them. Use \`hadara init register-doc --path <path> --when <text> --purpose <text> --json\` to preview registration, and add \`--execute\` to update this table.
+## Project-Specific Documents
+
+When adding project-specific specs, contracts, roadmap files, or human/agent operating notes, register them in the Required Reading table before expecting people or agents to rely on them. Each row must explain when to read the document and what decision or workflow boundary it owns.
+
+\`\`\`bash
+hadara init register-doc --path docs/specs/example.md --when "When changing example behavior" --purpose "Example behavior contract" --json
+hadara init register-doc --path docs/specs/example.md --when "When changing example behavior" --purpose "Example behavior contract" --execute --json
+\`\`\`
+
+Use \`--require-exists\` when the document must already exist before registration. Keep local-only notes out of committed required reading unless they are intentionally part of the project handoff.
 
 ## Init Profile Matrix
 
 | Profile | Scale | Generated Docs | Intended Use | Special Notes |
 |---|---|---|---|---|
-| \`basic\` | Small | Core session docs only | Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead. | SOP required reading references only core docs plus active Task Capsule docs. |
-| \`standard\` | Medium, default | Core docs plus planning, architecture, decision, and validation docs | Most multi-session projects that need roadmap slices and repeatable validation. | Optional integrations must be registered before agents rely on them. |
+| \`basic\` | Small | Core session docs plus task workflow commands | Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead. | SOP required reading references core docs, task workflow docs, and active Task Capsule docs. |
+| \`standard\` | Medium, default | Basic docs plus planning, architecture, decision, and validation docs | Most multi-session projects that need roadmap slices and repeatable validation. | Optional integrations must be registered before agents rely on them. |
 | \`governed\` | Heavy | Standard docs plus security, refactor log, and roadmap docs | Long-lived projects with stronger governance, security boundaries, refactor history, or roadmap-level planning. | Project-specific contracts still must be manually registered in Required Reading. |
 
 ## Scaffold Document Structure
@@ -932,12 +947,71 @@ Prefer tables for repeated records and \`##\`/\`###\` headings for durable secti
 3. Make the smallest coherent change that satisfies acceptance criteria.
 4. Update task-local docs when scope changes.
 
+## Standard Task Workflow Loop
+
+The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. For ordinary implementation capsules, use this loop:
+
+\`\`\`bash
+hadara task next --json
+
+# If a matching capsule already exists:
+hadara task status --task T-XXXX --json
+
+# If no matching capsule exists, create one first:
+hadara task create "task title" --json
+hadara task status --task T-XXXX --json
+
+# Do the scoped work.
+
+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
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
+hadara task ready --task T-XXXX --level done --json
+
+# Optional workflow compression / next action preview:
+hadara task complete --task T-XXXX --json
+
+hadara task close --task T-XXXX --json
+hadara task close --task T-XXXX --execute --json
+
+hadara task audit-close --task T-XXXX --json
+\`\`\`
+
+| Command | Default Write Behavior | Notes |
+|---|---|---|
+| \`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; 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. |
+| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+
+Before running \`task ready\` and \`task close\`, finish all close-source edits: Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, \`docs/TASK_BOARD.md\`, and tracked state docs such as \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when they apply. After \`task close --execute --json\`, do not edit those close-source documents unless you intend to rerun \`task ready\`, \`task close\`, and \`task audit-close\`. Avoid writing volatile close evidence ids into close-source docs; use stable wording such as "close evidence appended; audit returned closed-valid".
+
 ## Validation
 
 1. Run relevant tests.
-2. Run \`hadara harness validate --task <task-id> --json\`.
-3. Record evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
-4. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
+2. Record meaningful evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
+3. Preview and execute \`hadara task finish --task <task-id> --json\` and \`hadara task finish --task <task-id> --execute --json\`.
+4. Finalize Task Capsule docs and tracked state docs before close so the close source hash remains stable.
+5. Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close.
+6. Preview and execute \`hadara task close --task <task-id> --json\` and \`hadara task close --task <task-id> --execute --json\`, then run \`hadara task audit-close --task <task-id> --json\`.
+7. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
+
+\`task ready\` and \`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task <task-id> --level done --json\` directly when you need to debug capsule format or done-level validation failures.
+
+## Evidence Records
+
+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. 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
 
@@ -1042,8 +1116,18 @@ function createTestStrategyDoc() {
 | Step | Check | Evidence Location |
 |---|---|---|
 | 1 | Run the relevant suite from the table above. | Task Capsule \`EVIDENCE.md\` |
-| 2 | Run \`hadara harness validate --task <task-id> --json\`. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
-| 3 | Record meaningful evidence in the Task Capsule. | Task Capsule files |
+| 2 | Record meaningful evidence in the Task Capsule. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
+| 3 | Preview and execute \`task finish\` to synchronize status bookkeeping. | Task Capsule \`TASK.md\` and \`docs/TASK_BOARD.md\` |
+| 4 | Finalize Task Capsule docs and tracked state docs before close. | Task Capsule docs and tracked state docs |
+| 5 | Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
+| 6 | Preview and execute \`task close\`, then run \`task audit-close\`. | Task Capsule close evidence |
+
+## Diagnostic Checks
+
+| Check | Command | When To Use |
+|---|---|---|
+| Task Capsule format | \`hadara harness validate --task <task-id> --level done --json\` | \`task ready\` or \`task close\` reports done-level validation failures. |
+| Evidence index | \`hadara evidence lint --task <task-id> --json\` | Evidence files were touched manually by mistake or evidence drift is suspected. |
 
 ## Special-Case Checks
 
@@ -1072,14 +1156,94 @@ function createRoadmapDoc() {
 |---|---|---|
 `;
 }
+function createTaskWorkflowCommandsDoc() {
+    return `# TASK_WORKFLOW_COMMANDS
+
+HADARA task workflow commands are split by responsibility. Similar-looking commands are not interchangeable: some only report state, some check readiness, some perform bounded bookkeeping writes, and some append close evidence.
+
+## Standard Task Loop
+
+Use this loop for ordinary implementation capsules:
+
+\`\`\`bash
+hadara task next --json
+
+# If a matching capsule already exists:
+hadara task status --task T-XXXX --json
+
+# If no matching capsule exists, create one first:
+hadara task create "task title" --json
+hadara task status --task T-XXXX --json
+
+# Do the scoped work.
+
+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
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
+hadara task ready --task T-XXXX --level done --json
+
+# Optional workflow compression / next action preview:
+hadara task complete --task T-XXXX --json
+
+hadara task close --task T-XXXX --json
+hadara task close --task T-XXXX --execute --json
+
+hadara task audit-close --task T-XXXX --json
+\`\`\`
+
+\`task finish\`, \`task ready\`, and \`task close\` are intentionally separate. \`finish\` synchronizes bounded status bookkeeping first. \`ready\` then validates the Done-level state. \`close\` records close evidence after validation succeeds. \`audit-close\` checks the resulting close evidence after the write.
+
+The close model has three separate phases: validation proves readiness, close records the proof, and audit checks the already-recorded close evidence. Close evidence is excluded from the current validation loop because it is appended after validation; requiring it as a same-run precondition would create a fixed-point loop.
+
+\`task ready\` and \`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task T-XXXX --level done --json\` directly when debugging capsule format, status-history, acceptance, evidence, or handoff validation failures.
+
+Before close, finish all close-source edits: Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, \`docs/TASK_BOARD.md\`, and tracked state docs such as \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when they apply. After \`task close --execute --json\`, changing those documents changes the close source hash and requires rerunning \`task ready\`, \`task close\`, and \`task audit-close\`. Do not paste volatile close evidence ids into close-source docs; prefer stable wording such as "close evidence appended; audit returned closed-valid".
+
+## Command Semantics
+
+| Command | Default Write Behavior | Notes |
+|---|---|---|
+| \`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; 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. |
+| \`task close\` | Dry-run by default; writes only with \`--execute\` | Appends only canonical close evidence after close preconditions pass. |
+| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+
+## Non-Overlap Rules
+
+- \`task next\` chooses work; it does not create a capsule or infer completion.
+- \`task status\` is an operator console; \`ok: true\` means report generation succeeded, not that the task is ready.
+- \`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. \`--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.
+- \`task audit-close\` is read-only and should be run after \`task close --execute --json\`.
+
+## State Documents
+
+\`task finish --execute --json\` deliberately does not update broad prose state. Operators still update \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and any roadmap/slice docs generated for the selected profile when the task changes project state.
+`;
+}
 function createAgentsDoc(spec) {
     const requiredReadingRows = [
         ['1', '`docs/PROJECT_STATE.md`', 'Every session', 'Current product and capability state.'],
         ['2', '`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact continuation state.'],
         ['3', '`docs/TASK_BOARD.md`', 'Every session', 'Current task queue and status.'],
-        ['4', '`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local workflow and required-reading registry.']
+        ['4', '`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local workflow and required-reading registry.'],
+        ['5', '`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
-    let order = 5;
+    let order = 6;
     if (spec.docs.architecture)
         requiredReadingRows.push([String(order++), '`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.']);
     if (spec.docs.developmentSlices)
@@ -1099,7 +1263,8 @@ function createAgentsDoc(spec) {
     const ruleRows = [
         ['Task boundary', 'Keep work inside one Task Capsule whenever possible.', 'Active Task Capsule'],
         ['Task creation', 'If no suitable capsule exists, create one with `hadara task create <title>`.', '`docs/TASK_BOARD.md`'],
-        ['Evidence', 'Do not mark work done without evidence.', '`EVIDENCE.md`, `evidence.jsonl`'],
+        ['Evidence', 'Do not mark work done without evidence. Do not hand-edit `evidence.jsonl`; record failed or blocked checks honestly instead of replacing them with optimistic summaries.', '`EVIDENCE.md`, `evidence.jsonl`'],
+        ['Task workflow', 'For task workflow commands, follow `docs/TASK_WORKFLOW_COMMANDS.md`: record evidence, preview and execute `task finish`, finalize close-source docs, run `task ready`, preview and execute `task close`, then run `task audit-close`.', 'Task Capsule evidence'],
         ['Safety', 'Do not execute dangerous commands without explicit user approval.', 'Task Capsule evidence'],
         ['Secrets', 'Do not write secrets, private logs, or machine-local state into committed files.', 'Changed-file review'],
         ['Store boundary', 'Preserve the portable/project store boundary.', spec.docs.architecture ? '`.gitignore`, `docs/ARCHITECTURE.md`' : '`.gitignore`'],
@@ -1143,6 +1308,22 @@ dist/
 coverage/
 *.log
 
+# Python and test artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+env/
+*.db
+*.sqlite
+*.sqlite3
+
 # HADARA local/private state
 .hadara/local/
 .hadara/tmp/

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.1",
+  "version": "0.2.0-rc.3",
   "private": false,
   "license": "MIT",
   "description": "HADARA: portable agentic development workbench",