hadara 0.3.0 → 0.3.2-rc.0

package/README.md

@@ -6,7 +6,7 @@
 
 <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.0-orange">
+  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.2--rc.0-orange">
   <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>
@@ -27,26 +27,22 @@ Current stable npm release:
 hadara@0.3.0
 ```
 
-Previous npm release candidate:
+Current release candidate:
 
 ```text
-hadara@0.3.0-rc.2
+hadara@0.3.2-rc.0
 ```
 
-The 0.3.0 line is the Phase 7 Surface Refactor. It organizes HADARA's existing task, evidence, proof, lifecycle, release, and document surfaces so agents can distinguish primary lifecycle commands, diagnostics, advanced surfaces, canonical documents, historical documents, and safe Markdown update boundaries.
+The 0.3.2-rc.0 line is the Evidence v2 refactor release candidate. 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 7.x labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.0` package is published through the approval-gated release path with explicit operator confirmation.
+Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.0` package remains the default install target; the `0.3.2-rc.0` package is for explicit release-candidate evaluation.
 
 | Surface | Status |
 |---|---|
-| npm package | Primary release target. |
-| `hadara@0.2.0-rc.1` | Previous published npm RC. |
-| `hadara@0.2.0-rc.2` | Previous published npm RC. |
-| `hadara@0.2.0-rc.3` | Previous published npm RC. |
-| `hadara@0.3.0-rc.0` | Previous published npm RC; package metadata lacks the intended discovery fields. |
-| `hadara@0.3.0-rc.1` | Previous published npm RC; T-0301 publish evidence verified `npm view` returned `0.3.0-rc.1`. |
-| `hadara@0.3.0-rc.2` | Previous published npm RC; T-0310 publish evidence verified `npm view` returned `0.3.0-rc.2`. |
-| `hadara@0.3.0` | Current stable npm release. |
+| Current stable | [`hadara@0.3.0`](docs/RELEASE_NOTES.md#030) |
+| 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. |
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
@@ -73,6 +69,23 @@ npx hadara@0.3.0 help
 npx hadara@0.3.0 doctor --json
 ```
 
+Evaluate the release candidate explicitly:
+
+```bash
+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
+"$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.
+
 ## What HADARA Gives You
 
 | Capability | Purpose |
@@ -115,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.
@@ -126,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
@@ -219,7 +245,7 @@ Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay
 
 ## Safety Boundaries
 
-HADARA 0.3.0 is not:
+HADARA 0.3.2-rc.0 is not:
 
 - a full agent runtime;
 - Rack/enterprise behavior;
@@ -255,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:
@@ -292,19 +324,6 @@ node dist/cli/main.js doctor --json
 npm run check
 ```
 
-For HADARA-dev itself, Docker is the preferred validation path because host `node_modules` on mounted workspaces can be unreliable:
-
-```bash
-npm run dev:docker-check
-npm run dev:docker-sync-build
-```
-
-Focused validation:
-
-```bash
-npm run test:focused -- tests/unit/release-dry-run.test.ts
-```
-
 Optional integrations are not generated by `hadara init` and are not part of the default scaffold:
 
 ```bash

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

@@ -571,7 +571,7 @@ function sopRequiredReadingRowsForProfile(profile) {
         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.']);
     }
     if (profile === 'governed') {
-        rows.push(['`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants and special checks.'], ['`docs/REFACTOR_LOG.md`', 'Refactor, migration, removal, or replacement work', 'Project-level refactor history.'], ['`docs/ROADMAP.md`', 'Roadmap, milestone, or scope planning', 'Longer-term priorities and deferred work.']);
+        rows.push(['`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants and special checks.'], ['`docs/ROADMAP.md`', 'Roadmap, milestone, or scope planning', 'Longer-term priorities and deferred work.']);
     }
     return rows;
 }
@@ -587,7 +587,7 @@ function agentsRequiredReadingRowsForProfile(profile) {
         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.' });
     }
     if (profile === 'governed') {
-        rows.push({ document: '`docs/SECURITY_MODEL.md`', when: 'Security, secret, permission, or evidence-safety work', purpose: 'Project security invariants.' }, { document: '`docs/REFACTOR_LOG.md`', when: 'Refactor, migration, removal, or replacement work', purpose: 'Project-level refactor history.' }, { document: '`docs/ROADMAP.md`', when: 'Roadmap, milestone, or scope planning', purpose: 'Longer-term priorities and deferred work.' });
+        rows.push({ document: '`docs/SECURITY_MODEL.md`', when: 'Security, secret, permission, or evidence-safety work', purpose: 'Project security invariants.' }, { document: '`docs/ROADMAP.md`', when: 'Roadmap, milestone, or scope planning', purpose: 'Longer-term priorities and deferred work.' });
     }
     return rows;
 }
@@ -710,7 +710,7 @@ function requiredDocsForProfile(profile) {
         docs.push('docs/ARCHITECTURE.md', 'docs/DEVELOPMENT_SLICES.md', 'docs/DECISIONS.md', 'docs/TEST_STRATEGY.md');
     }
     if (profile === 'governed') {
-        docs.push('docs/SECURITY_MODEL.md', 'docs/REFACTOR_LOG.md', 'docs/ROADMAP.md');
+        docs.push('docs/SECURITY_MODEL.md', 'docs/ROADMAP.md');
     }
     return docs;
 }
@@ -973,9 +973,6 @@ function createImplementationSopDoc(spec) {
     if (spec.docs.securityModel) {
         requiredReadingRows.push(['`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants and special checks.']);
     }
-    if (spec.docs.refactorLog) {
-        requiredReadingRows.push(['`docs/REFACTOR_LOG.md`', 'Refactor, migration, removal, or replacement work', 'Project-level refactor history.']);
-    }
     if (spec.docs.roadmap) {
         requiredReadingRows.push(['`docs/ROADMAP.md`', 'Roadmap, milestone, release, or scope planning', 'Longer-term priorities and deferred work.']);
     }
@@ -1095,6 +1092,16 @@ Keep capsule docs current as work changes:
 
 Parallelize read-only discovery, \`rg\`/file inspection, independent validation commands, package or registry metadata inspection, read-only diagnostics, and draft preparation before writes. Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board writes, Project State writes, Agent Handoff writes, before-hash execute operations, \`task finish --execute\`, \`task close --execute\`, and release artifact or publish operations.
 
+## Status Token And Document Ownership Policy
+
+Use distinct token families for persistent task state, close proof state, document registry state, and evidence outcomes. \`TaskStatus\` belongs to Task Capsule metadata, \`TASK.md\` Status/Status History, and command-owned \`docs/TASK_BOARD.md\` cells. Valid persistent task tokens are \`Draft\`, \`In Progress\`, \`Blocked\`, \`Done\`, \`Partial\`, \`Superseded\`, and \`Archived\`.
+
+\`CloseState\` is derived from close evidence and \`task audit-close\`; do not write close proof values as \`TaskStatus\`, and do not persist \`CloseState\` in task-local \`HANDOFF.md\` close-source current-state tables. Canonical close-state tokens are \`not-closed\`, \`closed-valid\`, \`closed-stale\`, \`closed-invalid\`, and \`unknown\`. Compatibility diagnostics such as \`close-evidence-found-invalid\`, \`close-evidence-malformed\`, and \`closed-with-drift-warnings\` are close-state details, not task status.
+
+\`DocStatus\` belongs only to the docs registry and uses \`canonical\`, \`active\`, \`reference\`, \`historical\`, \`superseded\`, and \`archived\`. Evidence outcomes are \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`; preserve failed or blocked evidence and append newer corrective evidence instead of rewriting history.
+
+Ownership boundaries follow the lifecycle command model. \`task finish --execute\` owns bounded status bookkeeping in \`TASK.md\` and command-owned \`docs/TASK_BOARD.md\` cells. \`task close --execute\` owns only close evidence append. Operators own close-source prose and shared state docs before close, then rerun ready/close/audit after any intentional close-source edit.
+
 ## Standard Task Workflow Loop
 
 The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. For ordinary implementation capsules, use this loop:
@@ -1111,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
@@ -1133,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. |
@@ -1158,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
 
@@ -1329,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
@@ -1353,6 +1362,68 @@ The close model has three separate phases: validation proves readiness, close re
 
 \`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.
 
+## Status Token And Ownership Policy
+
+HADARA uses separate token families for persistent state, derived proof state, document registry state, and evidence outcomes. Do not collapse these families into a single Markdown \`Status\` field.
+
+### TaskStatus
+
+\`TaskStatus\` is persistent task lifecycle state in \`TASK.md\` metadata, the \`## Status\` section, Status History rows, and the command-owned cells of \`docs/TASK_BOARD.md\`.
+
+| Token | Meaning | Writer |
+|---|---|---|
+| \`Draft\` | Task capsule exists but implementation is not started or not yet ready for done-level validation. | \`task create\`, worker docs |
+| \`In Progress\` | Work is actively being performed. | Worker docs |
+| \`Blocked\` | Work cannot proceed without a recorded blocker. | Worker docs |
+| \`Done\` | Scoped work is implemented and ready for done-level validation/close. | \`task finish --execute\` |
+| \`Partial\` | Deliberate partial completion with remaining scope deferred or split. | Worker/coordinator docs |
+| \`Superseded\` | Task has been replaced by another task or line. | Worker/coordinator docs |
+| \`Archived\` | Task is no longer active state and is retained only for history. | Worker/coordinator docs |
+
+Reserved non-TaskStatus strings include \`Closed\`, \`Ready\`, \`Approved\`, \`Complete\`, \`closed-valid\`, \`not-closed\`, and phrases such as \`Done pending lifecycle close\`. Use \`TaskStatus: Done\`; get close proof state from \`task status\`, \`task audit-close\`, proof status, or \`state verify\` read models.
+
+### CloseState
+
+\`CloseState\` is derived proof state from close evidence and \`task audit-close\`; it is not written as persistent \`TaskStatus\` and should not be stored in task-local \`HANDOFF.md\` current-state tables.
+
+| Canonical Token | Meaning |
+|---|---|
+| \`not-closed\` | No valid close proof has been recorded. |
+| \`closed-valid\` | Close evidence exists and audit reports current/fresh proof. |
+| \`closed-stale\` | Close evidence exists but source or validation hashes drifted after close. |
+| \`closed-invalid\` | Close-like evidence exists but audit reports invalid shape, failed result, or mismatch. |
+| \`unknown\` | The projection cannot determine close state. |
+
+Current compatibility read models may expose more specific diagnostic values such as \`close-evidence-found-invalid\`, \`close-evidence-malformed\`, or \`closed-with-drift-warnings\`. Treat those as CloseState diagnostics, not TaskStatus values.
+
+### DocStatus
+
+\`DocStatus\` is stored in the document registry only.
+
+| Token | Meaning |
+|---|---|
+| \`canonical\` | Core scaffold/current-state document. |
+| \`active\` | Active working document or task-work document. |
+| \`reference\` | Conditional reference document. |
+| \`historical\` | Historical context, never default required reading. |
+| \`superseded\` | Replaced by another registered document. |
+| \`archived\` | Retained only as archive candidate/history. |
+
+### EvidenceOutcome
+
+Evidence outcome tokens are \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`. Failed or blocked evidence must remain visible; add newer evidence that explains the fix or residual risk instead of editing old records.
+
+### Write Ownership
+
+| Surface | Ownership |
+|---|---|
+| \`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\`. 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. |
+
 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".
 
 ## Documentation Timing and Write Coordination
@@ -1370,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. |
@@ -1384,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.
@@ -1415,8 +1488,6 @@ function createAgentsDoc(spec) {
         requiredReadingRows.push([String(order++), '`docs/TEST_STRATEGY.md`', 'Validation planning or completion checks', 'Routine suites and special-case checks.']);
     if (spec.docs.securityModel)
         requiredReadingRows.push([String(order++), '`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants.']);
-    if (spec.docs.refactorLog)
-        requiredReadingRows.push([String(order++), '`docs/REFACTOR_LOG.md`', 'Refactor, migration, removal, or replacement work', 'Project-level refactor history.']);
     if (spec.docs.roadmap)
         requiredReadingRows.push([String(order++), '`docs/ROADMAP.md`', 'Roadmap, milestone, or scope planning', 'Longer-term priorities and deferred work.']);
     requiredReadingRows.push([String(order++), 'Active `tasks/T-*/TASK.md`', 'Working a task', 'Task-specific goal, scope, and status.'], [String(order++), 'Active Task Capsule docs', 'Working a task', 'Decisions, plan, context, acceptance, files, tests, risks, handoff, and evidence.'], [String(order++), 'Project-specific registered docs', 'When listed in `docs/IMPLEMENTATION_SOP.md`', 'Specs, contracts, or roadmap files explicitly added by this project.']);

package/dist/cli/main.js

@@ -173,6 +173,12 @@ async function main(args = process.argv.slice(2)) {
                 return;
             break;
         }
+        case 'state': {
+            const { handleStateCommand } = await Promise.resolve().then(() => __importStar(require('./state')));
+            if (handleStateCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
+                return;
+            break;
+        }
         case 'dashboard': {
             const { handleDashboardCommand } = await Promise.resolve().then(() => __importStar(require('./dashboard')));
             if (handleDashboardCommand({ args, projectRoot: paths.projectRoot }))

package/dist/cli/state.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleStateCommand = handleStateCommand;
+const state_projection_1 = require("../services/state-projection");
+function handleStateCommand(input) {
+    if (input.args[0] !== 'state' || input.args[1] !== 'verify')
+        return false;
+    const report = (0, state_projection_1.createStateProjectionReport)(input.projectRoot);
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log((0, state_projection_1.formatStateProjectionReport)(report));
+    }
+    return true;
+}

package/dist/cli/status.js

@@ -16,7 +16,7 @@ function handleOpsCommand(input) {
     return true;
 }
 function printStatus(projectRoot, jsonOutput) {
-    const report = (0, operations_status_service_1.createOpsStatusReport)(projectRoot);
+    const report = (0, operations_status_service_1.createOpsStatusReport)(projectRoot, { includeStateConsistency: true });
     if (jsonOutput) {
         console.log(JSON.stringify(report, null, 2));
     }

package/dist/core/schema.js

@@ -49,6 +49,7 @@ const release_gate_schema_json_1 = __importDefault(require("../schemas/release-g
 const release_publish_schema_json_1 = __importDefault(require("../schemas/release-publish.schema.json"));
 const runtime_version_schema_json_1 = __importDefault(require("../schemas/runtime-version.schema.json"));
 const smoke_evidence_summary_schema_json_1 = __importDefault(require("../schemas/smoke-evidence-summary.schema.json"));
+const state_projection_schema_json_1 = __importDefault(require("../schemas/state-projection.schema.json"));
 const task_audit_close_schema_json_1 = __importDefault(require("../schemas/task-audit-close.schema.json"));
 const task_close_schema_json_1 = __importDefault(require("../schemas/task-close.schema.json"));
 const task_complete_flow_schema_json_1 = __importDefault(require("../schemas/task-complete-flow.schema.json"));
@@ -115,6 +116,7 @@ const registeredSchemas = {
     'hadara.releasePublish.v1': release_publish_schema_json_1.default,
     'hadara.runtime.version.v1': runtime_version_schema_json_1.default,
     'hadara.smokeEvidenceSummary.v1': smoke_evidence_summary_schema_json_1.default,
+    'hadara.stateProjection.v1': state_projection_schema_json_1.default,
     'hadara.task.audit_close.v1': task_audit_close_schema_json_1.default,
     'hadara.task.close.v1': task_close_schema_json_1.default,
     'hadara.task.complete_flow.v1': task_complete_flow_schema_json_1.default,