hadara 0.3.0 → 0.3.2-rc.0

package/dist/evidence/evidence.js

@@ -3,10 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EvidenceAppendLockError = exports.EvidenceArtifactPolicyError = void 0;
+exports.EvidenceTaskDirectoryError = exports.EvidenceResultOutcomeMismatchError = exports.EvidenceAppendLockError = exports.EvidenceArtifactPolicyError = void 0;
 exports.persistedEvidenceKind = persistedEvidenceKind;
 exports.persistedEvidenceResult = persistedEvidenceResult;
 exports.persistedEvidencePath = persistedEvidencePath;
+exports.validateEvidenceResultOutcomeCompatibility = validateEvidenceResultOutcomeCompatibility;
 exports.appendEvidence = appendEvidence;
 exports.appendEvidenceWithResult = appendEvidenceWithResult;
 exports.appendEvidenceTextArtifact = appendEvidenceTextArtifact;
@@ -48,13 +49,53 @@ class EvidenceAppendLockError extends Error {
     }
 }
 exports.EvidenceAppendLockError = EvidenceAppendLockError;
+class EvidenceResultOutcomeMismatchError extends Error {
+    issue;
+    code = 'EVIDENCE_RESULT_OUTCOME_MISMATCH';
+    constructor(issue) {
+        super(issue.message);
+        this.issue = issue;
+        this.name = 'EvidenceResultOutcomeMismatchError';
+    }
+}
+exports.EvidenceResultOutcomeMismatchError = EvidenceResultOutcomeMismatchError;
+class EvidenceTaskDirectoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'EvidenceTaskDirectoryError';
+    }
+}
+exports.EvidenceTaskDirectoryError = EvidenceTaskDirectoryError;
+function validateEvidenceResultOutcomeCompatibility(input) {
+    if (!input.outcome)
+        return undefined;
+    if (input.outcome === 'passed' || input.outcome === 'failed' || input.outcome === 'blocked' || input.outcome === 'unknown') {
+        if (input.result === input.outcome)
+            return undefined;
+        return {
+            severity: 'error',
+            code: 'EVIDENCE_RESULT_OUTCOME_MISMATCH',
+            message: `Evidence result ${input.result} conflicts with outcome ${input.outcome}; matching evidence outcomes must use the same legacy result.`
+        };
+    }
+    if ((input.outcome === 'recorded' || input.outcome === 'not-applicable') && input.result !== 'unknown') {
+        return {
+            severity: 'error',
+            code: 'EVIDENCE_RESULT_OUTCOME_MISMATCH',
+            message: `Evidence outcome ${input.outcome} is record-only/non-applicable evidence and requires legacy result unknown.`
+        };
+    }
+    return undefined;
+}
 function appendEvidence(projectRoot, record) {
     return appendEvidenceWithResult(projectRoot, record).markdownPath;
 }
 function appendEvidenceWithResult(projectRoot, record) {
     const taskDir = findTaskDir(projectRoot, record.taskId);
     if (!taskDir) {
-        throw new Error(`Task capsule not found: ${record.taskId}`);
+        throw new EvidenceTaskDirectoryError('TASK_NOT_FOUND', `Task Capsule not found: ${record.taskId}`);
     }
     const time = new Date().toISOString();
     const visibility = record.visibility ?? 'public';
@@ -70,7 +111,7 @@ function appendEvidenceWithResult(projectRoot, record) {
 function appendEvidenceTextArtifact(projectRoot, record, artifact, options = {}) {
     const taskDir = findTaskDir(projectRoot, record.taskId);
     if (!taskDir) {
-        throw new Error(`Task capsule not found: ${record.taskId}`);
+        throw new EvidenceTaskDirectoryError('TASK_NOT_FOUND', `Task Capsule not found: ${record.taskId}`);
     }
     const time = new Date().toISOString();
     const visibility = record.visibility ?? 'public';
@@ -182,6 +223,13 @@ function sleepSync(ms) {
     Atomics.wait(signal, 0, 0, ms);
 }
 function appendEvidenceRecord(input) {
+    const resultOutcomeIssue = validateEvidenceResultOutcomeCompatibility({
+        result: input.record.result,
+        outcome: input.record.outcome
+    });
+    if (resultOutcomeIssue) {
+        throw new EvidenceResultOutcomeMismatchError(resultOutcomeIssue);
+    }
     const summary = (0, redaction_1.redactSecrets)(input.record.summary.replace(/\|/g, '/'));
     const markdownPath = node_path_1.default.join(input.taskDir, 'EVIDENCE.md');
     return withEvidenceAppendLock(input.projectRoot, input.record.taskId, () => {
@@ -212,6 +260,8 @@ function appendEvidenceRecord(input) {
             kind: input.record.kind,
             summary,
             result: input.record.result,
+            category: input.record.category,
+            outcome: input.record.outcome,
             visibility: input.visibility,
             attachedPath,
             tags: input.record.tags,
@@ -250,8 +300,8 @@ function createEvidenceV2Record(input) {
         schemaVersion: 'hadara.evidence.v2',
         time: input.time,
         taskId: input.taskId,
-        category: deriveEvidenceCategory(input.kind, input.summary),
-        outcome: normalizeEvidenceOutcome(input.result),
+        category: input.category ?? deriveEvidenceCategory(input.kind, input.summary),
+        outcome: input.outcome ?? normalizeEvidenceOutcome(input.result),
         visibility: input.visibility,
         summary: input.summary,
         artifacts: input.visibility === 'public' && input.attachedPath
@@ -375,8 +425,13 @@ function findTaskDir(projectRoot, taskId) {
     const tasksDir = node_path_1.default.join(projectRoot, 'tasks');
     if (!node_fs_1.default.existsSync(tasksDir))
         return null;
-    const entry = node_fs_1.default.readdirSync(tasksDir).find((name) => name.startsWith(`${taskId}-`));
-    return entry ? node_path_1.default.join(tasksDir, entry) : null;
+    const entries = node_fs_1.default
+        .readdirSync(tasksDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith(`${taskId}-`) && node_fs_1.default.existsSync(node_path_1.default.join(tasksDir, entry.name, 'TASK.md')));
+    if (entries.length > 1) {
+        throw new EvidenceTaskDirectoryError('TASK_CAPSULE_AMBIGUOUS', `Multiple Task Capsules found for ${taskId}; remove or repair duplicate TASK.md-bearing directories before recording evidence.`);
+    }
+    return entries[0] ? node_path_1.default.join(tasksDir, entries[0].name) : null;
 }
 function createSessionEvidenceDirs(dataRoot, sessionId) {
     const evidenceDir = node_path_1.default.join(dataRoot, 'sessions', sessionId, 'evidence');

package/dist/evidence/semantics.js

@@ -82,10 +82,10 @@ function findUnresolvedFailedEvidence(records, taskDocs = {}) {
         if (record.outcome !== 'failed')
             return false;
         const laterRecords = records.slice(index + 1);
-        if (laterRecords.some((candidate) => candidate.outcome === 'passed' && candidate.category === record.category))
-            return false;
         if (laterRecords.some((candidate) => hasExactResolutionMarker(candidate, record.id)))
             return false;
+        if (usesLegacySameCategoryFallback(record, laterRecords))
+            return false;
         if (hasResidualRiskDocumentation(record, taskDocs))
             return false;
         return true;
@@ -137,7 +137,7 @@ function analyzeTaskEvidenceSemantics(input) {
             message: 'Task has unresolved failed evidence while marked Done.',
             evidenceId: record.id,
             path: `${input.taskDir}/evidence.jsonl`,
-            expected: `later passed same-category evidence, supersedes:${record.id}, resolves:${record.id}, or explicit residual-risk documentation`,
+            expected: `supersedes:${record.id}, resolves:${record.id}, legacy same-category passed evidence, or explicit residual-risk documentation`,
             actual: 'failed evidence has no resolution signal'
         });
     }
@@ -191,8 +191,17 @@ function isRecordOnlyCategory(category) {
     return exports.RECORD_ONLY_EVIDENCE_CATEGORIES.includes(category);
 }
 function hasExactResolutionMarker(record, evidenceId) {
+    if (record.outcome !== 'passed' && record.outcome !== 'recorded')
+        return false;
     return record.tags.includes(`supersedes:${evidenceId}`) || record.tags.includes(`resolves:${evidenceId}`);
 }
+function usesLegacySameCategoryFallback(record, laterRecords) {
+    if (record.persistedSchemaVersion !== 'hadara.evidence.v1')
+        return false;
+    return laterRecords.some((candidate) => candidate.persistedSchemaVersion === 'hadara.evidence.v1' &&
+        candidate.outcome === 'passed' &&
+        candidate.category === record.category);
+}
 function hasResidualRiskDocumentation(record, taskDocs) {
     const content = joinTaskDocs(taskDocs);
     if (!content)

package/dist/harness/validate.js

@@ -25,6 +25,8 @@ const REQUIRED_TASK_FILES = [
 const EVIDENCE_KINDS = new Set(['test-log', 'command-log', 'diff-summary', 'screenshot', 'note']);
 const EVIDENCE_RESULTS = new Set(['passed', 'failed', 'blocked', 'unknown']);
 const EVIDENCE_VISIBILITIES = new Set(['public', 'private']);
+const TASK_STATUS_TOKENS = new Set(['draft', 'in progress', 'blocked', 'done', 'partial', 'superseded', 'archived']);
+const STALE_PENDING_CLOSE_PATTERN = /\b(?:done\s+pending\s+lifecycle\s+close|pending\s+lifecycle\s+close)\b/i;
 const DONE_SEMANTIC_EVIDENCE_CODES = new Set([
     'TASK_DONE_WITHOUT_SUBSTANTIVE_EVIDENCE',
     'TASK_DONE_WITH_FAILED_EVIDENCE',
@@ -338,6 +340,8 @@ function validateDoneLevel(projectRoot, task, issues, checkedFiles) {
     validateEvidenceIndexHasRecords(projectRoot, task, issues);
     validateEvidenceSemanticGates(projectRoot, task, issues);
     validateHandoffDone(projectRoot, task, issues);
+    validateHandoffCurrentStateTokens(projectRoot, task, issues);
+    validatePlanStatusDrift(projectRoot, task, issues);
     validateTaskBoardDone(projectRoot, task, issues, checkedFiles);
 }
 function validateTaskMetadataComplete(projectRoot, task, issues) {
@@ -645,6 +649,112 @@ function validateHandoffDone(projectRoot, task, issues) {
         });
     }
 }
+function validateHandoffCurrentStateTokens(projectRoot, task, issues) {
+    const handoffPath = node_path_1.default.join(task.dir, 'HANDOFF.md');
+    if (!node_fs_1.default.existsSync(handoffPath))
+        return;
+    const relativePath = toPortablePath(node_path_1.default.relative(projectRoot, handoffPath));
+    const currentState = readSectionBody(handoffPath, '## Current State');
+    const fields = handoffCurrentStateFields(currentState);
+    const taskStatus = fields.get('taskstatus') ?? fields.get('task status');
+    const legacyStatus = fields.get('status');
+    const closeState = fields.get('closestate') ?? fields.get('close state');
+    if (taskStatus && !isTaskStatusToken(taskStatus)) {
+        issues.push(handoffStatusIssue(relativePath, `HANDOFF.md TaskStatus uses non-canonical value "${taskStatus}".`));
+    }
+    if (legacyStatus) {
+        if (STALE_PENDING_CLOSE_PATTERN.test(legacyStatus)) {
+            issues.push(handoffStatusIssue(relativePath, 'HANDOFF.md legacy Status mixes lifecycle state with pending close proof wording.'));
+        }
+        else if (!isTaskStatusToken(legacyStatus)) {
+            issues.push(handoffStatusIssue(relativePath, `HANDOFF.md legacy Status uses non-canonical value "${legacyStatus}".`));
+        }
+    }
+    if (STALE_PENDING_CLOSE_PATTERN.test(currentState) && (!legacyStatus || !STALE_PENDING_CLOSE_PATTERN.test(legacyStatus))) {
+        issues.push(handoffStatusIssue(relativePath, 'HANDOFF.md Current State contains stale pending lifecycle close wording.'));
+    }
+    if (closeState) {
+        issues.push({
+            severity: 'error',
+            code: 'TASK_HANDOFF_CLOSE_STATE_PERSISTED',
+            message: `HANDOFF.md persists derived CloseState value "${closeState}".`,
+            path: relativePath,
+            heading: 'Current State',
+            fixHint: 'Remove the CloseState row from task-local HANDOFF.md; use task status, audit-close, proof status, or state verify read models for derived close state.',
+            example: '| TaskStatus | Done |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Current State',
+                requiredChange: 'Remove persistent CloseState from this close-source handoff table.',
+                example: '| TaskStatus | Done |',
+                blocking: true
+            }
+        });
+    }
+}
+function handoffCurrentStateFields(currentState) {
+    const fields = new Map();
+    for (const cells of (0, markdown_table_1.parseMarkdownRows)(currentState)) {
+        if (cells.length < 2 || /^field$/i.test(cells[0] ?? ''))
+            continue;
+        fields.set(normalizeFieldName(cells[0] ?? ''), cells[1]?.trim() ?? '');
+    }
+    return fields;
+}
+function handoffStatusIssue(relativePath, message) {
+    return {
+        severity: 'error',
+        code: 'TASK_HANDOFF_STATUS_DRIFT',
+        message,
+        path: relativePath,
+        heading: 'Current State',
+        fixHint: 'Use `TaskStatus` for lifecycle state only; close proof state is derived from audit-close/proof/status read models.',
+        example: '| TaskStatus | Done |',
+        remediationHint: {
+            path: relativePath,
+            heading: 'Current State',
+            requiredChange: 'Replace ambiguous Status wording with canonical TaskStatus and remove close-proof wording from HANDOFF.md.',
+            example: '| TaskStatus | Done |',
+            blocking: true
+        }
+    };
+}
+function validatePlanStatusDrift(projectRoot, task, issues) {
+    const planPath = node_path_1.default.join(task.dir, 'PLAN.md');
+    if (!node_fs_1.default.existsSync(planPath))
+        return;
+    const relativePath = toPortablePath(node_path_1.default.relative(projectRoot, planPath));
+    const rows = (0, markdown_table_1.parseMarkdownRows)(node_fs_1.default.readFileSync(planPath, 'utf8'));
+    const inProgressRows = rows.filter((cells) => {
+        if (/^step$/i.test(cells[0] ?? ''))
+            return false;
+        return (cells[2] ?? '').trim().toLowerCase() === 'in progress';
+    });
+    if (inProgressRows.length === 0)
+        return;
+    issues.push({
+        severity: 'error',
+        code: 'TASK_PLAN_STATUS_DRIFT',
+        message: `PLAN.md has ${inProgressRows.length} row(s) still marked In Progress while the task is Done.`,
+        path: relativePath,
+        heading: 'Plan',
+        fixHint: 'Before closing a Done task, mark completed plan rows Done or split/defer unfinished work explicitly instead of leaving rows In Progress.',
+        example: '| 3 | Commit the pre-publish preparation. | Done | `command:T-XXXX:check` |',
+        remediationHint: {
+            path: relativePath,
+            heading: 'Plan',
+            requiredChange: 'Update PLAN.md rows that are no longer active from In Progress to Done, Blocked, Partial, or a task-specific final status with evidence.',
+            example: '| 3 | Commit the pre-publish preparation. | Done | `command:T-XXXX:check` |',
+            blocking: true
+        }
+    });
+}
+function isTaskStatusToken(value) {
+    return TASK_STATUS_TOKENS.has(value.trim().toLowerCase());
+}
+function normalizeFieldName(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
 function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
     const taskBoardPath = node_path_1.default.join(projectRoot, 'docs', 'TASK_BOARD.md');
     const relativePath = toPortablePath(node_path_1.default.relative(projectRoot, taskBoardPath));

package/dist/schemas/evidence-list.schema.json

@@ -25,25 +25,44 @@
         "evidenceV1": {
             "type": "object",
             "additionalProperties": true,
-            "required": ["schemaVersion", "time", "taskId", "kind", "summary", "result", "visibility"],
+            "required": ["schemaVersion", "id", "sourceLine", "idSource", "idStability", "persistedSchemaVersion", "time", "taskId", "kind", "summary", "result", "visibility", "category", "outcome", "tags", "legacy"],
             "properties": {
                 "schemaVersion": { "const": "hadara.evidence.v1" },
+                "id": { "type": "string", "pattern": "^legacy:T-[0-9]{4}:[0-9]+:[a-f0-9]{12}$" },
+                "sourceLine": { "type": "integer", "minimum": 1 },
+                "idSource": { "const": "line-fallback" },
+                "idStability": { "const": "unstable-on-reorder" },
+                "persistedSchemaVersion": { "const": "hadara.evidence.v1" },
                 "time": { "type": "string", "minLength": 1 },
                 "taskId": { "type": "string", "pattern": "^T-[0-9]{4}$" },
                 "kind": { "type": "string", "enum": ["test-log", "command-log", "diff-summary", "screenshot", "note"] },
                 "summary": { "type": "string", "minLength": 1 },
                 "result": { "type": "string", "enum": ["passed", "failed", "blocked", "unknown"] },
-                "visibility": { "type": "string", "enum": ["public", "private"] }
+                "visibility": { "type": "string", "enum": ["public", "private"] },
+                "category": { "type": "string", "enum": ["validation", "implementation", "release", "security", "policy", "operation", "decision", "handoff", "audit", "note", "observation"] },
+                "outcome": { "type": "string", "enum": ["passed", "failed", "blocked", "unknown", "recorded", "not-applicable"] },
+                "tags": { "type": "array", "items": { "type": "string" } },
+                "legacy": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "required": ["kind", "result"],
+                    "properties": {
+                        "kind": { "type": "string", "enum": ["test-log", "command-log", "diff-summary", "screenshot", "note"] },
+                        "result": { "type": "string", "enum": ["passed", "failed", "blocked", "unknown"] },
+                        "evidencePath": { "type": "string", "minLength": 1 }
+                    }
+                }
             }
         },
         "evidenceV2": {
             "type": "object",
             "additionalProperties": true,
-            "required": ["schemaVersion", "id", "fingerprint", "idSource", "idStability", "time", "taskId", "category", "outcome", "visibility", "summary", "artifacts", "tags", "legacy"],
+            "required": ["schemaVersion", "id", "sourceLine", "persistedSchemaVersion", "fingerprint", "idSource", "idStability", "time", "taskId", "category", "outcome", "visibility", "summary", "artifacts", "tags", "legacy"],
             "properties": {
                 "schemaVersion": { "const": "hadara.evidence.v2" },
                 "id": { "type": "string", "minLength": 1 },
                 "sourceLine": { "type": "integer", "minimum": 1 },
+                "persistedSchemaVersion": { "const": "hadara.evidence.v2" },
                 "fingerprint": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
                 "idSource": { "const": "persisted" },
                 "idStability": { "const": "durable" },

package/dist/schemas/schema-index.json

@@ -274,6 +274,13 @@
             "owner": "runtime/version",
             "notes": "Documents read-only CLI origin, package, git, Node, and build freshness reports from hadara version --verbose."
         },
+        {
+            "id": "hadara.stateProjection.v1",
+            "path": "src/schemas/state-projection.schema.json",
+            "status": "fixture",
+            "owner": "services/state-projection",
+            "notes": "Documents the Phase 8.4 read-only state consistency projection over Task Board, Task Capsules, handoff, close evidence, docs registry, and release readiness state."
+        },
         {
             "id": "hadara.releaseGate.v1",
             "path": "src/schemas/release-gate.schema.json",

package/dist/schemas/state-projection.schema.json

@@ -0,0 +1,115 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.stateProjection.v1",
+    "x-hadara-schema-id": "hadara.stateProjection.v1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "generatedAt", "projectRoot", "summary", "sources", "tasks", "issues"],
+    "properties": {
+        "schemaVersion": {
+            "const": "hadara.stateProjection.v1"
+        },
+        "command": {
+            "const": "state.projection"
+        },
+        "ok": {
+            "type": "boolean"
+        },
+        "generatedAt": {
+            "type": "string"
+        },
+        "projectRoot": {
+            "type": "string"
+        },
+        "summary": {
+            "type": "object",
+            "required": ["consistent", "issueCounts", "latestDoneTaskId", "activeTaskIds", "checkedTasks"],
+            "additionalProperties": true,
+            "properties": {
+                "consistent": {
+                    "type": "boolean"
+                },
+                "issueCounts": {
+                    "type": "object"
+                },
+                "latestDoneTaskId": {
+                    "type": ["string", "null"]
+                },
+                "activeTaskIds": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "checkedTasks": {
+                    "type": "number"
+                }
+            }
+        },
+        "sources": {
+            "type": "object"
+        },
+        "tasks": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["id", "title", "capsule", "task", "taskBoard", "handoff", "plan", "closeProof"],
+                "additionalProperties": true,
+                "properties": {
+                    "id": {
+                        "type": "string"
+                    },
+                    "title": {
+                        "type": "string"
+                    },
+                    "capsule": {
+                        "type": "string"
+                    },
+                    "task": {
+                        "type": "object"
+                    },
+                    "taskBoard": {
+                        "type": "object"
+                    },
+                    "handoff": {
+                        "type": "object"
+                    },
+                    "plan": {
+                        "type": "object"
+                    },
+                    "closeProof": {
+                        "type": "object"
+                    }
+                }
+            }
+        },
+        "issues": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["severity", "code", "message", "fixHint"],
+                "additionalProperties": true,
+                "properties": {
+                    "severity": {
+                        "enum": ["error", "warning", "info"]
+                    },
+                    "code": {
+                        "type": "string"
+                    },
+                    "message": {
+                        "type": "string"
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "taskId": {
+                        "type": "string"
+                    },
+                    "fixHint": {
+                        "type": "string"
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/services/capability-registry.js

@@ -475,8 +475,8 @@ exports.HADARA_COMMAND_REGISTRY = [
     },
     {
         id: 'evidence.add-command',
-        command: 'hadara evidence add-command --task <task-id> --summary <text> [--result <result>] [--idempotency-key <key>] [--json]',
-        summary: 'Append command-log evidence to a Task Capsule.',
+        command: 'hadara evidence add-command --task <task-id> --summary <text> [--result <result>] [--outcome <outcome>] [--category <category>] [--resolves <id>] [--supersedes <id>] [--idempotency-key <key>] [--json]',
+        summary: 'Append command-log evidence to a Task Capsule, rejecting incompatible result/outcome metadata.',
         canonical: true,
         appearsInDefaultHelp: true,
         family: 'capsule-lifecycle',
@@ -490,14 +490,17 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         schemaVersion: 'hadara.evidence.collect.v1',
         docs: ['docs/IMPLEMENTATION_SOP.md'],
-        examples: [example('Record command evidence', 'hadara evidence add-command --task T-0001 --summary "npm test passed" --result passed --json', 'After meaningful validation.')],
+        examples: [
+            example('Record command evidence', 'hadara evidence add-command --task T-0001 --summary "npm test passed" --result passed --category validation --json', 'After meaningful validation.')
+        ],
         related: ['evidence.list', 'evidence.lint', 'task.ready'],
+        notes: 'The collect response remains `hadara.evidence.collect.v1` with additive v2 metadata. A new add-command report schema id, check-id, and subject fields are deferred candidate scope.',
         conflictsWith: []
     },
     {
         id: 'evidence.list',
         command: 'hadara evidence list --task <task-id> [--limit <n>] [--include-private] [--json]',
-        summary: 'List public evidence index records for a Task Capsule.',
+        summary: 'List Task Capsule evidence ids, category/outcome metadata, and sanitized evidence summaries.',
         canonical: true,
         appearsInDefaultHelp: false,
         family: 'capsule-lifecycle',
@@ -511,7 +514,7 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         schemaVersion: 'hadara.evidence.list.v1',
         docs: ['docs/IMPLEMENTATION_SOP.md'],
-        examples: [example('List evidence', 'hadara evidence list --task T-0001 --json', 'When auditing a capsule evidence trail.')],
+        examples: [example('List evidence ids', 'hadara evidence list --task T-0001', 'Before copying a durable ev: id into --resolves or --supersedes.')],
         related: ['evidence.add-command', 'evidence.lint'],
         conflictsWith: []
     },
@@ -552,9 +555,10 @@ exports.HADARA_COMMAND_REGISTRY = [
         actor: 'operator',
         status: 'stable',
         schemaVersion: 'hadara.evidence.migration_preview.v1',
-        docs: ['docs/EVIDENCE_SEMANTIC_CONTRACT.md'],
+        docs: ['docs/EVIDENCE_SEMANTIC_CONTRACT.md', 'docs/CLI_JSON_CONTRACT.md'],
         examples: [example('Preview evidence migration', 'hadara evidence migrate --task T-0001 --to v2 --json', 'When older evidence files need migration.')],
         related: ['evidence.lint', 'protocol.remediate'],
+        notes: 'This is an operator-selected JSONL migration surface, not evidence rebuild. 0.3.2 does not register or implement `hadara evidence rebuild`; `EVIDENCE.md` remains a non-canonical human summary.',
         conflictsWith: []
     },
     {
@@ -600,7 +604,7 @@ exports.HADARA_COMMAND_REGISTRY = [
     {
         id: 'ci.gate',
         command: 'hadara ci gate [--mode advisory|strict] [--task <task-id>] [--allow-empty] [--json]',
-        summary: 'Evaluate CI-style task proof gates.',
+        summary: 'Evaluate CI-style task proof gates with advisory state consistency signals.',
         canonical: true,
         appearsInDefaultHelp: false,
         family: 'proof-diagnostics',
@@ -614,7 +618,28 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         docs: ['docs/IMPLEMENTATION_SOP.md'],
         examples: [example('Run strict CI gate', 'hadara ci gate --mode strict --task T-0001 --json', 'In automated validation paths.')],
-        related: ['task.ready', 'proof.status'],
+        related: ['task.ready', 'proof.status', 'state.verify'],
+        conflictsWith: []
+    },
+    {
+        id: 'state.verify',
+        command: 'hadara state verify [--json]',
+        summary: 'Read the state consistency projection and concise drift issues.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'proof-diagnostics',
+        scope: 'project',
+        lifecycleStage: 'ready',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'stable',
+        schemaVersion: 'hadara.stateProjection.v1',
+        docs: ['docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        examples: [example('Verify state drift', 'hadara state verify --json', 'Before close or when shared-doc state looks inconsistent.')],
+        related: ['status', 'protocol.doctor', 'ci.gate'],
         conflictsWith: []
     },
     commandEntry({
@@ -677,7 +702,7 @@ exports.HADARA_COMMAND_REGISTRY = [
         schemaVersion: 'hadara.protocol.consistency.v1',
         docs: ['docs/IMPLEMENTATION_SOP.md'],
         examples: [example('Run protocol doctor', 'hadara protocol doctor --scope all --json', 'When project protocol files may be inconsistent.')],
-        related: ['protocol.remediate', 'doctor'],
+        related: ['protocol.remediate', 'doctor', 'state.verify'],
         conflictsWith: []
     }),
     commandEntry({
@@ -1185,7 +1210,7 @@ exports.HADARA_COMMAND_REGISTRY = [
         schemaVersion: 'hadara.ops.status.v1',
         docs: ['docs/PROJECT_STATE.md'],
         examples: [example('Read status', 'hadara status --json', 'When checking project health and active task signals.')],
-        related: ['ops.status', 'doctor'],
+        related: ['ops.status', 'doctor', 'state.verify'],
         conflictsWith: []
     }),
     commandEntry({

package/dist/services/ci-gate.js

@@ -9,6 +9,7 @@ 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 state_projection_1 = require("./state-projection");
 const task_capsule_1 = require("../task/task-capsule");
 function createCiGateReport(projectRoot, mode, options = {}) {
     const allowEmpty = options.allowEmpty ?? false;
@@ -29,6 +30,27 @@ function createCiGateReport(projectRoot, mode, options = {}) {
         const target = issue.severity === 'error' ? blockers : warnings;
         target.push({ severity: issue.severity, source: 'protocol', code: issue.code, message: issue.message, path: issue.path });
     }
+    const stateProjection = (0, state_projection_1.createStateProjectionReport)(projectRoot);
+    const stateConsistency = (0, state_projection_1.toStateProjectionAdvisory)(stateProjection, 10);
+    checks.push({
+        id: 'state:consistency',
+        source: 'state',
+        ok: true,
+        summary: stateConsistency.consistent
+            ? 'State consistency projection found no drift.'
+            : `State consistency projection is advisory: warnings ${stateConsistency.issueCounts.warning}, errors ${stateConsistency.issueCounts.error}.`
+    });
+    for (const issue of stateConsistency.issues) {
+        warnings.push({
+            severity: issue.severity,
+            source: 'state',
+            code: issue.code,
+            message: issue.message,
+            taskId: issue.taskId,
+            path: issue.path,
+            fixHint: issue.fixHint
+        });
+    }
     for (const task of tasks) {
         const evidence = (0, evidence_lint_1.createEvidenceLintReport)(projectRoot, task.id);
         checks.push({
@@ -63,6 +85,7 @@ function createCiGateReport(projectRoot, mode, options = {}) {
         ok: mode === 'advisory' ? true : blockers.length === 0,
         mode,
         scope: { ...(options.taskId ? { taskId: options.taskId } : {}), taskCount: tasks.length, allowEmpty },
+        stateConsistency,
         checks,
         blockers,
         warnings

package/dist/services/docs-registry.js

@@ -14,6 +14,7 @@ exports.registryJson = registryJson;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const managed_sections_1 = require("./managed-sections");
+const markdown_table_1 = require("./markdown-table");
 exports.DOCS_REGISTRY_PATH = '.hadara/docs-registry.json';
 const VALID_STATUSES = ['canonical', 'active', 'reference', 'historical', 'superseded', 'archived'];
 const VALID_READ_WHEN = ['session-start', 'task-start', 'task-close', 'release-work', 'docs-work', 'debugging', 'integration-work', 'only-when-linked', 'never-default'];
@@ -294,7 +295,8 @@ function parseRequiredReading(projectRoot) {
     const found = new Set();
     for (const file of files) {
         const text = node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, file)) ? node_fs_1.default.readFileSync(node_path_1.default.join(projectRoot, file), 'utf8') : '';
-        for (const match of text.matchAll(/`([^`]+\.(?:md|MD))`/g)) {
+        const requiredReading = (0, markdown_table_1.readMarkdownSection)(text, '## Required Reading');
+        for (const match of requiredReading.matchAll(/`([^`]+\.(?:md|MD))`/g)) {
             const value = normalizePath(match[1]);
             if (value !== 'AGENTS.md' && !value.startsWith('docs/') && value !== '.hadara/context/HADARA_CONTEXT.md')
                 continue;