hadara 0.2.0-rc.2 → 0.3.0-rc.0

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.2-blue">
+  <img alt="Release candidate" src="https://img.shields.io/badge/npm-0.3.0--rc.0-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>
@@ -14,30 +14,30 @@
 
 > Unbroken Context, Verified Development.
 
-HADARA is named from **Harness + Dara**. A harness safely binds and controls complex systems; Dara carries layered associations of holding, wisdom, durability, and continuity. HADARA binds non-deterministic LLM agent work into a production-oriented workflow through Task Capsules, Session Continuity, Policy Layers, Evidence Logs, and Handoff Protocols.
+HADARA binds non-deterministic LLM agent work into a production-oriented workflow through Task Capsules, Session Continuity, Policy Layers, Evidence Logs, and Handoff Protocols.
 
 This repository is both the HADARA source checkout and the HADARA protocol workspace used to build it.
 
 ## Release Status
 
-The current source checkout targets:
+Current release candidate:
 
 ```text
-hadara@0.2.0-rc.2
+hadara@0.3.0-rc.0
 ```
 
-T-0282 refreshes the npm release-candidate source state for `0.2.0-rc.2` after the init scaffold protocol guidance follow-up. T-0275 published the previous `0.2.0-rc.1` RC after the installed-package recycle fixes.
+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.
 
-Current publish boundaries:
+Phase 7.x labels are internal implementation phases, not npm release-candidate labels. Publishing `0.3.0-rc.0` or any later release still requires the approval-gated release path and explicit operator confirmation.
 
 | Surface | Status |
 |---|---|
 | npm package | Primary release target. |
-| `hadara@0.1.0-rc.0` | Published first RC. |
-| `hadara@0.2.0-rc.0` | Superseded internal publish candidate after recycle findings. |
-| `hadara@0.2.0-rc.1` | Current published npm RC until rc.2 is operator-published. |
-| `hadara@0.2.0-rc.2` | Current source version and next npm RC target. |
-| GitHub Release | Secondary target, still approval-gated. |
+| `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` | Current release candidate. |
+| GitHub Release | Secondary target, approval-gated. |
 | Docker image | Deferred. |
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
 | Installer scripts / USB launchers | Deferred. |
@@ -48,24 +48,21 @@ No release command should publish, create a GitHub Release, build Docker images,
 
 Requires Node.js 22.
 
-Install the current RC:
+Install this release candidate:
 
 ```bash
-npm install -g hadara@0.2.0-rc.2
+npm install -g hadara@0.3.0-rc.0
+hadara help
 hadara doctor --json
-hadara task list --json
-hadara tools list --json
 ```
 
 Run without a global install:
 
 ```bash
-npx hadara@0.2.0-rc.2 doctor --json
-npx hadara@0.2.0-rc.2 tools list --json
+npx hadara@0.3.0-rc.0 help
+npx hadara@0.3.0-rc.0 doctor --json
 ```
 
-Previous published RCs: `hadara@0.2.0-rc.1` and `hadara@0.1.0-rc.0` remain available on npm for comparison or rollback, but new installs should use the current RC after the operator publishes it.
-
 ## What HADARA Gives You
 
 | Capability | Purpose |
@@ -73,186 +70,154 @@ Previous published RCs: `hadara@0.2.0-rc.1` and `hadara@0.1.0-rc.0` remain avail
 | Task Capsules | Keep each unit of work scoped, evidenced, and resumable. |
 | Evidence Logs | Record public, reduced proof of validation without raw private logs. |
 | Handoff Protocol | Preserve current state for the next operator or agent. |
-| Policy Surfaces | Inspect command risk and release boundaries before mutation. |
-| CLI JSON Reports | Give agents and automation stable read models. |
+| Structured Help | Separate primary lifecycle commands from diagnostics, advanced, release, UI, and integration surfaces. |
+| Document Governance | Classify canonical, active, reference, historical, superseded, and archived docs. |
+| Managed Markdown Safety | Patch declared generated sections with dry-run and hash guards. |
+| Release Gates | Check package and release readiness through evidence-backed dry-run reports. |
 | Read-only MCP Bridge | Expose project/task/evidence state without default write tools. |
 | Dashboard and TUI | Provide local operator observation surfaces over existing read models. |
-| Release Gates | Check release readiness through evidence-backed dry-run reports. |
 
 HADARA is deliberately conservative. Read surfaces are broad; write and release surfaces are narrow, explicit, and evidence-oriented.
 
-## Common Commands
+## Start Here
 
-Project and protocol health:
-
-```bash
-hadara doctor --json
-hadara status --json
-hadara ops status --json
-hadara tools list --json
-hadara protocol doctor --json
-hadara protocol doctor --scope docs --json
-```
-
-Task workflow:
+Ask the CLI for the workflow before choosing commands:
 
 ```bash
+hadara help
+hadara help lifecycle
 hadara task next --json
-hadara task create "implement a focused change" --json
-hadara task status --task T-0001 --json
-hadara task finish --task T-0001 --json
-hadara task finish --task T-0001 --execute --json
-hadara task ready --task T-0001 --level done --json
-hadara task close --task T-0001 --json
-hadara task close --task T-0001 --execute --json
-hadara task audit-close --task T-0001 --json
 ```
 
-Evidence and handoff:
+Use structured discovery when an agent or tool needs machine-readable command metadata:
 
 ```bash
-hadara evidence collect --task T-0001 --json
-hadara evidence add-command --task T-0001 --summary "Focused validation passed." --result passed --json
-hadara evidence list --task T-0001 --json
-hadara handoff suggest --task T-0001 --json
-```
-
-Release and package readiness:
-
-```bash
-hadara package smoke --dry-run --json
-hadara package smoke --execute --attach-evidence --task T-0001 --json
-hadara smoke clean-checkout --execute --attach-evidence --task T-0001 --json
-hadara release artifact --execute --json --output dist-release --attach-evidence --task T-0001
-hadara release gate --mode strict --json
-hadara release dry-run --json
-hadara release publish --mode dry-run --json
+hadara commands --json
+hadara commands --family capsule-lifecycle --json
+hadara help command task.close
 ```
 
-`package smoke --execute`, `smoke clean-checkout --execute`, and `release artifact --execute` create local validation artifacts and reduced public evidence only. They must not publish packages, create GitHub Releases, build Docker images, push images, or load publish token values.
+## Primary Capsule Lifecycle
 
-`release publish --mode dry-run` reports readiness, token presence by name, approval requirements, and mutation privacy flags without running `npm publish`. Any publish execution must happen only in a separate approval-gated release capsule with explicit operator confirmation.
-
-## Task Capsule Lifecycle
-
-HADARA task workflow commands have distinct read/write boundaries. The full command semantics live in `docs/TASK_WORKFLOW_COMMANDS.md`.
-
-Phase 6 reports support optional actor/run metadata for future multi-agent-compatible workflows. Commands such as `task complete`, `task finish`, `task ready`, `task close`, `task audit-close`, `handoff suggest`, and `dev docker-check` may accept metadata such as `--agent-id`, `--run-id`, `--actor-role`, and `--parent-run-id`. These fields improve provenance but do not enable a scheduler or full multi-agent runtime.
+The primary path is intentionally small:
 
 ```bash
 hadara task next --json
-
-# If a matching capsule already exists:
-hadara task status --task T-XXXX --json
-
-# If no matching capsule exists, create one first:
 hadara task create "implement a focused change" --json
 hadara task status --task T-XXXX --json
-
-# Do the scoped work.
-
-hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
-
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --idempotency-key "command:T-XXXX:check" --json
 hadara task finish --task T-XXXX --json
 hadara task finish --task T-XXXX --execute --json
-
 # Finalize Task Capsule docs and tracked state docs before closing.
-
 hadara task ready --task T-XXXX --level done --json
-
-# Optional workflow compression / next action preview:
-hadara task complete --task T-XXXX --json
-
 hadara task close --task T-XXXX --json
 hadara task close --task T-XXXX --execute --json
-
 hadara task audit-close --task T-XXXX --json
+hadara handoff suggest --task T-XXXX --json
 ```
 
-Important distinctions:
+Optional workflow compression is read-only. Use it separately when you want a compact current-stage report and next recommended action:
+
+```bash
+hadara task complete --task T-XXXX --json
+```
+
+Important boundaries:
 
 | Command | Boundary |
 |---|---|
 | `task status` | Read-only operator console. `ok:true` means the report was generated, not that the task is ready. |
-| `task complete` | Read-only workflow compressor. It reports the current stage and next action. |
+| `task complete` | Optional read-only workflow compressor. It reports the current stage and next action. |
 | `task finish --execute` | Writes only bounded status bookkeeping in `TASK.md` and `docs/TASK_BOARD.md`. |
 | `task close --execute` | Appends close evidence only. |
 | `task audit-close` | Read-only close proof audit. |
 
-Before `task close --execute`, finish Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, Task Board updates, and tracked state docs. After close execute, changing those close-source docs intentionally invalidates the previous close proof and requires rerunning ready/close/audit. Use stable wording for close results instead of pasting volatile close evidence ids into close-source docs.
+Before `task close --execute`, finish Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, Task Board updates, and tracked state docs. After close execute, changing close-source docs intentionally invalidates the previous close proof and requires rerunning ready/close/audit.
+
+The full command semantics live in `docs/TASK_WORKFLOW_COMMANDS.md`.
 
-## Initialize a Project
+## Proof and Diagnostics
+
+Diagnostics are useful, but they are not the primary lifecycle:
 
 ```bash
-hadara init                  # default: standard
-hadara init --profile basic
-hadara init --profile standard
-hadara init --profile governed
+hadara evidence lint --task T-0001 --json
+hadara evidence list --task T-0001 --json
+hadara proof status --task T-0001 --json
+hadara proof explain --task T-0001 --json
+hadara ci gate --mode advisory --task T-0001 --json
+hadara ci gate --mode strict --task T-0001 --json
+hadara protocol doctor --json
 ```
 
-Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current evidence, ready, finish, close, and audit-close loop.
+Use strict gates before Done/close/release claims. Use advisory gates while exploring.
 
-| Profile | Use When |
-|---|---|
-| `basic` | Small project, only task/handoff discipline needed. |
-| `standard` | Default multi-session project with planning and validation docs. |
-| `governed` | Long-lived project with security, refactor, roadmap, or operational governance needs. |
+## Document Governance
 
-Init maintenance commands dry-run by default unless `--execute` is supplied:
+HADARA projects can register and classify their operating documents:
 
 ```bash
-hadara init doctor --json
-hadara init upgrade --profile governed --json
-hadara init register-doc --path docs/specs/LOCAL.md --when "Local work" --purpose "Local spec" --json
-hadara init enable-integration --integration mcp --json
+hadara docs list --json
+hadara docs doctor --json
+hadara docs explain --path docs/PROJECT_STATE.md --json
+hadara docs required-reading --json
 ```
 
-`register-doc` can use `--require-exists` when missing referenced docs should be treated as an error. `enable-integration` registers project guidance docs only; it does not enable Hermes/MCP runtime behavior or change capability gates. `upgrade` creates missing scaffold docs and updates known generated profile metadata; it does not rewrite unrelated user-authored content.
+The document registry distinguishes canonical, active, reference, historical, superseded, and archived docs. `docs required-reading` reports the effective default reading set and excludes historical, superseded, and archived docs.
 
-## Develop from Source
-
-Use Node.js 22.
+Docs cleanup is metadata-first:
 
 ```bash
-npm install
-npm run build
-node dist/cli/main.js doctor --json
-npm run check
+hadara docs mark --path docs/specs/old.md --status superseded --by docs/specs/new.md --reason "Replaced" --json
+hadara docs archive --status superseded --json
 ```
 
-For HADARA-dev itself, Docker is the preferred validation path because host `node_modules` on mounted workspaces can be unreliable:
+`docs mark --execute` is hash-guarded and writes only `.hadara/docs-registry.json`. `docs archive` is dry-run planning only in the current implementation; it does not move or delete historical files.
+
+## Managed Markdown Safety
+
+HADARA can update declared managed sections only. Managed patch execution is dry-run-first and hash-guarded. User-authored prose remains outside automated writes.
 
 ```bash
-npm run dev:docker-check
-npm run dev:docker-sync-build
+hadara docs managed list --json
+hadara docs managed explain --path docs/TASK_BOARD.md --json
+hadara docs patch --path docs/TASK_BOARD.md --section task-board --content-file .hadara/local/patches/task-board.md --json
+hadara docs patch --path docs/TASK_BOARD.md --section task-board --content-file .hadara/local/patches/task-board.md --execute --before-hash sha256:... --json
 ```
 
-Focused validation:
+Managed patch reports describe target hashes, section hashes, planned operations, and issues before any write is applied.
+
+## Release and Advanced Surfaces
+
+Release/package commands are release-only surfaces, not ordinary lifecycle steps:
 
 ```bash
-npm run test:focused -- tests/unit/release-dry-run.test.ts
+hadara package smoke --dry-run --json
+hadara package smoke --execute --attach-evidence --task T-0001 --json
+hadara smoke clean-checkout --execute --attach-evidence --task T-0001 --json
+hadara release artifact --execute --json --output dist-release --attach-evidence --task T-0001
+hadara release gate --mode strict --json
+hadara release dry-run --json
+hadara release publish --mode dry-run --json
 ```
 
-## Release Discipline
+`package smoke --execute`, `smoke clean-checkout --execute`, and `release artifact --execute` create local validation artifacts and reduced public evidence only. They must not publish packages, create GitHub Releases, build Docker images, push images, or load publish token values.
 
-HADARA release work is evidence-first.
+`release publish --mode dry-run` reports readiness, token presence by name, approval requirements, and mutation privacy flags without running `npm publish`. Any publish execution must happen only in a separate approval-gated release capsule with explicit operator confirmation.
 
-Before any npm publish:
+Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay out of the primary lifecycle unless a task explicitly needs them.
 
-1. Confirm the git worktree is clean.
-2. Run `hadara release dry-run --json`.
-3. Run `hadara release publish --mode dry-run --json`.
-4. Confirm `NPM_TOKEN` presence without printing the token value.
-5. Confirm the exact package version is not already on npm.
-6. Generate fresh package, clean-checkout, and release-artifact evidence for the active release capsule.
-7. Publish only after explicit operator approval.
-8. Verify with `npm view hadara@<version> version`.
-9. Attach reduced publish evidence.
-10. Update release notes, Project State, Agent Handoff, and the active Task Capsule.
+## Safety Boundaries
 
-Never write token values, private logs, raw npm output, private paths, or local machine state into committed evidence.
+HADARA 0.3.0 is not:
 
-## Store Separation
+- a full agent runtime;
+- Rack/enterprise behavior;
+- automatic broad document rewriting;
+- automatic historical document deletion;
+- default shell execution through agents;
+- default MCP write tooling;
+- release or publish automation without operator approval.
 
 HADARA separates portable runtime state from project-owned development state.
 
@@ -280,9 +245,57 @@ AGENTS.md
 
 Portable/local state is not committed. Project docs, Task Capsules, and reduced public evidence are committed when they represent reproducible context.
 
-## Optional / Deferred Integrations
+## Development / Contributing
+
+Initialize a project:
+
+```bash
+hadara init                  # default: standard
+hadara init --profile basic
+hadara init --profile standard
+hadara init --profile governed
+```
+
+Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current evidence, ready, finish, close, and audit-close loop.
+
+| Profile | Use When |
+|---|---|
+| `basic` | Small project, only task/handoff discipline needed. |
+| `standard` | Default multi-session project with planning and validation docs. |
+| `governed` | Long-lived project with security, refactor, roadmap, or operational governance needs. |
+
+Init maintenance commands dry-run by default unless `--execute` is supplied:
+
+```bash
+hadara init doctor --json
+hadara init upgrade --profile governed --json
+hadara init register-doc --path docs/specs/LOCAL.md --when "Local work" --purpose "Local spec" --json
+hadara init enable-integration --integration mcp --json
+```
 
-Hermes and MCP surfaces exist for compatibility experiments and read-only bridge work. They are not generated by `hadara init` and are not part of the default scaffold. Use them only when a project explicitly opts into integration guidance.
+Develop from source with Node.js 22:
+
+```bash
+npm install
+npm run build
+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
 hadara init enable-integration --integration hermes --execute --json
@@ -294,19 +307,6 @@ hadara mcp serve
 
 The default MCP server remains read-only. Evidence attach is opt-in, approval-recorded, and audited.
 
-## Deferred
-
-These are intentionally not part of the current default runtime:
-
-- Full multi-agent scheduler/controller.
-- Broad MCP write tools.
-- Shell execution through agents.
-- Real provider execution as the default path.
-- GitHub Release automation as a default path.
-- Docker image publishing.
-- Installer scripts and USB portable launchers.
-- Live dashboard streaming.
-
 ## License
 
 HADARA is released under the MIT License. You can use, copy, modify, distribute, and build on it under the terms in `LICENSE`.

package/dist/cli/ci.js

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

package/dist/cli/commands.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCommandsCommand = handleCommandsCommand;
+exports.createCommandsRegistryReport = createCommandsRegistryReport;
+const args_1 = require("./args");
+const capability_registry_1 = require("../services/capability-registry");
+function handleCommandsCommand(input) {
+    const family = (0, args_1.getStringOption)(input.args, '--family');
+    const requiredness = (0, args_1.getStringOption)(input.args, '--requiredness');
+    const report = createCommandsRegistryReport({ family, requiredness });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        for (const entry of report.commands) {
+            console.log(`${entry.id} | ${entry.family} | ${entry.requiredness} | ${entry.command}`);
+        }
+    }
+    return true;
+}
+function createCommandsRegistryReport(filters = {}) {
+    return {
+        schemaVersion: 'hadara.commands.registry.v1',
+        command: 'commands',
+        ok: true,
+        registryVersion: capability_registry_1.HADARA_COMMAND_REGISTRY_VERSION,
+        filters: {
+            family: filters.family ?? null,
+            requiredness: filters.requiredness ?? null
+        },
+        commands: (0, capability_registry_1.listCommandRegistryEntries)(filters),
+        issues: []
+    };
+}

package/dist/cli/docs.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDocsCommand = handleDocsCommand;
+const args_1 = require("./args");
+const docs_cleanup_1 = require("../services/docs-cleanup");
+const docs_registry_1 = require("../services/docs-registry");
+const managed_sections_1 = require("../services/managed-sections");
+function handleDocsCommand(input) {
+    const sub = input.args[1];
+    if (sub === 'list') {
+        const report = (0, docs_registry_1.createDocsListReport)(input.projectRoot, {
+            status: (0, args_1.getStringOption)(input.args, '--status'),
+            readWhen: (0, args_1.getStringOption)(input.args, '--read-when')
+        });
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'doctor') {
+        const report = (0, docs_registry_1.createDocsDoctorReport)(input.projectRoot, (0, args_1.getStringOption)(input.args, '--scope', 'all') ?? 'all');
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'explain') {
+        const documentPath = (0, args_1.getStringOption)(input.args, '--path') ?? input.args[2] ?? '';
+        const report = (0, docs_registry_1.createDocsExplainReport)(input.projectRoot, documentPath);
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'managed') {
+        const managedSub = input.args[2];
+        if (managedSub === 'list') {
+            printReport((0, managed_sections_1.createManagedSectionsListReport)(input.projectRoot), input.jsonOutput);
+            return true;
+        }
+        if (managedSub === 'explain') {
+            printReport((0, managed_sections_1.createManagedSectionExplainReport)(input.projectRoot, (0, args_1.getRequiredStringOption)(input.args, '--path')), input.jsonOutput);
+            return true;
+        }
+    }
+    if (sub === 'patch') {
+        const report = (0, managed_sections_1.createDocsPatchPlanReport)(input.projectRoot, {
+            targetPath: (0, args_1.getRequiredStringOption)(input.args, '--path'),
+            sectionId: (0, args_1.getRequiredStringOption)(input.args, '--section'),
+            contentFile: (0, args_1.getRequiredStringOption)(input.args, '--content-file'),
+            mode: (0, args_1.getFlag)(input.args, '--execute') ? 'execute' : 'dry-run',
+            beforeHash: (0, args_1.getStringOption)(input.args, '--before-hash'),
+            owner: (0, args_1.getStringOption)(input.args, '--owner', 'operator') ?? 'operator'
+        });
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'mark') {
+        const report = (0, docs_cleanup_1.createDocsMarkReport)(input.projectRoot, {
+            documentPath: (0, args_1.getRequiredStringOption)(input.args, '--path'),
+            status: (0, args_1.getRequiredStringOption)(input.args, '--status'),
+            reason: (0, args_1.getStringOption)(input.args, '--reason'),
+            by: (0, args_1.getStringOption)(input.args, '--by'),
+            mode: (0, args_1.getFlag)(input.args, '--execute') ? 'execute' : 'dry-run',
+            beforeHash: (0, args_1.getStringOption)(input.args, '--before-hash'),
+            forceCanonical: (0, args_1.getFlag)(input.args, '--force-canonical')
+        });
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'archive') {
+        printReport((0, docs_cleanup_1.createDocsArchivePlanReport)(input.projectRoot, (0, args_1.getStringOption)(input.args, '--status')), input.jsonOutput);
+        return true;
+    }
+    if (sub === 'required-reading') {
+        printReport((0, docs_cleanup_1.createDocsRequiredReadingReport)(input.projectRoot), input.jsonOutput);
+        return true;
+    }
+    return false;
+}
+function printReport(report, jsonOutput) {
+    if (jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(JSON.stringify(report, null, 2));
+}

package/dist/cli/evidence-json.js

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