hadara 0.3.2 → 0.3.3-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.2-blue">
-  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.2-blue">
+  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.3--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>
@@ -30,18 +30,18 @@ hadara@0.3.2
 Current release candidate:
 
 ```text
-hadara@0.3.2-rc.0
+hadara@0.3.3-rc.0
 ```
 
-The 0.3.2 line is the Evidence v2 refactor release. It hardens evidence writer metadata, exact resolution markers, durable evidence id discovery, canonical/derived evidence boundaries, and release-facing docs after the 0.3.1 post-publish recycle.
+The 0.3.3-rc.0 line is the context-routing and lifecycle release candidate. It adds project context graph, context pack/slice/session-start surfaces, explicit context cache warm paths, and makes the finalize-first lifecycle the default agent-facing task loop.
 
-Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.2` source is prepared for approval-gated npm publish; the `0.3.2-rc.0` package remains the prior release-candidate evaluation build until stable publish is executed.
+Phase labels are internal implementation phases, not npm release-candidate labels. The stable `0.3.2` package is the default install target; `0.3.3-rc.0` is the current source candidate for the next `next` dist-tag publish.
 
 | Surface | Status |
 |---|---|
 | Current stable | [`hadara@0.3.2`](docs/RELEASE_NOTES.md#032) |
-| Current RC | [`hadara@0.3.2-rc.0`](docs/RELEASE_NOTES.md#032-rc0) |
-| Previous RC | [`hadara@0.3.1-rc.1`](docs/RELEASE_NOTES.md#031-rc1) |
+| Current RC | [`hadara@0.3.3-rc.0`](docs/RELEASE_NOTES.md#033-rc0) |
+| Previous RC | [`hadara@0.3.2-rc.0`](docs/RELEASE_NOTES.md#032-rc0) |
 | Historical RCs | See [Release Notes](docs/RELEASE_NOTES.md). |
 | GitHub Release | Secondary target, approval-gated. |
 | Docker image | Deferred. |
@@ -72,8 +72,8 @@ npx hadara@0.3.2 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
+npm install -g hadara@0.3.3-rc.0
+npx hadara@0.3.3-rc.0 help
 ```
 
 For release or recycle evidence, prefer an isolated prefix install when PATH, global installs, or `npx` cache behavior may be stale:
@@ -122,23 +122,22 @@ hadara help command task.close
 
 ## Primary Capsule Lifecycle
 
-The primary path is intentionally small:
+The 0.3.3 primary path is intentionally small. Agents should use `task finalize` as the default lifecycle close path:
 
 ```bash
 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 --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.
-hadara task ready --task T-XXXX --level done --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 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
 ```
 
+`task finalize --json` is the reviewed dry-run. It reports the current lifecycle step, write boundaries, expected write paths, and a current `planHash`. `task finalize --execute --plan-hash ...` rechecks that plan hash, executes phases serially, stops on blockers, and succeeds only after final close audit is `closed-valid`.
+
 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:
@@ -152,23 +151,39 @@ Legacy compatibility ids are inspection-only and are not the preferred durable r
 
 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:
+Use read-only lifecycle diagnostics when you want a compact current-stage report, next recommended action, or close-proof repair explanation:
 
 ```bash
 hadara task complete --task T-XXXX --json
+hadara task lifecycle --task T-XXXX --json
+hadara task close-repair-plan --task T-XXXX --json
+```
+
+Low-level proof-boundary commands remain available for debugging, recovery, and command implementation work:
+
+```bash
+hadara task finish --task T-XXXX --json
+hadara task finish --task T-XXXX --execute --json
+hadara task ready --task T-XXXX --level done --json
+hadara task close --task T-XXXX --json
+hadara task close --task T-XXXX --execute --json
+hadara task audit-close --task T-XXXX --json
 ```
 
+Those commands are canonical proof boundaries under the wrapper, but they are no longer the default agent-facing cycle.
+
 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` | 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. |
+| `task lifecycle` | Read-only normalized lifecycle phase report for agents. |
+| `task close-repair-plan` | Read-only close-proof repair classifier. |
+| `task finalize` | Default agent close path. Read-only by default; guarded execute requires a matching current `planHash` and preserves underlying write boundaries. |
+| `task finish` / `task ready` / `task close` / `task audit-close` | Low-level proof-boundary commands for debugging and recovery. |
 
-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.
+Before executing `task finalize`, finish Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, Task Board updates, and tracked state docs. After final close proof, changing close-source docs intentionally invalidates the previous close proof and requires rerunning finalize or the low-level ready/close/audit sequence.
 
 The full command semantics live in `docs/TASK_WORKFLOW_COMMANDS.md`.
 
@@ -245,7 +260,7 @@ Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay
 
 ## Safety Boundaries
 
-HADARA 0.3.2 is not:
+HADARA 0.3.3-rc.0 is not:
 
 - a full agent runtime;
 - Rack/enterprise behavior;
@@ -285,7 +300,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.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.
+0.3.3-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.
 
 ## Development / Contributing
 
@@ -298,7 +313,7 @@ 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.
+Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current 0.3.3 finalize-first lifecycle loop plus low-level proof-boundary reference commands.
 
 | Profile | Use When |
 |---|---|

package/dist/cli/context.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleContextCommand = handleContextCommand;
+const args_1 = require("./args");
+const context_cache_store_1 = require("../context/context-cache-store");
+const context_graph_builder_1 = require("../context/context-graph-builder");
+const context_pack_1 = require("../context/context-pack");
+const context_slice_1 = require("../context/context-slice");
+function handleContextCommand(input) {
+    const sub = input.args[1];
+    if (sub === 'graph')
+        return handleContextGraphCommand(input);
+    if (sub === 'pack')
+        return handleContextPackCommand(input);
+    if (sub === 'slice')
+        return handleContextSliceCommand(input);
+    if (sub === 'cache')
+        return handleContextCacheCommand(input);
+    return false;
+}
+function handleContextGraphCommand(input) {
+    const taskId = (0, args_1.getStringOption)(input.args, '--task');
+    const includeCode = (0, args_1.getFlag)(input.args, '--include-code');
+    const report = (0, context_graph_builder_1.buildContextGraphReport)({
+        projectRoot: input.projectRoot,
+        includeCode,
+        ...(taskId ? { taskId, mode: 'task' } : { mode: 'full' })
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function handleContextPackCommand(input) {
+    const taskId = (0, args_1.getStringOption)(input.args, '--task');
+    const includeCode = (0, args_1.getFlag)(input.args, '--include-code');
+    const budget = contextPackBudgetFromArgs(input.args);
+    const report = (0, context_pack_1.buildContextPackReport)({
+        projectRoot: input.projectRoot,
+        includeCode,
+        ...(taskId ? { taskId } : {}),
+        ...(Object.keys(budget).length > 0 ? { budget } : {})
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function handleContextSliceCommand(input) {
+    const report = (0, context_slice_1.buildContextSliceReport)({
+        projectRoot: input.projectRoot,
+        path: (0, args_1.getStringOption)(input.args, '--path'),
+        from: (0, args_1.getIntegerOption)(input.args, '--from', { min: 1 }),
+        to: (0, args_1.getIntegerOption)(input.args, '--to', { min: 1 }),
+        symbol: (0, args_1.getStringOption)(input.args, '--symbol'),
+        keyword: (0, args_1.getStringOption)(input.args, '--keyword'),
+        window: (0, args_1.getIntegerOption)(input.args, '--window', { min: 0, max: 500 }),
+        tail: (0, args_1.getIntegerOption)(input.args, '--tail', { min: 1, max: 1000 }),
+        managedSection: (0, args_1.getStringOption)(input.args, '--managed-section'),
+        taskId: (0, args_1.getStringOption)(input.args, '--task'),
+        candidateId: (0, args_1.getStringOption)(input.args, '--candidate'),
+        includeCode: (0, args_1.getFlag)(input.args, '--include-code')
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function handleContextCacheCommand(input) {
+    const action = input.args[2];
+    if (action !== 'status' && action !== 'warm')
+        return false;
+    const report = action === 'status'
+        ? (0, context_cache_store_1.createContextCacheStatusReport)({ projectRoot: input.projectRoot })
+        : (0, context_cache_store_1.createContextCacheWarmReport)({ projectRoot: input.projectRoot, execute: (0, args_1.getFlag)(input.args, '--execute') });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function contextPackBudgetFromArgs(args) {
+    const targetTokens = (0, args_1.getIntegerOption)(args, '--budget', { min: 1 });
+    const maxItems = (0, args_1.getIntegerOption)(args, '--max-items', { min: 1, max: 500 });
+    const maxReadFirstItems = (0, args_1.getIntegerOption)(args, '--max-read-first', { min: 1, max: 100 });
+    return {
+        ...(targetTokens !== undefined ? { targetTokens } : {}),
+        ...(maxItems !== undefined ? { maxItems } : {}),
+        ...(maxReadFirstItems !== undefined ? { maxReadFirstItems } : {})
+    };
+}

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', 'finish', 'ready', 'close', 'audit', 'handoff'];
+const LIFECYCLE_ORDER = ['discover', 'create', 'inspect', 'evidence', 'phase-check', 'finalize', 'handoff'];
 function handleHelpCommand(input) {
     const topic = input.args[1];
     if (!topic) {
@@ -74,17 +74,16 @@ 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 canonical task lifecycle',
+        'HADARA 0.3.3 primary task lifecycle',
         '',
         'Primary capsule lifecycle:'
     ];
     for (const step of report.primaryPath) {
-        lines.push(`  ${step.order} ${step.stage.padEnd(9)} ${step.command}`);
-        if (step.commandId === 'task.finish')
-            lines.push('             hadara task finish --task T-XXXX --execute --json');
-        if (step.commandId === 'task.close')
-            lines.push('             hadara task close --task T-XXXX --execute --json');
+        lines.push(`  ${step.order} ${step.stage.padEnd(11)} ${step.command}`);
+        if (step.commandId === 'task.finalize')
+            lines.push('               hadara task finalize --task T-XXXX --execute --plan-hash sha256:... --json');
     }
+    lines.push('', 'Low-level proof-boundary commands are available through `hadara help family capsule-lifecycle`.');
     lines.push('', 'Diagnostics when blocked:');
     for (const entry of diagnostics)
         lines.push(`  ${entry.id}  ${entry.command}`);

package/dist/cli/init.js

@@ -1087,10 +1087,10 @@ Keep capsule docs current as work changes:
 | Before execution | \`PLAN.md\` |
 | During execution | \`DECISIONS.md\`, \`RISKS.md\`, and \`FILES.md\` |
 | Immediately after validation | \`TESTS.md\` and \`EVIDENCE.md\` |
-| Before finish/ready/close | \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs |
+| Before finalize execute | \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs |
 | Before close-source hash is captured | \`docs/TASK_BOARD.md\`, \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when applicable |
 
-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.
+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 finalize --execute\`, low-level \`task finish --execute\`, low-level \`task close --execute\`, and release artifact or publish operations.
 
 ## Status Token And Document Ownership Policy
 
@@ -1100,11 +1100,11 @@ Use distinct token families for persistent task state, close proof state, docume
 
 \`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.
+Ownership boundaries follow the lifecycle command model. \`task finalize --execute --plan-hash <hash>\` is the default 0.3.3 agent close path and preserves the underlying write boundaries: \`task finish --execute\` owns bounded status bookkeeping in \`TASK.md\` and command-owned \`docs/TASK_BOARD.md\` cells, and \`task close --execute\` owns only close evidence append. Operators own close-source prose and shared state docs before finalize execute, then rerun finalize or the low-level ready/close/audit sequence 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:
+The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. From 0.3.3 onward, agents should use this loop for ordinary implementation capsules:
 
 \`\`\`bash
 hadara task next --json
@@ -1120,20 +1120,11 @@ 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
 
-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 task lifecycle --task T-XXXX --json
+hadara task finalize --task T-XXXX --json
+hadara task finalize --task T-XXXX --execute --plan-hash sha256:... --json
 \`\`\`
 
 | Command | Default Write Behavior | Notes |
@@ -1141,24 +1132,24 @@ 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 \`--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. |
-| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+| \`task lifecycle\` | Read-only | Reports normalized lifecycle phase, checks, blockers, and one next action. |
+| \`task close-repair-plan\` | Read-only | Classifies close proof repair state and exact repair command. |
+| \`task finalize\` | Read-only by default; guarded execute requires \`--plan-hash\` | Default agent close path. Rechecks the current plan hash, executes phases serially, stops on blockers, and preserves finish/close write boundaries. |
+| \`task finish\` / \`task ready\` / \`task close\` / \`task audit-close\` | Low-level proof-boundary commands | Use directly for debugging, recovery, or command implementation work. |
 
-Before running \`task ready\` and \`task 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\`, do not edit those close-source documents unless you intend to rerun \`task ready\`, \`task close\`, and \`task audit-close\`. Avoid writing volatile close evidence ids into close-source docs; use stable wording such as "close evidence appended; audit returned closed-valid".
+Before running \`task finalize --execute\`, 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 finalize closes the task, do not edit those close-source documents unless you intend to rerun finalize or the low-level \`task ready\`, \`task close\`, and \`task audit-close\` sequence. Avoid writing volatile close evidence ids into close-source docs; use stable wording such as "close evidence appended; audit returned closed-valid".
 
 ## Validation
 
 1. Run relevant tests.
 2. Record meaningful evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
-3. Preview and execute \`hadara task finish --task <task-id> --json\` and \`hadara task finish --task <task-id> --execute --json\`.
-4. Finalize Task Capsule docs and tracked state docs before close so the close source hash remains stable.
-5. Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close.
-6. Preview and execute \`hadara task close --task <task-id> --json\` and \`hadara task close --task <task-id> --execute --json\`, then run \`hadara task audit-close --task <task-id> --json\`.
+3. Finalize Task Capsule docs and tracked state docs before close so the close source hash remains stable.
+4. Run \`hadara task lifecycle --task <task-id> --json\` when you need a compact phase check.
+5. Run \`hadara task finalize --task <task-id> --json\`, review the current plan hash and write boundaries, then execute \`hadara task finalize --task <task-id> --execute --plan-hash <hash> --json\`.
+6. Use low-level \`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` only when debugging or repairing one proof boundary directly.
 7. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
 
-\`task ready\` and \`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task <task-id> --level done --json\` directly when you need to debug capsule format or done-level validation failures.
+\`task finalize\` and low-level \`task ready\`/\`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task <task-id> --level done --json\` directly when you need to debug capsule format or done-level validation failures.
 
 ## Evidence Records
 
@@ -1274,16 +1265,16 @@ function createTestStrategyDoc() {
 |---|---|---|
 | 1 | Run the relevant suite from the table above. | Task Capsule \`EVIDENCE.md\` |
 | 2 | Record meaningful evidence in the Task Capsule. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
-| 3 | Preview and execute \`task finish\` to synchronize status bookkeeping. | Task Capsule \`TASK.md\` and \`docs/TASK_BOARD.md\` |
-| 4 | Finalize Task Capsule docs and tracked state docs before close. | Task Capsule docs and tracked state docs |
-| 5 | Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
-| 6 | Preview and execute \`task close\`, then run \`task audit-close\`. | Task Capsule close evidence |
+| 3 | Finalize Task Capsule docs and tracked state docs before close. | Task Capsule docs and tracked state docs |
+| 4 | Run \`hadara task lifecycle --task <task-id> --json\` when you need a compact phase check. | Task Capsule docs and evidence |
+| 5 | Run \`hadara task finalize --task <task-id> --json\`, review the plan hash, then execute \`hadara task finalize --task <task-id> --execute --plan-hash <hash> --json\`. | Task Capsule close evidence |
+| 6 | Use low-level \`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` only when debugging or repairing one proof boundary directly. | Task Capsule evidence |
 
 ## Diagnostic Checks
 
 | Check | Command | When To Use |
 |---|---|---|
-| Task Capsule format | \`hadara harness validate --task <task-id> --level done --json\` | \`task ready\` or \`task close\` reports done-level validation failures. |
+| Task Capsule format | \`hadara harness validate --task <task-id> --level done --json\` | \`task finalize\` or low-level \`task ready\`/\`task close\` reports done-level validation failures. |
 | Evidence index | \`hadara evidence lint --task <task-id> --json\` | Evidence files were touched manually by mistake or evidence drift is suspected. |
 
 ## Special-Case Checks
@@ -1324,7 +1315,7 @@ HADARA task workflow commands are split by responsibility. Similar-looking comma
 
 ## Standard Task Loop
 
-Use this loop for ordinary implementation capsules:
+From 0.3.3 onward, agents should use the finalize-first loop for ordinary implementation capsules:
 
 \`\`\`bash
 hadara task next --json
@@ -1340,27 +1331,31 @@ 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
 
-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
+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
+\`\`\`
+
+\`task finalize --json\` is the reviewed dry-run. It reports the current lifecycle step, write boundaries, expected write paths, and a current \`planHash\`. \`task finalize --execute --plan-hash ...\` rechecks that plan hash, runs the underlying phases serially, stops on the first blocker, and succeeds only after the final close audit is \`closed-valid\`.
 
-# Optional workflow compression / next action preview:
-hadara task complete --task T-XXXX --json
+Low-level proof-boundary commands remain available for debugging, recovery, and command implementation work:
 
+\`\`\`bash
+hadara task finish --task T-XXXX --json
+hadara task finish --task T-XXXX --execute --json
+hadara task ready --task T-XXXX --level done --json
 hadara task close --task T-XXXX --json
 hadara task close --task T-XXXX --execute --json
-
 hadara task audit-close --task T-XXXX --json
 \`\`\`
 
-\`task finish\`, \`task ready\`, and \`task close\` are intentionally separate. \`finish\` synchronizes bounded status bookkeeping first. \`ready\` then validates the Done-level state. \`close\` records close evidence after validation succeeds. \`audit-close\` checks the resulting close evidence after the write.
+\`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` are canonical proof boundaries under \`task finalize\`, but they are not the default agent-facing cycle. \`finish\` synchronizes bounded status bookkeeping first. \`ready\` then validates the Done-level state. \`close\` records close evidence after validation succeeds. \`audit-close\` checks the resulting close evidence after the write.
 
 The close model has three separate phases: validation proves readiness, close records the proof, and audit checks the already-recorded close evidence. Close evidence is excluded from the current validation loop because it is appended after validation; requiring it as a same-run precondition would create a fixed-point loop.
 
-\`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.
+\`task finalize\` and low-level \`task ready\`/\`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
 
@@ -1424,15 +1419,15 @@ Evidence outcome tokens are \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`
 | 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".
+Before finalize execute, 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 finalize --execute --plan-hash ...\` reaches close proof, changing those documents changes the close source hash and requires rerunning finalize or the low-level \`task ready\`, \`task close\`, and \`task audit-close\` sequence. 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
 
-Do not defer all documentation until after implementation. Keep \`PLAN.md\` current before execution; update \`DECISIONS.md\`, \`RISKS.md\`, and \`FILES.md\` during execution; update \`TESTS.md\` and \`EVIDENCE.md\` immediately after validation; update \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs before finish/ready/close; and update shared close-source docs before the close-source hash is captured.
+Do not defer all documentation until after implementation. Keep \`PLAN.md\` current before execution; update \`DECISIONS.md\`, \`RISKS.md\`, and \`FILES.md\` during execution; update \`TESTS.md\` and \`EVIDENCE.md\` immediately after validation; update \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs before finalize execute; and update shared close-source docs before the close-source hash is captured.
 
 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.
+Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board writes, Project State writes, Agent Handoff writes, before-hash execute operations, \`task finalize --execute\`, low-level \`task finish --execute\`, low-level \`task close --execute\`, and release artifact or publish operations.
 
 ## Command Semantics
 
@@ -1442,30 +1437,33 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 | \`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 \`--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. |
-| \`task close\` | Dry-run by default; writes only with \`--execute\` | Appends only canonical close evidence after close preconditions pass. |
-| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+| \`task lifecycle\` | Read-only | Reports normalized lifecycle phase, checks, blockers, repair metadata, and one next action. |
+| \`task close-repair-plan\` | Read-only | Classifies close proof repair state and exact repair command. |
+| \`task finalize\` | Read-only by default; guarded execute requires \`--plan-hash\` | Default agent close path. Rechecks the current plan hash, executes phases serially, stops on blockers, and succeeds only after final audit is \`closed-valid\`. |
+| \`task finish\` / \`task ready\` / \`task close\` / \`task audit-close\` | Low-level proof-boundary commands | Use directly for debugging, recovery, or command implementation work. |
+| \`task complete\` | Legacy read-only workflow compressor | Summarizes the current completion stage and next command; prefer \`task lifecycle\` and \`task finalize\` for 0.3.3 agent flows. |
 
 ## Non-Overlap Rules
 
 - \`task next\` chooses work; it does not create a capsule or infer completion.
 - \`task status\` is an operator console; \`ok: true\` means report generation succeeded, not that the task is ready.
-- \`task ready\` checks readiness; it does not write evidence or status.
+- \`task ready\` checks readiness; it does not write evidence or status. In normal 0.3.3 agent work, call it through \`task finalize\` unless debugging a readiness blocker directly.
 - \`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.
+- \`task complete\` is a legacy read-only workflow compressor. It may report the next lifecycle command, but it must not execute finish, ready, close, or audit commands. Prefer \`task lifecycle\` and \`task finalize\` for 0.3.3 agent flows.
+- \`task lifecycle\` is the read-only normalized phase API for agents.
+- \`task close-repair-plan\` is a read-only close-proof repair classifier.
+- \`task finalize\` is read-only by default. Guarded execute requires a matching current dry-run \`planHash\`, runs phases serially, stops on blockers, and returns success only after \`task audit-close\` is \`closed-valid\`.
 - \`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.
-- \`task audit-close\` is read-only and should be run after \`task close --execute --json\`.
+- \`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. In normal 0.3.3 agent work, call it through \`task finalize --execute\`.
+- \`task close\` may append only close evidence. It must not update status docs, Task Board rows, handoff, Project State, roadmap docs, or arbitrary evidence. In normal 0.3.3 agent work, call it through \`task finalize --execute\`.
+- After close proof is recorded, close-source document edits intentionally invalidate the previous close proof. Make those edits before finalize execute, or rerun finalize/low-level ready-close-audit if the edit is unavoidable.
+- \`task audit-close\` is read-only and is normally reached through \`task finalize --execute\`.
 
 ## State Documents
 
-\`task finish --execute --json\` deliberately does not update broad prose state. Operators still update \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and any roadmap/slice docs generated for the selected profile when the task changes project state.
+\`task finalize --execute --plan-hash <hash>\` deliberately preserves narrow write boundaries; it does not update broad prose state beyond the underlying finish/close writes. Operators still update \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and any roadmap/slice docs generated for the selected profile before finalize when the task changes project state.
 `;
 }
 function createAgentsDoc(spec) {
@@ -1497,8 +1495,8 @@ function createAgentsDoc(spec) {
         ['Task creation', 'If no suitable capsule exists, create one with `hadara task create <title>`.', '`docs/TASK_BOARD.md`'],
         ['Evidence', 'Do not mark work done without evidence. Do not hand-edit `evidence.jsonl`; record failed or blocked checks honestly instead of replacing them with optimistic summaries.', '`EVIDENCE.md`, `evidence.jsonl`'],
         ['Documentation timing', 'Do not defer all documentation until after implementation; keep capsule docs current as work changes.', 'Task Capsule docs and shared state docs'],
-        ['Write coordination', 'Parallelize read-only discovery and independent validation; serialize evidence append, Task Capsule doc writes, shared state doc writes, before-hash executes, finish/close executes, and release/publish operations.', 'Task Capsule evidence'],
-        ['Task workflow', 'For task workflow commands, follow `docs/TASK_WORKFLOW_COMMANDS.md`: record evidence, preview and execute `task finish`, finalize close-source docs, run `task ready`, preview and execute `task close`, then run `task audit-close`.', 'Task Capsule evidence'],
+        ['Write coordination', 'Parallelize read-only discovery and independent validation; serialize evidence append, Task Capsule doc writes, shared state doc writes, before-hash executes, `task finalize --execute`, low-level finish/close executes, and release/publish operations.', 'Task Capsule evidence'],
+        ['Task workflow', 'For task workflow commands, follow `docs/TASK_WORKFLOW_COMMANDS.md`: from 0.3.3 onward, agents should use `task lifecycle` and reviewed `task finalize --json` / `task finalize --execute --plan-hash <hash>` as the default close path. Use `task finish`, `task ready`, `task close`, and `task audit-close` only as low-level proof-boundary commands for debugging, recovery, or command implementation work.', 'Task Capsule evidence'],
         ['Safety', 'Do not execute dangerous commands without explicit user approval.', 'Task Capsule evidence'],
         ['Secrets', 'Do not write secrets, private logs, or machine-local state into committed files.', 'Changed-file review'],
         ['Store boundary', 'Preserve the portable/project store boundary.', spec.docs.architecture ? '`.gitignore`, `docs/ARCHITECTURE.md`' : '`.gitignore`'],

package/dist/cli/main.js

@@ -179,6 +179,18 @@ async function main(args = process.argv.slice(2)) {
                 return;
             break;
         }
+        case 'context': {
+            const { handleContextCommand } = await Promise.resolve().then(() => __importStar(require('./context')));
+            if (handleContextCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
+                return;
+            break;
+        }
+        case 'session': {
+            const { handleSessionCommand } = await Promise.resolve().then(() => __importStar(require('./session')));
+            if (handleSessionCommand({ 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/session.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSessionCommand = handleSessionCommand;
+const args_1 = require("./args");
+const session_start_1 = require("../context/session-start");
+function handleSessionCommand(input) {
+    const sub = input.args[1];
+    if (sub !== 'start')
+        return false;
+    const budget = sessionStartBudgetFromArgs(input.args);
+    const report = (0, session_start_1.buildSessionStartReport)({
+        projectRoot: input.projectRoot,
+        taskId: (0, args_1.getStringOption)(input.args, '--task'),
+        includeCode: (0, args_1.getFlag)(input.args, '--include-code'),
+        allowLiveContextPack: (0, args_1.getFlag)(input.args, '--live'),
+        ...(Object.keys(budget).length > 0 ? { budget } : {})
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
+function sessionStartBudgetFromArgs(args) {
+    const targetTokens = (0, args_1.getIntegerOption)(args, '--budget', { min: 1 });
+    const maxItems = (0, args_1.getIntegerOption)(args, '--max-items', { min: 1, max: 200 });
+    const maxReadFirstItems = (0, args_1.getIntegerOption)(args, '--max-read-first', { min: 1, max: 50 });
+    return {
+        ...(targetTokens !== undefined ? { targetTokens } : {}),
+        ...(maxItems !== undefined ? { maxItems } : {}),
+        ...(maxReadFirstItems !== undefined ? { maxReadFirstItems } : {})
+    };
+}