hadara 0.3.1-rc.1 → 0.3.2

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <img alt="Stable npm release" src="https://img.shields.io/badge/npm-0.3.0-blue">
-  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.1--rc.1-orange">
+  <img alt="Stable npm release" src="https://img.shields.io/badge/npm-0.3.2-blue">
+  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.2-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>
@@ -24,24 +24,24 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 Current stable npm release:
 
 ```text
-hadara@0.3.0
+hadara@0.3.2
 ```
 
 Current release candidate:
 
 ```text
-hadara@0.3.1-rc.1
+hadara@0.3.2-rc.0
 ```
 
-The 0.3.1-rc.1 line is the Phase 8 State Governance release candidate. It hardens status-token vocabulary, document ownership/write boundaries, handoff close-state handling, installed-package finding guidance, and state consistency verification surfaces after the stable 0.3.0 publish/recycle.
+The 0.3.2 line is the Evidence v2 refactor release. It hardens evidence writer metadata, exact resolution markers, durable evidence id discovery, canonical/derived evidence boundaries, and release-facing docs after the 0.3.1 post-publish recycle.
 
-Phase 8.x labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.0` package remains the default install target; the `0.3.1-rc.1` package is for explicit release-candidate evaluation.
+Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.2` source is prepared for approval-gated npm publish; the `0.3.2-rc.0` package remains the prior release-candidate evaluation build until stable publish is executed.
 
 | Surface | Status |
 |---|---|
-| Current stable | [`hadara@0.3.0`](docs/RELEASE_NOTES.md#030) |
-| Current RC | [`hadara@0.3.1-rc.1`](docs/RELEASE_NOTES.md#031-rc1) |
-| Previous RC | [`hadara@0.3.0-rc.2`](docs/RELEASE_NOTES.md#030-rc2) |
+| Current stable | [`hadara@0.3.2`](docs/RELEASE_NOTES.md#032) |
+| Current RC | [`hadara@0.3.2-rc.0`](docs/RELEASE_NOTES.md#032-rc0) |
+| Previous RC | [`hadara@0.3.1-rc.1`](docs/RELEASE_NOTES.md#031-rc1) |
 | Historical RCs | See [Release Notes](docs/RELEASE_NOTES.md). |
 | GitHub Release | Secondary target, approval-gated. |
 | Docker image | Deferred. |
@@ -57,7 +57,7 @@ Requires Node.js 22.
 Install the stable release:
 
 ```bash
-npm install -g hadara@0.3.0
+npm install -g hadara@0.3.2
 hadara help
 hadara doctor --json
 ```
@@ -65,26 +65,26 @@ hadara doctor --json
 Run without a global install:
 
 ```bash
-npx hadara@0.3.0 help
-npx hadara@0.3.0 doctor --json
+npx hadara@0.3.2 help
+npx hadara@0.3.2 doctor --json
 ```
 
 Evaluate the release candidate explicitly:
 
 ```bash
-npm install -g hadara@0.3.1-rc.1
-npx hadara@0.3.1-rc.1 help
+npm install -g hadara@0.3.2-rc.0
+npx hadara@0.3.2-rc.0 help
 ```
 
 For release or recycle evidence, prefer an isolated prefix install when PATH, global installs, or `npx` cache behavior may be stale:
 
 ```bash
 tmp="$(mktemp -d)"
-npm --prefix "$tmp" install hadara@0.3.0
+npm --prefix "$tmp" install hadara@0.3.2
 "$tmp/node_modules/.bin/hadara" version --json
 ```
 
-`npx hadara@0.3.0 ...` remains convenient for normal use. The isolated installed-bin path is stronger proof that the published package installed and executed from the intended package tree.
+`npx hadara@0.3.2 ...` remains convenient for normal use. The isolated installed-bin path is stronger proof that the published package installed and executed from the intended package tree.
 
 ## What HADARA Gives You
 
@@ -128,7 +128,7 @@ The primary path is intentionally small:
 hadara task next --json
 hadara task create "implement a focused change" --json
 hadara task status --task T-XXXX --json
-hadara evidence add-command --task T-XXXX --summary "..." --result passed --idempotency-key "command:T-XXXX:check" --json
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --category validation --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.
@@ -139,6 +139,19 @@ hadara task audit-close --task T-XXXX --json
 hadara handoff suggest --task T-XXXX --json
 ```
 
+When `evidence add-command` uses both legacy `--result` and v2 `--outcome`, matching outcomes must agree with the legacy result. `recorded` and `not-applicable` outcomes keep legacy result `unknown`; incompatible combinations fail before evidence is appended.
+
+Use `hadara evidence list --task T-XXXX` to discover evidence ids before writing exact resolution markers. Text output shows `[id] time | category/outcome | visibility | summary`; JSON output includes `id`, `idSource`, `idStability`, `persistedSchemaVersion`, `category`, `outcome`, and `tags`. For long-lived references, copy only durable persisted `ev:` ids:
+
+```bash
+hadara evidence list --task T-XXXX
+hadara evidence add-command --task T-XXXX --summary "Fix verified" --result passed --category validation --resolves ev:T-XXXX:aaaaaaaaaaaaaaaaaaaaaaaa --json
+```
+
+Legacy compatibility ids are inspection-only and are not the preferred durable reference for `resolves:` or `supersedes:` examples.
+
+Deferred Evidence v2 scope is explicit: rebuild preview/execute, `check-id`, `subject`, and a new add-command report schema id are future candidates, not current command behavior. Treat `evidence.jsonl` as canonical append-only evidence and `EVIDENCE.md` as a non-canonical human summary.
+
 Optional workflow compression is read-only. Use it separately when you want a compact current-stage report and next recommended action:
 
 ```bash
@@ -232,7 +245,7 @@ Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay
 
 ## Safety Boundaries
 
-HADARA 0.3.1-rc.1 is not:
+HADARA 0.3.2 is not:
 
 - a full agent runtime;
 - Rack/enterprise behavior;
@@ -268,6 +281,12 @@ AGENTS.md
 
 Portable/local state is not committed. Project docs, Task Capsules, and reduced public evidence are committed when they represent reproducible context.
 
+### Evidence Rebuild Boundary
+
+`evidence.jsonl` is the canonical Task Capsule evidence source. `EVIDENCE.md` is a non-canonical human summary that can help review validation history, but it must not be treated as the source of truth for rebuild, migration, or resolution logic.
+
+0.3.2 does not implement `hadara evidence rebuild --json` or an execute mode. Future rebuild work must first define whether a difference is formatting regeneration, managed-section drift, or data inconsistency before reporting `wouldChange`. Any later write-capable rebuild flow must be dry-run-first, reviewed, and before-hash guarded before it rewrites derived Markdown.
+
 ## Development / Contributing
 
 Initialize a project:

package/dist/cli/evidence-json.js

@@ -33,11 +33,18 @@ function createEvidenceCollectReport(projectRoot, input) {
             summary: input.summary,
             result: input.result,
             visibility: input.visibility,
+            category: input.category,
+            outcome: input.outcome,
+            tags: input.tags,
             idempotencyKey: input.idempotencyKey
         });
     }
     catch (error) {
-        if (error instanceof workspace_1.WorkspaceFileError || error instanceof evidence_1.EvidenceArtifactPolicyError || error instanceof evidence_1.EvidenceAppendLockError) {
+        if (error instanceof workspace_1.WorkspaceFileError ||
+            error instanceof evidence_1.EvidenceArtifactPolicyError ||
+            error instanceof evidence_1.EvidenceAppendLockError ||
+            error instanceof evidence_1.EvidenceResultOutcomeMismatchError ||
+            error instanceof evidence_1.EvidenceTaskDirectoryError) {
             return {
                 schemaVersion: 'hadara.evidence.collect.v1',
                 command: 'evidence.collect',

package/dist/cli/evidence.js

@@ -4,6 +4,8 @@ exports.handleEvidenceCommand = handleEvidenceCommand;
 exports.parseEvidenceKind = parseEvidenceKind;
 exports.parseEvidenceResult = parseEvidenceResult;
 exports.parseEvidenceVisibility = parseEvidenceVisibility;
+exports.parseEvidenceCategory = parseEvidenceCategory;
+exports.parseEvidenceOutcome = parseEvidenceOutcome;
 const evidence_1 = require("../evidence/evidence");
 const evidence_json_1 = require("./evidence-json");
 const evidence_lint_1 = require("../services/evidence-lint");
@@ -24,7 +26,7 @@ function handleEvidenceCommand(input) {
         }
         else {
             for (const record of report.records) {
-                console.log(`${record.time} | ${(0, evidence_1.persistedEvidenceKind)(record)} | ${(0, evidence_1.persistedEvidenceResult)(record)} | ${record.visibility} | ${record.summary}`);
+                console.log(`[${evidenceListDisplayId(record)}] ${record.time} | ${evidenceListCategory(record)}/${evidenceListOutcome(record)} | ${record.visibility} | ${record.summary}`);
             }
             for (const issue of report.issues) {
                 console.log(`[${issue.severity}] ${issue.code}: ${issue.message}`);
@@ -76,9 +78,30 @@ function handleEvidenceCommand(input) {
     if (sub === 'add-command') {
         const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
         const summary = (0, args_1.getStringOption)(input.args, '--summary') ?? 'Command completed.';
-        const result = parseEvidenceResult((0, args_1.getStringOption)(input.args, '--result', 'unknown') ?? 'unknown');
+        const outcome = parseOptionalEvidenceOutcome((0, args_1.getStringOption)(input.args, '--outcome'));
+        const explicitResult = (0, args_1.getStringOption)(input.args, '--result');
+        const result = parseEvidenceResult(explicitResult ?? outcomeToLegacyResult(outcome));
+        const resultOutcomeIssue = (0, evidence_1.validateEvidenceResultOutcomeCompatibility)({ result, outcome });
+        if (resultOutcomeIssue) {
+            const report = {
+                schemaVersion: 'hadara.evidence.collect.v1',
+                command: 'evidence.add-command',
+                ok: false,
+                issues: [resultOutcomeIssue]
+            };
+            if (input.jsonOutput) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                console.log(`[error] ${resultOutcomeIssue.code}: ${resultOutcomeIssue.message}`);
+            }
+            process.exitCode = 6;
+            return true;
+        }
         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');
+        const category = parseOptionalEvidenceCategory((0, args_1.getStringOption)(input.args, '--category'));
+        const tags = resolutionTagsFromArgs(input.args);
         if (input.jsonOutput) {
             const report = (0, evidence_json_1.createEvidenceCollectReport)(input.projectRoot, {
                 taskId,
@@ -86,6 +109,9 @@ function handleEvidenceCommand(input) {
                 summary,
                 result,
                 visibility,
+                category,
+                outcome,
+                tags,
                 idempotencyKey
             });
             console.log(JSON.stringify({ ...report, command: 'evidence.add-command' }, null, 2));
@@ -93,7 +119,7 @@ function handleEvidenceCommand(input) {
                 process.exitCode = 6;
         }
         else {
-            const appendResult = (0, evidence_1.appendEvidenceWithResult)(input.projectRoot, { taskId, kind: 'command-log', summary, result, visibility, idempotencyKey });
+            const appendResult = (0, evidence_1.appendEvidenceWithResult)(input.projectRoot, { taskId, kind: 'command-log', summary, result, visibility, category, outcome, tags, idempotencyKey });
             if (appendResult.existing) {
                 console.log(`[HADARA] Command evidence already exists: ${persistedEvidenceId(appendResult.evidence)}`);
             }
@@ -140,6 +166,15 @@ function handleEvidenceCommand(input) {
 function persistedEvidenceId(record) {
     return record.schemaVersion === 'hadara.evidence.v2' && record.id ? record.id : 'evidence.jsonl';
 }
+function evidenceListDisplayId(record) {
+    return record.id;
+}
+function evidenceListCategory(record) {
+    return record.category;
+}
+function evidenceListOutcome(record) {
+    return record.outcome;
+}
 function parseEvidenceKind(value) {
     if (['test-log', 'command-log', 'diff-summary', 'screenshot', 'note'].includes(value)) {
         return value;
@@ -159,3 +194,46 @@ function parseEvidenceVisibility(value, privateFlag = false) {
         return value;
     throw new Error(`unsupported evidence visibility: ${value}`);
 }
+function parseEvidenceCategory(value) {
+    if (['validation', 'implementation', 'release', 'security', 'policy', 'operation', 'decision', 'handoff', 'audit', 'note', 'observation'].includes(value)) {
+        return value;
+    }
+    throw new Error(`unsupported evidence category: ${value}`);
+}
+function parseEvidenceOutcome(value) {
+    if (value === 'passed' || value === 'failed' || value === 'blocked' || value === 'unknown' || value === 'recorded' || value === 'not-applicable') {
+        return value;
+    }
+    throw new Error(`unsupported evidence outcome: ${value}`);
+}
+function parseOptionalEvidenceCategory(value) {
+    return value ? parseEvidenceCategory(value) : undefined;
+}
+function parseOptionalEvidenceOutcome(value) {
+    return value ? parseEvidenceOutcome(value) : undefined;
+}
+function outcomeToLegacyResult(outcome) {
+    if (outcome === 'passed' || outcome === 'failed' || outcome === 'blocked' || outcome === 'unknown')
+        return outcome;
+    return 'unknown';
+}
+function resolutionTagsFromArgs(args) {
+    const tags = [];
+    for (const id of getRepeatedStringOptions(args, '--resolves'))
+        tags.push(`resolves:${id}`);
+    for (const id of getRepeatedStringOptions(args, '--supersedes'))
+        tags.push(`supersedes:${id}`);
+    return tags.length > 0 ? tags : undefined;
+}
+function getRepeatedStringOptions(args, option) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== option)
+            continue;
+        const value = args[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`missing value for ${option}`);
+        values.push(value);
+    }
+    return values;
+}

package/dist/cli/init.js

@@ -1118,7 +1118,7 @@ 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 evidence add-command --task T-XXXX --summary "..." --result passed --category validation --idempotency-key "command:T-XXXX:check" --json
 
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json
@@ -1140,7 +1140,7 @@ hadara task audit-close --task T-XXXX --json
 |---|---|---|
 | \`task next\` | Read-only | Recommends work; does not create tasks. |
 | \`task status\` | Read-only | \`ok\` means report generation succeeded; readiness is in \`state.ready\`, \`summary.blockers\`, and \`issues\`. |
-| \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands; optional \`--idempotency-key\` prevents duplicate same-key records. |
+| \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands; optional \`--category\`/\`--outcome\`/\`--resolves\`/\`--supersedes\` enrich v2 metadata, result/outcome mismatches are rejected, and 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. |
@@ -1165,8 +1165,10 @@ Before running \`task ready\` and \`task close\`, finish all close-source edits:
 1. Do not hand-edit Task Capsule \`evidence.jsonl\`.
 2. Append evidence through HADARA commands so schema, visibility, and artifact-safety checks run consistently.
 3. Record failed or blocked checks honestly. Do not replace them later with optimistic summaries; add newer evidence that explains the fix or residual risk.
-4. Use \`hadara evidence add-command --task <task-id> --summary <text> --result passed|failed|blocked|unknown --json\` for command results when no artifact file is attached. 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.
+4. Use \`hadara evidence list --task <task-id>\` to discover evidence ids and copy durable persisted \`ev:\` ids for long-lived \`--resolves\` or \`--supersedes\` references. Legacy compatibility ids are inspection-only and are not the preferred durable reference.
+5. 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 \`--category <category>\` or \`--outcome <outcome>\` when summary heuristics are not precise enough; if both \`--result\` and \`--outcome\` are supplied, matching outcomes must match the legacy result, while \`recorded\` and \`not-applicable\` require \`--result unknown\` or no explicit result. Use \`--resolves <ev:evidence-id>\` or \`--supersedes <ev:evidence-id>\` for exact v2 resolution markers from passed or recorded follow-up evidence, and \`--idempotency-key <key>\` when rerunning the same logical check should report one durable evidence identity instead of appending duplicates.
+6. Use \`hadara evidence lint --task <task-id> --json\` when evidence drift is suspected or before close if evidence files were touched manually by mistake.
+7. Treat Task Capsule \`evidence.jsonl\` as canonical append-only evidence and \`EVIDENCE.md\` as a non-canonical human summary. \`hadara evidence rebuild\` is not implemented in this scaffold; future rebuild work must define whether \`wouldChange\` means formatting regeneration, managed-section drift, or data inconsistency before preview semantics are safe, and any execute mode must be dry-run-first and before-hash guarded.
 
 ## Session End
 
@@ -1336,7 +1338,7 @@ 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 evidence add-command --task T-XXXX --summary "..." --result passed --category validation --idempotency-key "command:T-XXXX:check" --json
 
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json
@@ -1417,7 +1419,7 @@ Evidence outcome tokens are \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`
 |---|---|
 | \`TASK.md\` status metadata, \`## Status\`, and Status History | Command-owned for finish bookkeeping; worker-owned before finish. |
 | \`docs/TASK_BOARD.md\` ID/title/status/capsule cells | Command-owned by \`task finish\`; Notes and extra cells are mixed/human-owned. |
-| \`EVIDENCE.md\` and \`evidence.jsonl\` | Evidence writer-owned; do not hand-edit \`evidence.jsonl\`. |
+| \`EVIDENCE.md\` and \`evidence.jsonl\` | Evidence writer-owned; do not hand-edit \`evidence.jsonl\`. Treat \`evidence.jsonl\` as canonical and \`EVIDENCE.md\` as a non-canonical human summary; evidence rebuild is not implemented in this scaffold and any future execute mode must be dry-run-first and before-hash guarded. |
 | \`HANDOFF.md\` managed current-state table | Managed/mixed; persist \`TaskStatus\` only. \`CloseState\` is derived by status/audit/proof/state read models and should not be written into close-source handoff tables. |
 | Shared state docs | Mixed/human-owned; update before close when they are close-source relevant. |
 | \`.hadara/docs-registry.json\` and \`docs/DOC_REGISTRY.md\` | Docs registry-owned; registry mutations should stay dry-run-first or explicitly scoped. |
@@ -1439,7 +1441,7 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 | \`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. |
+| \`evidence add-command\` | Write | Appends operator-supplied command-log evidence. It does not execute shell commands or capture stdout/stderr; optional \`--category\`/\`--outcome\`/\`--resolves\`/\`--supersedes\` enrich v2 metadata, result/outcome mismatches are rejected, and 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. |
@@ -1453,7 +1455,9 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 - \`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.
+- \`evidence list\` is the supported evidence id discovery surface. Text output shows \`[id] time | category/outcome | visibility | summary\`; JSON records expose \`id\`, \`idSource\`, \`idStability\`, \`persistedSchemaVersion\`, \`category\`, \`outcome\`, and \`tags\`. Use durable persisted \`ev:\` ids for long-lived \`--resolves\` and \`--supersedes\` references. Legacy compatibility ids are inspection-only and are not the preferred durable reference.
+- \`evidence add-command\` records an operator-supplied command result; it does not run the command. \`--category\` and \`--outcome\` set persisted v2 metadata explicitly, while \`--result\` remains the legacy-compatible command result. When both are supplied, \`--result\` must match \`--outcome\` for \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`; \`recorded\` and \`not-applicable\` require \`--result unknown\` or no explicit \`--result\`. \`--resolves\` and \`--supersedes\` append exact v2 resolution tags from passed or recorded follow-up evidence. \`--idempotency-key\` is optional; when supplied, same-key repeats return the existing record without appending duplicate Markdown or JSONL rows.
+- Evidence v2 deferred scope remains explicit: rebuild preview/execute, \`check-id\`, \`subject\`, and a new add-command report schema id are future candidates. Do not infer those commands or schema changes from the current \`evidence list\` and \`evidence add-command\` ergonomics.
 - \`task finish\` may update only the Task Capsule \`TASK.md\` status and the matching \`docs/TASK_BOARD.md\` row's command-owned cells: \`ID\`, \`Title\`, \`Status\`, and \`Capsule\`. It preserves human/mixed-owned \`Notes\` and any extra cells.
 - \`task close\` may append only close evidence. It must not update status docs, Task Board rows, handoff, Project State, roadmap docs, or arbitrary evidence.
 - After \`task close --execute --json\`, close-source document edits intentionally invalidate the previous close proof. Make those edits before close, or rerun ready/close/audit if the edit is unavoidable.

package/dist/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/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/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: []
     },
     {

package/dist/services/evidence-list.js

@@ -8,6 +8,7 @@ exports.parseEvidenceIndexFile = parseEvidenceIndexFile;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const redaction_1 = require("../core/redaction");
+const normalizer_1 = require("../evidence/normalizer");
 const task_capsule_1 = require("../task/task-capsule");
 const DEFAULT_LIMIT = 50;
 function createEvidenceListReport(projectRoot, input) {
@@ -73,7 +74,7 @@ function parseEvidenceIndexFile(indexPath, taskId) {
                     });
                     return;
                 }
-                records.push(normalizeEvidenceIndexRecord(record));
+                records.push(normalizeEvidenceIndexRecord(record, index + 1));
                 return;
             }
             issues.push({
@@ -132,9 +133,10 @@ function isEvidenceV2IndexRecord(value) {
         isEvidenceResult(record.legacy.result) &&
         (record.legacy.evidencePath === undefined || typeof record.legacy.evidencePath === 'string'));
 }
-function normalizeEvidenceIndexRecord(record) {
+function normalizeEvidenceIndexRecord(record, sourceLine) {
     if (record.schemaVersion === 'hadara.evidence.v2')
-        return normalizeEvidenceV2IndexRecord(record);
+        return normalizeEvidenceV2IndexRecord(record, sourceLine);
+    const normalizedRecord = (0, normalizer_1.normalizeEvidenceRecord)(record, { lineNumber: sourceLine });
     const normalized = {
         schemaVersion: 'hadara.evidence.v1',
         time: record.time,
@@ -147,13 +149,29 @@ function normalizeEvidenceIndexRecord(record) {
     if (record.visibility === 'public' && record.evidencePath) {
         normalized.evidencePath = record.evidencePath;
     }
-    return normalized;
+    return {
+        ...normalized,
+        id: normalizedRecord.id,
+        sourceLine,
+        idSource: 'line-fallback',
+        idStability: 'unstable-on-reorder',
+        persistedSchemaVersion: 'hadara.evidence.v1',
+        category: normalizedRecord.category,
+        outcome: normalizedRecord.outcome,
+        tags: normalizedRecord.tags,
+        legacy: {
+            kind: normalized.kind,
+            result: normalized.result,
+            ...(normalized.evidencePath ? { evidencePath: normalized.evidencePath } : {})
+        }
+    };
 }
-function normalizeEvidenceV2IndexRecord(record) {
+function normalizeEvidenceV2IndexRecord(record, sourceLine) {
     return {
         schemaVersion: 'hadara.evidence.v2',
         id: record.id,
-        ...(record.sourceLine ? { sourceLine: record.sourceLine } : {}),
+        sourceLine: record.sourceLine ?? sourceLine,
+        persistedSchemaVersion: 'hadara.evidence.v2',
         fingerprint: record.fingerprint,
         idSource: 'persisted',
         idStability: 'durable',

package/dist/tui/read-model.js

@@ -349,7 +349,7 @@ function createSelectedTaskReadModel(projectRoot, summary, options = {}) {
 }
 function createFastSelectedTaskReadModel(projectRoot, summary, options) {
     const detail = createTaskDocumentReadReportFromSummary(projectRoot, summary, { includePrivate: false });
-    const evidenceIndex = detail.evidenceIndex ?? [];
+    const evidenceIndex = (detail.evidenceIndex ?? []);
     const evidence = limitEvidenceListReport({
         schemaVersion: 'hadara.evidence.list.v1',
         command: 'evidence.list',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadara",
-  "version": "0.3.1-rc.1",
+  "version": "0.3.2",
   "private": false,
   "license": "MIT",
   "description": "Portable AI-assisted development workbench for evidence-backed task capsules, handoffs, and release gates.",