hadara 0.3.4-rc.0 → 0.4.0

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.3-blue">
-  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.4--rc.0-blue">
+  <img alt="Stable npm release" src="https://img.shields.io/badge/npm-0.4.0-blue">
+  <img alt="Next npm release" src="https://img.shields.io/badge/next-0.4.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>
@@ -24,30 +24,30 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 Current stable npm release:
 
 ```text
-hadara@0.3.3
+hadara@0.4.0
 ```
 
-Current source release candidate:
+Previous npm release candidate:
 
 ```text
-hadara@0.3.4-rc.0
+hadara@0.4.0-rc.0
 ```
 
-Previous published release candidate:
+Previous agent UX release candidate:
 
 ```text
-hadara@0.3.3-rc.0
+hadara@0.3.4-rc.0
 ```
 
-The 0.3.4 source line is an agent UX hardening release candidate after stable 0.3.3. It keeps the context-routing and finalize-first lifecycle surfaces, then improves the commands agents actually use during HADARA development: session start, context pack, evidence summary, handoff stale-problem checks, release closeout, package recycle, generated init guidance, and close/finalize diagnostics.
+The 0.4.0 source line is a breaking productization release after stable 0.3.3 and the published 0.3.4-rc.0 agent UX line. It keeps the context-routing and finalize-first lifecycle baseline, then simplifies new projects around a productized 0.4 scaffold, registry-backed docs read maps, a four-file Task Capsule, generated evidence projection, a normalized close-source contract, and fail-closed legacy mutation boundaries.
 
-Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.3` package is the default install target; `0.3.4-rc.0` is the current source candidate and must not be treated as published until an approval-gated publish capsule completes.
+Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.4.0` package is the default install target through the `latest` dist-tag after the approval-gated publish completes; `0.4.0-rc.0` remains the previous release candidate on npm under the `next` dist-tag.
 
 | Surface | Status |
 |---|---|
-| Current stable | [`hadara@0.3.3`](docs/RELEASE_NOTES.md#033) |
-| Source candidate | [`hadara@0.3.4-rc.0`](docs/RELEASE_NOTES.md#034-rc0) |
-| Previous RC | [`hadara@0.3.3-rc.0`](docs/RELEASE_NOTES.md#033-rc0) |
+| Current stable | [`hadara@0.4.0`](docs/RELEASE_NOTES.md#040) |
+| Previous RC | [`hadara@0.4.0-rc.0`](docs/RELEASE_NOTES.md#040-rc0) on `next` |
+| Previous agent UX RC | [`hadara@0.3.4-rc.0`](docs/RELEASE_NOTES.md#034-rc0) |
 | Previous stable | [`hadara@0.3.2`](docs/RELEASE_NOTES.md#032) |
 | Historical RCs | See [Release Notes](docs/RELEASE_NOTES.md). |
 | GitHub Release | Secondary target, approval-gated. |
@@ -55,7 +55,7 @@ Phase labels are internal implementation phases, not npm release-candidate label
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
 | Installer scripts / USB launchers | Deferred. |
 
-No release command should publish, create a GitHub Release, build Docker images, upload artifacts, or load token values unless an operator explicitly approves the mutation path for the active release capsule. Stable `0.3.3` is the npm package line until the `0.3.4-rc.0` publish capsule completes; GitHub Release, Docker/PyPI publish, installer execution, and MCP release/package execution remain separate explicit mutations.
+No release command should publish, create a GitHub Release, build Docker images, upload artifacts, or load token values unless an operator explicitly approves the mutation path for the active release capsule. Stable `0.4.0` is the default npm package line after the T-0490 approval-gated publish completes; `0.4.0-rc.0` remains available for explicit RC evaluation through `hadara@next` or the exact version. The `v0.4.0-rc.0` GitHub Release exists as a draft prerelease; Docker/PyPI publish, installer execution, and MCP release/package execution remain separate explicit mutations.
 
 ## Install
 
@@ -64,7 +64,7 @@ Requires Node.js 22.
 Install the stable release:
 
 ```bash
-npm install -g hadara@0.3.3
+npm install -g hadara@0.4.0
 hadara help
 hadara doctor --json
 ```
@@ -72,26 +72,26 @@ hadara doctor --json
 Run without a global install:
 
 ```bash
-npx hadara@0.3.3 help
-npx hadara@0.3.3 doctor --json
+npx hadara@0.4.0 help
+npx hadara@0.4.0 doctor --json
 ```
 
-Evaluate the previous release candidate explicitly:
+Evaluate the previous `0.4.0-rc.0` explicitly:
 
 ```bash
-npm install -g hadara@0.3.3-rc.0
-npx hadara@0.3.3-rc.0 help
+npm install -g hadara@0.4.0-rc.0
+npx hadara@0.4.0-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.3
+npm --prefix "$tmp" install hadara@0.4.0
 "$tmp/node_modules/.bin/hadara" version --json
 ```
 
-`npx hadara@0.3.3 ...` 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.4.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
 
@@ -116,7 +116,7 @@ Ask the CLI for the workflow before choosing commands:
 ```bash
 hadara help
 hadara help lifecycle
-hadara task next --json
+hadara task status --json
 ```
 
 Use structured discovery when an agent or tool needs machine-readable command metadata:
@@ -129,16 +129,15 @@ hadara help command task.close
 
 ## Primary Capsule Lifecycle
 
-The 0.3.4 primary path is intentionally small. Agents should start with compact context and use `task finalize` as the default lifecycle close path:
+The 0.4 primary path is intentionally small. Agents should start with compact context and use `task finalize` as the default lifecycle close path:
 
 ```bash
-hadara task next --json
+hadara task status --json
 hadara session start --task T-XXXX --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 --category validation --idempotency-key "command:T-XXXX:check" --json
 # Finalize Task Capsule docs and tracked state docs before closing.
-hadara task lifecycle --task T-XXXX --json
 hadara task finalize --task T-XXXX --json
 hadara task finalize --task T-XXXX --execute --plan-hash sha256:... --json
 hadara handoff suggest --task T-XXXX --json
@@ -162,8 +161,9 @@ Deferred Evidence v2 scope is explicit: rebuild preview/execute, `check-id`, `su
 Use read-only lifecycle diagnostics when you want a compact current-stage report, next recommended action, or close-proof repair explanation:
 
 ```bash
+hadara task status --task T-XXXX --json
 hadara task complete --task T-XXXX --json
-hadara task lifecycle --task T-XXXX --json
+hadara task lifecycle --task T-XXXX --json # compatibility
 hadara task close-repair-plan --task T-XXXX --json
 ```
 
@@ -268,7 +268,7 @@ Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay
 
 ## Safety Boundaries
 
-HADARA 0.3.4-rc.0 is not:
+HADARA 0.4.0 is not:
 
 - a full agent runtime;
 - Rack/enterprise behavior;
@@ -308,7 +308,7 @@ Portable/local state is not committed. Project docs, Task Capsules, and reduced
 
 `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.4-rc.0 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.
+0.4.0 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
 
@@ -321,7 +321,7 @@ hadara init --profile standard
 hadara init --profile governed
 ```
 
-Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current 0.3.4 context-aware finalize-first lifecycle loop plus low-level proof-boundary reference commands.
+Every profile generates the 0.4 project scaffold with compact agent entry docs, a docs registry, a workflow guide, and the current context-aware finalize-first lifecycle loop plus low-level proof-boundary reference commands.
 
 | Profile | Use When |
 |---|---|

package/dist/cli/dashboard.js

@@ -95,7 +95,7 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
     if (url.pathname === '/api/status') {
         // Dashboard clients fetch operational debt separately; keep the status
         // route cheap so a single slow debt scan cannot block first API paint.
-        return jsonResponse((0, operations_status_service_1.createOpsStatusReport)(projectRoot, { includeDebt: false }), headOnly);
+        return jsonResponse(readCachedOpsStatus(projectRoot, false, url.searchParams.get('cache') === 'bypass'), headOnly);
     }
     if (url.pathname === '/api/dashboard/core') {
         const bypassProjection = url.searchParams.get('cache') === 'bypass';
@@ -125,7 +125,12 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
         if (selectedTaskId)
             keyParts.push('selected', selectedTaskId);
         const key = (0, dashboard_cache_1.createDashboardCacheKey)(projectRoot, ...keyParts);
-        const cached = (0, dashboard_cache_1.getOrCreateCachedReport)(key, { ttlMs: dashboard_cache_1.DASHBOARD_CACHE_TTLS.bootstrap, bypass: url.searchParams.get('cache') === 'bypass' }, () => (0, dashboard_bootstrap_1.createDashboardBootstrapReport)(projectRoot, { tier, ...(selectedTaskId ? { selectedTaskId } : {}) }));
+        const cached = (0, dashboard_cache_1.getOrCreateCachedReport)(key, { ttlMs: dashboard_cache_1.DASHBOARD_CACHE_TTLS.bootstrap, bypass: url.searchParams.get('cache') === 'bypass' }, () => (0, dashboard_bootstrap_1.createDashboardBootstrapReport)(projectRoot, {
+            tier,
+            ...(selectedTaskId ? { selectedTaskId } : {}),
+            status: readCachedOpsStatus(projectRoot, tier === 'full', url.searchParams.get('cache') === 'bypass'),
+            tasks: readCachedTaskList(projectRoot, url.searchParams.get('cache') === 'bypass')
+        }));
         return jsonResponse((0, dashboard_cache_1.withDashboardCacheMetadata)(cached.value, cached.cache), headOnly);
     }
     if (url.pathname === '/api/dashboard/task-detail') {
@@ -139,7 +144,7 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
     if (url.pathname === '/api/dashboard/cache/status')
         return jsonResponse((0, dashboard_cache_1.createDashboardCacheStatusReport)(), headOnly);
     if (url.pathname === '/api/tasks')
-        return jsonResponse((0, task_read_model_1.createTaskListReport)(projectRoot), headOnly);
+        return jsonResponse(readCachedTaskList(projectRoot, url.searchParams.get('cache') === 'bypass'), headOnly);
     if (url.pathname === '/api/active-run')
         return jsonResponse((0, active_run_state_1.safeCreateActiveRunProjection)(projectRoot), headOnly);
     if (url.pathname === '/api/debt') {
@@ -159,7 +164,8 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
         const taskId = url.searchParams.get('taskId')?.trim();
         if (!taskId)
             return missingTaskId(headOnly);
-        return jsonResponse((0, task_workbench_1.createTaskWorkbenchReport)(projectRoot, taskId), headOnly);
+        const detail = url.searchParams.get('detail') === 'full' ? 'full' : 'fast';
+        return jsonResponse((0, task_workbench_1.createTaskWorkbenchReport)(projectRoot, taskId, new Date(), { detail }), headOnly);
     }
     if (url.pathname === '/api/evidence-lint') {
         const taskId = url.searchParams.get('taskId')?.trim();
@@ -175,6 +181,12 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
     }
     return notFound();
 }
+function readCachedOpsStatus(projectRoot, includeDebt, bypass) {
+    return (0, dashboard_cache_1.getOrCreateCachedReport)((0, dashboard_cache_1.createDashboardCacheKey)(projectRoot, 'status', includeDebt ? 'full' : 'core'), { ttlMs: dashboard_cache_1.DASHBOARD_CACHE_TTLS.status, bypass }, () => (0, operations_status_service_1.createOpsStatusReport)(projectRoot, { includeDebt })).value;
+}
+function readCachedTaskList(projectRoot, bypass) {
+    return (0, dashboard_cache_1.getOrCreateCachedReport)((0, dashboard_cache_1.createDashboardCacheKey)(projectRoot, 'tasks'), { ttlMs: dashboard_cache_1.DASHBOARD_CACHE_TTLS.tasks, bypass }, () => (0, task_read_model_1.createTaskListReport)(projectRoot)).value;
+}
 function missingTaskId(headOnly) {
     return jsonResponse({
         schemaVersion: 'hadara.dashboard.api.error.v1',

package/dist/cli/docs.js

@@ -5,6 +5,7 @@ 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");
+const legacy_boundary_1 = require("./legacy-boundary");
 function handleDocsCommand(input) {
     const sub = input.args[1];
     if (sub === 'list') {
@@ -26,6 +27,39 @@ function handleDocsCommand(input) {
         printReport(report, input.jsonOutput);
         return true;
     }
+    if (sub === 'read-map') {
+        const report = (0, docs_registry_1.createDocsReadMapReport)(input.projectRoot, (0, args_1.getRequiredStringOption)(input.args, '--task'));
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'inbox') {
+        const report = (0, docs_registry_1.createDocsInboxReport)(input.projectRoot);
+        printReport(report, input.jsonOutput);
+        return true;
+    }
+    if (sub === 'register') {
+        if ((0, args_1.getFlag)(input.args, '--execute') && blockLegacyMutation(input, 'docs.register'))
+            return true;
+        const report = (0, docs_registry_1.createDocsRegisterReport)(input.projectRoot, {
+            documentPath: (0, args_1.getRequiredStringOption)(input.args, '--path'),
+            title: (0, args_1.getStringOption)(input.args, '--title'),
+            kind: (0, args_1.getStringOption)(input.args, '--kind'),
+            status: (0, args_1.getStringOption)(input.args, '--status'),
+            readWhen: (0, args_1.getStringOption)(input.args, '--read-when'),
+            readTier: (0, args_1.getStringOption)(input.args, '--read-tier'),
+            authority: (0, args_1.getStringOption)(input.args, '--authority'),
+            editPolicy: (0, args_1.getStringOption)(input.args, '--edit-policy'),
+            activeForTasks: splitCsv((0, args_1.getStringOption)(input.args, '--active-for-task')),
+            driftRisk: (0, args_1.getStringOption)(input.args, '--drift'),
+            driftReviewRequired: (0, args_1.getFlag)(input.args, '--drift-review-required'),
+            driftReason: (0, args_1.getStringOption)(input.args, '--drift-reason'),
+            requiredReading: (0, args_1.getFlag)(input.args, '--required-reading'),
+            requireExists: (0, args_1.getFlag)(input.args, '--require-exists'),
+            mode: (0, args_1.getFlag)(input.args, '--execute') ? 'execute' : 'dry-run'
+        });
+        printReport(report, input.jsonOutput);
+        return true;
+    }
     if (sub === 'managed') {
         const managedSub = input.args[2];
         if (managedSub === 'list') {
@@ -38,6 +72,8 @@ function handleDocsCommand(input) {
         }
     }
     if (sub === 'patch') {
+        if ((0, args_1.getFlag)(input.args, '--execute') && blockLegacyMutation(input, 'docs.patch'))
+            return true;
         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'),
@@ -72,6 +108,14 @@ function handleDocsCommand(input) {
     }
     return false;
 }
+function blockLegacyMutation(input, command) {
+    const report = (0, legacy_boundary_1.createLegacyMutationBlockedReport)(input.projectRoot, command);
+    if (!report)
+        return false;
+    (0, legacy_boundary_1.printLegacyMutationBlockedReport)(report, input.jsonOutput);
+    process.exitCode = 6;
+    return true;
+}
 function printReport(report, jsonOutput) {
     if (jsonOutput) {
         console.log(JSON.stringify(report, null, 2));
@@ -79,3 +123,9 @@ function printReport(report, jsonOutput) {
     }
     console.log(JSON.stringify(report, null, 2));
 }
+function splitCsv(value) {
+    if (value === undefined)
+        return undefined;
+    const items = value.split(',').map((item) => item.trim()).filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}

package/dist/cli/doctor.js

@@ -7,18 +7,33 @@ exports.createDoctorReport = createDoctorReport;
 exports.formatDoctorReport = formatDoctorReport;
 exports.handleDoctorCommand = handleDoctorCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
-function createDoctorReport(paths, nodeVersion = process.version) {
+const node_path_1 = __importDefault(require("node:path"));
+const package_json_1 = __importDefault(require("../../package.json"));
+function createDoctorReport(paths, nodeVersion = process.version, options = {}) {
     const checks = [
         pathCheck('docs', paths.projectDocsDir),
         pathCheck('tasks', paths.projectTasksDir),
         pathCheck('project-context', `${paths.projectContextDir}/HADARA_CONTEXT.md`)
     ];
+    const executablePath = normalizeOptionalPath(options.cliEntry ?? process.argv[1] ?? null);
+    const resolvedExecutablePath = resolveExecutablePath(executablePath);
+    const packageRoot = findPackageRoot([resolvedExecutablePath, executablePath]);
     return {
         schemaVersion: 'hadara.doctor.v1',
         command: 'doctor',
         ok: checks.every((check) => check.status === 'ok'),
         runtime: {
-            node: nodeVersion
+            node: nodeVersion,
+            nodePath: normalizePath(options.nodePath ?? process.execPath)
+        },
+        installation: {
+            executablePath,
+            resolvedExecutablePath,
+            packageRoot,
+            packageVersion: package_json_1.default.version,
+            registry: 'https://registry.npmjs.org',
+            installCommand: `npm install -g ${package_json_1.default.name}@${package_json_1.default.version}`,
+            latestInstallCommand: `npm install -g ${package_json_1.default.name}`
         },
         paths: {
             portableRoot: paths.portableRoot,
@@ -35,11 +50,18 @@ function formatDoctorReport(report) {
         `dataRoot:     ${report.paths.dataRoot}`,
         `projectRoot:  ${report.paths.projectRoot}`,
         `Node:         ${report.runtime.node}`,
+        `Node path:    ${report.runtime.nodePath}`,
+        'Install:',
+        `  executable: ${report.installation.executablePath ?? 'unknown'}`,
+        `  resolved:   ${report.installation.resolvedExecutablePath ?? 'unknown'}`,
+        `  package:    ${report.installation.packageVersion}${report.installation.packageRoot ? ` at ${report.installation.packageRoot}` : ' (package root unknown)'}`,
+        `  registry:   ${report.installation.registry}`,
+        `  install:    ${report.installation.installCommand}`,
         ...report.checks.map((check) => `${formatCheckLabel(check.id)}${check.status}`)
     ].join('\n');
 }
 function handleDoctorCommand(input) {
-    const report = createDoctorReport(input.paths);
+    const report = createDoctorReport(input.paths, process.version, { cliEntry: process.argv[1] });
     if (input.jsonOutput) {
         console.log(JSON.stringify(report, null, 2));
     }
@@ -57,6 +79,55 @@ function pathCheck(id, targetPath) {
         path: targetPath
     };
 }
+function normalizeOptionalPath(value) {
+    if (!value)
+        return null;
+    return normalizePath(value);
+}
+function normalizePath(value) {
+    return node_path_1.default.normalize(value);
+}
+function resolveExecutablePath(executablePath) {
+    if (!executablePath)
+        return null;
+    try {
+        return normalizePath(node_fs_1.default.realpathSync.native(executablePath));
+    }
+    catch {
+        return null;
+    }
+}
+function findPackageRoot(candidates) {
+    for (const candidate of candidates) {
+        const found = candidate ? findPackageRootFromFile(candidate) : null;
+        if (found)
+            return found;
+    }
+    return null;
+}
+function findPackageRootFromFile(filePath) {
+    let current = node_fs_1.default.existsSync(filePath) && node_fs_1.default.statSync(filePath).isDirectory()
+        ? filePath
+        : node_path_1.default.dirname(filePath);
+    while (true) {
+        const packagePath = node_path_1.default.join(current, 'package.json');
+        if (isHadaraPackageJson(packagePath))
+            return normalizePath(current);
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function isHadaraPackageJson(packagePath) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(packagePath, 'utf8'));
+        return parsed.name === package_json_1.default.name;
+    }
+    catch {
+        return false;
+    }
+}
 function formatCheckLabel(id) {
     if (id === 'docs')
         return 'docs/:       ';

package/dist/cli/evidence-json.js

@@ -15,6 +15,7 @@ function createEvidenceCollectReport(projectRoot, input) {
             schemaVersion: 'hadara.evidence.collect.v1',
             command: 'evidence.collect',
             ok: false,
+            taskId: input.taskId,
             issues: [
                 {
                     severity: 'error',
@@ -49,6 +50,7 @@ function createEvidenceCollectReport(projectRoot, input) {
                 schemaVersion: 'hadara.evidence.collect.v1',
                 command: 'evidence.collect',
                 ok: false,
+                taskId: input.taskId,
                 issues: [
                     {
                         severity: 'error',
@@ -64,6 +66,7 @@ function createEvidenceCollectReport(projectRoot, input) {
         schemaVersion: 'hadara.evidence.collect.v1',
         command: 'evidence.collect',
         ok: true,
+        taskId: input.taskId,
         evidence: {
             ...appendResult.evidence,
             markdownPath: toPortablePath(node_path_1.default.relative(projectRoot, appendResult.markdownPath)),

package/dist/cli/evidence.js

@@ -13,8 +13,13 @@ const evidence_list_1 = require("../services/evidence-list");
 const evidence_migration_1 = require("../services/evidence-migration");
 const evidence_summary_1 = require("../services/evidence-summary");
 const args_1 = require("./args");
+const legacy_boundary_1 = require("./legacy-boundary");
 function handleEvidenceCommand(input) {
     const sub = input.args[1];
+    if (hasHelpFlag(input.args)) {
+        console.log(renderEvidenceCommandHelp(sub));
+        return true;
+    }
     if (sub === 'list') {
         const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
         const report = (0, evidence_list_1.createEvidenceListReport)(input.projectRoot, {
@@ -79,7 +84,24 @@ function handleEvidenceCommand(input) {
             process.exitCode = 6;
         return true;
     }
+    if (sub === 'project') {
+        const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
+        const report = (0, evidence_1.createEvidenceProjectionReport)(input.projectRoot, taskId, (0, args_1.getFlag)(input.args, '--execute'));
+        if (input.jsonOutput) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(`[HADARA] evidence project ${taskId}: ${report.ok ? 'ok' : 'issues'} | mode ${report.mode} | wouldChange ${report.wouldChange}`);
+            for (const issue of report.issues)
+                console.log(`[${issue.severity}] ${issue.code}: ${issue.message}`);
+        }
+        if (!report.ok)
+            process.exitCode = 6;
+        return true;
+    }
     if (sub === 'migrate') {
+        if ((0, args_1.getFlag)(input.args, '--execute') && blockLegacyMutation(input, 'evidence.migrate'))
+            return true;
         const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
         const report = (0, evidence_migration_1.createEvidenceMigrationPreviewReport)({
             projectRoot: input.projectRoot,
@@ -103,6 +125,8 @@ function handleEvidenceCommand(input) {
         return true;
     }
     if (sub === 'add-command') {
+        if (blockLegacyMutation(input, 'evidence.add-command'))
+            return true;
         const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
         const summary = (0, args_1.getStringOption)(input.args, '--summary') ?? 'Command completed.';
         const outcome = parseOptionalEvidenceOutcome((0, args_1.getStringOption)(input.args, '--outcome'));
@@ -114,6 +138,7 @@ function handleEvidenceCommand(input) {
                 schemaVersion: 'hadara.evidence.collect.v1',
                 command: 'evidence.add-command',
                 ok: false,
+                taskId,
                 issues: [resultOutcomeIssue]
             };
             if (input.jsonOutput) {
@@ -158,6 +183,8 @@ function handleEvidenceCommand(input) {
     }
     if (sub !== 'collect')
         return false;
+    if (blockLegacyMutation(input, 'evidence.collect'))
+        return true;
     const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
     const kind = parseEvidenceKind((0, args_1.getStringOption)(input.args, '--kind', 'note') ?? 'note');
     const summary = (0, args_1.getStringOption)(input.args, '--summary') ?? 'Manual evidence collection placeholder.';
@@ -190,6 +217,51 @@ function handleEvidenceCommand(input) {
     }
     return true;
 }
+function hasHelpFlag(args) {
+    return args.includes('--help') || args.includes('-h');
+}
+function renderEvidenceCommandHelp(sub) {
+    if (sub === 'add-command') {
+        return [
+            '[HADARA] evidence add-command',
+            '',
+            'Usage:',
+            '  hadara evidence add-command --task T-XXXX --summary "..." --result passed --category validation --json',
+            '',
+            'Records an already-run command result. It does not execute shell commands.',
+            'Options:',
+            '  --task <id>                Task Capsule id.',
+            '  --summary <text>          Human-readable result summary.',
+            '  --result <value>          Legacy-compatible result: passed, failed, blocked, unknown.',
+            '  --outcome <value>         Evidence v2 outcome.',
+            '  --category <value>        Evidence v2 category.',
+            '  --resolves <id>           Add a resolves:<id> tag. Repeatable.',
+            '  --supersedes <id>         Add a supersedes:<id> tag. Repeatable.',
+            '  --idempotency-key <key>   Reuse an existing keyed record instead of appending duplicates.',
+            '  --private                 Store as private evidence metadata.'
+        ].join('\n');
+    }
+    return [
+        '[HADARA] evidence',
+        '',
+        'Usage:',
+        '  hadara evidence list --task T-XXXX --json',
+        '  hadara evidence lint --task T-XXXX --json',
+        '  hadara evidence summary --task T-XXXX --json',
+        '  hadara evidence project --task T-XXXX [--execute] --json',
+        '  hadara evidence add-command --task T-XXXX --summary "..." --result passed --json',
+        '',
+        'Use `hadara help command evidence.add-command` for registry metadata.'
+    ].join('\n');
+}
+function blockLegacyMutation(input, command) {
+    const report = (0, legacy_boundary_1.createLegacyMutationBlockedReport)(input.projectRoot, command);
+    if (!report)
+        return false;
+    (0, legacy_boundary_1.printLegacyMutationBlockedReport)(report, input.jsonOutput);
+    process.exitCode = 6;
+    return true;
+}
 function persistedEvidenceId(record) {
     return record.schemaVersion === 'hadara.evidence.v2' && record.id ? record.id : 'evidence.jsonl';
 }

package/dist/cli/help.js

@@ -7,7 +7,7 @@ exports.renderCommandHelp = renderCommandHelp;
 exports.renderFamilyHelp = renderFamilyHelp;
 const capability_registry_1 = require("../services/capability-registry");
 const lifecycle_guide_1 = require("../services/lifecycle-guide");
-const LIFECYCLE_ORDER = ['discover', 'create', 'inspect', 'evidence', 'phase-check', 'finalize', 'handoff'];
+const LIFECYCLE_ORDER = ['inspect', 'create', 'evidence', 'finalize', 'handoff'];
 function handleHelpCommand(input) {
     const topic = input.args[1];
     if (!topic) {
@@ -51,7 +51,7 @@ function renderDefaultHelp() {
         '',
         'Start:',
         '  hadara help lifecycle',
-        '  hadara task next --json',
+        '  hadara task status --json',
         '  hadara task status --task T-XXXX --json',
         '',
         'Primary capsule lifecycle:',
@@ -74,7 +74,7 @@ function renderLifecycleHelp() {
     const report = (0, lifecycle_guide_1.createLifecycleGuideReport)();
     const diagnostics = (0, capability_registry_1.listCommandRegistryEntries)({ family: 'proof-diagnostics' }).filter((entry) => entry.requiredness === 'diagnostic');
     const lines = [
-        'HADARA 0.3.3 primary task lifecycle',
+        'HADARA 0.4 primary task lifecycle',
         '',
         'Primary capsule lifecycle:'
     ];
@@ -104,6 +104,7 @@ function renderCommandHelp(id) {
         `Scope: ${entry.scope}`,
         `Lifecycle stage: ${entry.lifecycleStage}`,
         `Requiredness: ${entry.requiredness}`,
+        `Status: ${entry.status}`,
         `Write boundary: ${entry.writeBoundary}`,
         `Read-only: ${entry.readOnly ? 'yes' : 'no'}`,
         `Risk: ${entry.risk}`,