hadara 0.3.2 → 0.3.3

package/dist/schemas/task-finalize.schema.json

@@ -0,0 +1,98 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.task.finalize.v1",
+    "x-hadara-schema-id": "hadara.task.finalize.v1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "readOnly", "mode", "taskId", "generatedAt", "actor", "summary", "steps", "nextActions", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.task.finalize.v1" },
+        "command": { "const": "task.finalize" },
+        "ok": { "type": "boolean" },
+        "readOnly": { "type": "boolean" },
+        "mode": { "enum": ["dry-run", "execute", "execute-refused"] },
+        "taskId": { "type": "string" },
+        "generatedAt": { "type": "string" },
+        "actor": { "type": "object", "additionalProperties": true },
+        "planHash": { "type": "string" },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["steps", "required", "blocked", "satisfied", "executeSupported"],
+            "properties": {
+                "steps": { "type": "number" },
+                "required": { "type": "number" },
+                "blocked": { "type": "number" },
+                "satisfied": { "type": "number" },
+                "executeSupported": { "type": "boolean" },
+                "evaluatedReports": { "type": "array", "items": { "type": "string" } },
+                "skippedReports": { "type": "array", "items": { "type": "string" } }
+            }
+        },
+        "steps": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["id", "status", "summary", "command", "mode", "writeBoundary", "expectedWritePaths", "alreadySatisfied", "sourceReport"],
+                "properties": {
+                    "id": { "enum": ["finish", "ready", "close", "audit-close"] },
+                    "status": { "enum": ["satisfied", "required", "blocked", "pending", "unknown"] },
+                    "summary": { "type": "string" },
+                    "command": { "type": "string" },
+                    "mode": { "enum": ["dry-run", "execute", "read-only"] },
+                    "writeBoundary": { "enum": ["read-only", "task-local", "evidence-append"] },
+                    "expectedWritePaths": { "type": "array", "items": { "type": "string" } },
+                    "alreadySatisfied": { "type": "boolean" },
+                    "sourceReport": { "type": "string" }
+                }
+            }
+        },
+        "execution": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["planHashMatched", "executedSteps"],
+            "properties": {
+                "requestedPlanHash": { "type": "string" },
+                "currentPlanHash": { "type": "string" },
+                "planHashMatched": { "type": "boolean" },
+                "stoppedAt": { "enum": ["finish", "ready", "close", "audit-close"] },
+                "executedSteps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": true,
+                        "required": ["id", "status", "command", "ok", "reportHash", "summary", "writeBoundary"],
+                        "properties": {
+                            "id": { "enum": ["finish", "ready", "close", "audit-close"] },
+                            "status": { "enum": ["executed", "satisfied", "blocked", "skipped"] },
+                            "command": { "type": "string" },
+                            "ok": { "type": "boolean" },
+                            "reportHash": { "type": "string" },
+                            "summary": { "type": "string" },
+                            "writeBoundary": { "enum": ["read-only", "task-local", "evidence-append"] }
+                        }
+                    }
+                }
+            }
+        },
+        "primaryNextAction": { "type": "object", "additionalProperties": true },
+        "nextActions": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+        "issues": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["severity", "code", "message"],
+                "properties": {
+                    "severity": { "enum": ["error", "warning", "info"] },
+                    "code": { "type": "string" },
+                    "message": { "type": "string" },
+                    "path": { "type": "string" },
+                    "fixHint": { "type": "string" },
+                    "example": { "type": "string" }
+                }
+            }
+        }
+    }
+}

package/dist/schemas/task-lifecycle.schema.json

@@ -0,0 +1,84 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.task.lifecycle.v1",
+    "x-hadara-schema-id": "hadara.task.lifecycle.v1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "readOnly", "taskId", "generatedAt", "actor", "phase", "checks", "satisfied", "blockers", "nextActions", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.task.lifecycle.v1" },
+        "command": { "const": "task.lifecycle" },
+        "ok": { "type": "boolean" },
+        "readOnly": { "const": true },
+        "taskId": { "type": "string" },
+        "generatedAt": { "type": "string" },
+        "actor": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["agentId", "runId", "role", "parentRunId"],
+            "properties": {
+                "agentId": { "type": "string" },
+                "runId": { "type": "string" },
+                "role": { "enum": ["operator", "coordinator", "worker", "reviewer", "unknown"] },
+                "parentRunId": { "type": ["string", "null"] }
+            }
+        },
+        "phase": {
+            "enum": ["draft", "in-progress", "finish-required", "ready-required", "close-required", "audit-required", "closed-valid", "repair-required", "blocked", "unknown"]
+        },
+        "checks": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["finish", "sharedDocs", "ready", "close", "audit"],
+            "properties": {
+                "finish": { "$ref": "#/$defs/check" },
+                "sharedDocs": { "$ref": "#/$defs/check" },
+                "ready": { "$ref": "#/$defs/check" },
+                "close": { "$ref": "#/$defs/check" },
+                "audit": { "$ref": "#/$defs/check" }
+            }
+        },
+        "satisfied": { "type": "array", "items": { "type": "string" } },
+        "blockers": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["code", "severity", "summary"],
+                "properties": {
+                    "code": { "type": "string" },
+                    "severity": { "enum": ["error", "warning"] },
+                    "summary": { "type": "string" },
+                    "command": { "type": "string" }
+                }
+            }
+        },
+        "repair": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["classification", "summary", "sourceReport"],
+            "properties": {
+                "classification": { "enum": ["not-closed", "closed-stale", "closed-invalid", "duplicate-close-proof", "closed-valid", "unknown"] },
+                "summary": { "type": "string" },
+                "nextCommand": { "type": "string" },
+                "sourceReport": { "const": "hadara.task.audit_close.v1" }
+            }
+        },
+        "primaryNextAction": { "type": "object", "additionalProperties": true },
+        "nextActions": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+        "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
+    },
+    "$defs": {
+        "check": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["status", "summary", "sourceReport"],
+            "properties": {
+                "status": { "enum": ["satisfied", "required", "blocked", "warning", "pending", "unknown"] },
+                "summary": { "type": "string" },
+                "sourceReport": { "type": "string" },
+                "command": { "type": "string" }
+            }
+        }
+    }
+}

package/dist/services/capability-registry.js

@@ -338,18 +338,93 @@ exports.HADARA_COMMAND_REGISTRY = [
         examples: [example('Show completion guide', 'hadara task complete --task T-0001 --json', 'When debugging the task close loop.')],
         related: ['task.finish', 'task.ready', 'task.close', 'task.audit-close'],
         conflictsWith: [],
-        notes: 'Primary lifecycle help should show the explicit finish/ready/close/audit sequence.'
+        notes: 'Legacy read-only workflow compressor. Primary lifecycle help should show the 0.3.3 finalize-first path.'
+    },
+    {
+        id: 'task.finalize',
+        command: 'hadara task finalize --task <task-id> [--execute --plan-hash <hash>] [--json]',
+        summary: 'Create a reviewed finalize plan or execute the matching plan through the guarded lifecycle sequence.',
+        canonical: true,
+        appearsInDefaultHelp: true,
+        family: 'capsule-lifecycle',
+        scope: 'capsule',
+        lifecycleStage: 'finalize',
+        requiredness: 'primary',
+        writeBoundary: 'task-status-bookkeeping',
+        readOnly: false,
+        risk: 'medium',
+        actor: 'agent-worker',
+        status: 'stable',
+        schemaVersion: 'hadara.task.finalize.v1',
+        docs: TASK_DOCS,
+        implementationFiles: ['src/cli/task.ts', 'src/task/task-finalize.ts'],
+        testFiles: ['tests/unit/task-finalize.test.ts'],
+        examples: [
+            example('Review finalize plan', 'hadara task finalize --task T-0001 --json', 'When an agent wants one reviewed finish/ready/close/audit plan before executing the default close path.'),
+            example('Execute reviewed finalize plan', 'hadara task finalize --task T-0001 --execute --plan-hash sha256:... --json', 'After reviewing a current dry-run plan hash.')
+        ],
+        related: ['task.lifecycle', 'task.finish', 'task.ready', 'task.close', 'task.audit-close'],
+        conflictsWith: [],
+        notes: 'Default mode is read-only. Execute requires a matching current dry-run plan hash, runs phases serially, preserves the underlying finish/close write boundaries, and stops on the first blocker.'
+    },
+    {
+        id: 'task.lifecycle',
+        command: 'hadara task lifecycle --task <task-id> [--json]',
+        summary: 'Read normalized lifecycle phase, checks, satisfied state, blockers, and next action for one task.',
+        canonical: true,
+        appearsInDefaultHelp: true,
+        family: 'capsule-lifecycle',
+        scope: 'capsule',
+        lifecycleStage: 'phase-check',
+        requiredness: 'primary',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'stable',
+        schemaVersion: 'hadara.task.lifecycle.v1',
+        docs: TASK_DOCS,
+        implementationFiles: ['src/cli/task.ts', 'src/task/task-lifecycle.ts'],
+        testFiles: ['tests/unit/task-lifecycle.test.ts'],
+        examples: [example('Inspect lifecycle phase', 'hadara task lifecycle --task T-0001 --json', 'When an agent needs one read-only phase report before deciding the next lifecycle command.')],
+        related: ['task.status', 'task.finish', 'task.ready', 'task.close', 'task.audit-close'],
+        conflictsWith: [],
+        notes: 'Default 0.3.3 agent-facing phase report. Low-level finish/ready/close/audit-close proof commands remain available for debugging and recovery.'
+    },
+    {
+        id: 'task.close-repair-plan',
+        command: 'hadara task close-repair-plan --task <task-id> [--json]',
+        summary: 'Classify close proof repair state and return exact repair next actions.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'capsule-lifecycle',
+        scope: 'capsule',
+        lifecycleStage: 'inspect',
+        requiredness: 'conditional',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'stable',
+        schemaVersion: 'hadara.task.closeRepairPlan.v1',
+        docs: TASK_DOCS,
+        implementationFiles: ['src/cli/task.ts', 'src/task/task-close-repair-plan.ts'],
+        testFiles: ['tests/unit/task-close-repair-plan.test.ts'],
+        examples: [example('Plan close repair', 'hadara task close-repair-plan --task T-0001 --json', 'When audit-close reports missing, stale, invalid, or duplicate close proof state.')],
+        related: ['task.lifecycle', 'task.close', 'task.audit-close'],
+        conflictsWith: [],
+        notes: 'This command is read-only and does not append replacement close evidence.'
     },
     {
         id: 'task.finish',
         command: 'hadara task finish --task <task-id> [--execute] [--json]',
         summary: 'Preview or apply bounded Task Capsule status and close-source documentation updates.',
         canonical: true,
-        appearsInDefaultHelp: true,
+        appearsInDefaultHelp: false,
         family: 'capsule-lifecycle',
         scope: 'capsule',
         lifecycleStage: 'finish',
-        requiredness: 'primary',
+        requiredness: 'advanced',
         writeBoundary: 'task-status-bookkeeping',
         readOnly: false,
         risk: 'medium',
@@ -389,11 +464,11 @@ exports.HADARA_COMMAND_REGISTRY = [
         command: 'hadara task ready --task <task-id> [--level done] [--json]',
         summary: 'Run read-only readiness checks before close evidence is appended.',
         canonical: true,
-        appearsInDefaultHelp: true,
+        appearsInDefaultHelp: false,
         family: 'capsule-lifecycle',
         scope: 'capsule',
         lifecycleStage: 'ready',
-        requiredness: 'primary',
+        requiredness: 'advanced',
         writeBoundary: 'read-only',
         readOnly: true,
         risk: 'low',
@@ -410,11 +485,11 @@ exports.HADARA_COMMAND_REGISTRY = [
         command: 'hadara task close --task <task-id> [--execute] [--json]',
         summary: 'Preview or append close proof after readiness passes.',
         canonical: true,
-        appearsInDefaultHelp: true,
+        appearsInDefaultHelp: false,
         family: 'capsule-lifecycle',
         scope: 'capsule',
         lifecycleStage: 'close',
-        requiredness: 'primary',
+        requiredness: 'advanced',
         writeBoundary: 'close-evidence-append',
         readOnly: false,
         risk: 'medium',
@@ -422,6 +497,8 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         schemaVersion: 'hadara.task.close.v1',
         docs: TASK_DOCS,
+        implementationFiles: ['src/cli/task.ts', 'src/task/task-close.ts'],
+        testFiles: ['tests/unit/task-close.test.ts'],
         examples: [
             example('Preview close', 'hadara task close --task T-0001 --json', 'After task ready passes.'),
             example('Append close proof', 'hadara task close --task T-0001 --execute --json', 'After reviewing the dry-run report.')
@@ -434,11 +511,11 @@ exports.HADARA_COMMAND_REGISTRY = [
         command: 'hadara task audit-close --task <task-id> [--json]',
         summary: 'Audit appended close proof and detect post-close drift.',
         canonical: true,
-        appearsInDefaultHelp: true,
+        appearsInDefaultHelp: false,
         family: 'capsule-lifecycle',
         scope: 'capsule',
         lifecycleStage: 'audit',
-        requiredness: 'primary',
+        requiredness: 'advanced',
         writeBoundary: 'read-only',
         readOnly: true,
         risk: 'low',
@@ -514,6 +591,8 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         schemaVersion: 'hadara.evidence.list.v1',
         docs: ['docs/IMPLEMENTATION_SOP.md'],
+        implementationFiles: ['src/cli/evidence.ts', 'src/services/evidence-list.ts'],
+        testFiles: ['tests/unit/evidence-list.test.ts', 'tests/unit/evidence-json.test.ts'],
         examples: [example('List evidence ids', 'hadara evidence list --task T-0001', 'Before copying a durable ev: id into --resolves or --supersedes.')],
         related: ['evidence.add-command', 'evidence.lint'],
         conflictsWith: []
@@ -642,6 +721,180 @@ exports.HADARA_COMMAND_REGISTRY = [
         related: ['status', 'protocol.doctor', 'ci.gate'],
         conflictsWith: []
     },
+    commandEntry({
+        id: 'context.graph',
+        command: 'hadara context graph [--task <task-id>] [--include-code] --json',
+        summary: 'Emit the read-only project context graph, optional task context report, and opt-in code graph extension.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'project',
+        lifecycleStage: 'inspect',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.contextGraph.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/context.ts', 'src/context/context-graph-builder.ts', 'src/context/code-graph-extractor.ts'],
+        testFiles: ['tests/unit/context-graph-cli.test.ts', 'tests/unit/context-graph-builder.test.ts'],
+        examples: [
+            example('Read full context graph', 'hadara context graph --json', 'When a worker needs project context routing signals.'),
+            example('Read task context graph', 'hadara context graph --task T-0001 --json', 'When a worker needs task-scoped docs, evidence, commands, and known problems.'),
+            example('Read code-aware context graph', 'hadara context graph --include-code --json', 'When a worker needs source, test, symbol, and code relation candidates.')
+        ],
+        related: ['state.verify', 'docs.required-reading', 'task.status'],
+        conflictsWith: [],
+        notes: 'Read-only projection; persistent cache support is not implemented yet.'
+    }),
+    commandEntry({
+        id: 'context.pack',
+        command: 'hadara context pack --task <task-id> [--include-code] [--budget <tokens>] [--max-items <count>] [--max-read-first <count>] --json',
+        summary: 'Emit the bounded task-scoped context pack read plan from the current context graph.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'task',
+        lifecycleStage: 'inspect',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.contextPack.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/context.ts', 'src/context/context-pack.ts', 'src/context/context-graph-builder.ts'],
+        testFiles: ['tests/unit/context-graph-cli.test.ts', 'tests/unit/context-pack.test.ts'],
+        examples: [
+            example('Read task context pack', 'hadara context pack --task T-0001 --json', 'When a worker needs the bounded first-read plan for a task.'),
+            example('Read code-aware context pack', 'hadara context pack --task T-0001 --include-code --json', 'When source, test, and symbol candidates should be included.'),
+            example('Read smaller context pack', 'hadara context pack --task T-0001 --max-read-first 3 --max-items 12 --json', 'When a worker needs a tighter bounded read plan.')
+        ],
+        related: ['context.graph', 'state.verify', 'docs.required-reading', 'task.status'],
+        conflictsWith: [],
+        notes: 'Read-only C3 projection; C4 slicing and persistent C6 cache writes are not implemented by this command.'
+    }),
+    commandEntry({
+        id: 'context.slice',
+        command: 'hadara context slice (--path <path> (--from <line> --to <line>|--symbol <name>|--keyword <text> [--window <lines>]|--tail <lines>|--managed-section <section-id>)|--task <task-id> --candidate <candidate-id> [--include-code]) --json',
+        summary: 'Emit deterministic read-only raw context slices from one explicit project file or context-pack candidate.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'project',
+        lifecycleStage: 'inspect',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.contextSlice.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/context.ts', 'src/context/context-slice.ts'],
+        testFiles: ['tests/unit/context-slice.test.ts', 'tests/unit/context-graph-cli.test.ts'],
+        examples: [
+            example('Read an explicit range', 'hadara context slice --path docs/AGENT_HANDOFF.md --from 1 --to 80 --json', 'When a worker needs exact source text from a known range.'),
+            example('Read a symbol neighborhood', 'hadara context slice --path src/cli/context.ts --symbol handleContextCommand --json', 'When a worker needs bounded source around one exported symbol.'),
+            example('Read keyword windows', 'hadara context slice --path docs/TASK_BOARD.md --keyword T-0001 --window 20 --json', 'When a worker needs bounded context around known text.'),
+            example('Read a managed section', 'hadara context slice --path docs/TASK_BOARD.md --managed-section task-board --json', 'When a worker needs marker-bounded managed content.'),
+            example('Read a context-pack candidate', 'hadara context slice --task T-0001 --candidate slice-candidate:1:doc:docs/IMPLEMENTATION_SOP.md --json', 'When a worker wants exact text for a C3 slice candidate.')
+        ],
+        related: ['context.pack', 'context.graph', 'docs.managed.list'],
+        conflictsWith: [],
+        notes: 'C4 implementation reads exact source text through bounded strategies. Candidate slicing resolves against the current C3 context pack and remains read-only.'
+    }),
+    commandEntry({
+        id: 'session.start',
+        command: 'hadara session start [--task <task-id>] [--include-code] [--budget <tokens>] [--max-items <count>] [--max-read-first <count>] [--live] --json',
+        summary: 'Emit a bounded read-only session-start packet composed from context pack, state projection, lifecycle guidance, and cache metadata.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'project',
+        lifecycleStage: 'inspect',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.sessionStart.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/session.ts', 'src/context/session-start.ts', 'src/context/context-pack.ts'],
+        testFiles: ['tests/unit/session-start.test.ts', 'tests/unit/context-graph-cli.test.ts'],
+        examples: [
+            example('Start a bounded session', 'hadara session start --json', 'When a worker needs the default first-read packet for the current project state.'),
+            example('Start a task-scoped session', 'hadara session start --task T-0001 --json', 'When a worker needs bounded context and lifecycle commands for one task.'),
+            example('Start a smaller session packet', 'hadara session start --task T-0001 --max-read-first 3 --max-items 10 --json', 'When a worker needs a tighter packet for limited context windows.'),
+            example('Start a full live session packet', 'hadara session start --task T-0001 --live --json', 'When a worker explicitly accepts live context-pack graph discovery.')
+        ],
+        related: ['context.pack', 'context.graph', 'context.cache.status', 'task.next', 'task.status'],
+        conflictsWith: [],
+        notes: 'C5 MVP is read-only. The default path returns a bounded no-live packet; --live explicitly permits the underlying context-pack graph read.'
+    }),
+    commandEntry({
+        id: 'context.cache.status',
+        command: 'hadara context cache status --json',
+        summary: 'Inspect read-only C6 context cache freshness, source-manifest staleness, and extractor invalidation keys.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'local-state',
+        lifecycleStage: 'inspect',
+        requiredness: 'diagnostic',
+        writeBoundary: 'read-only',
+        readOnly: true,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.context.cacheStatus.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/context.ts', 'src/context/context-cache-store.ts', 'src/context/source-manifest.ts'],
+        testFiles: ['tests/unit/context-cache-store.test.ts', 'tests/unit/context-graph-cli.test.ts'],
+        examples: [
+            example('Read context cache status', 'hadara context cache status --json', 'Before relying on C6 cache-backed context routing performance.')
+        ],
+        related: ['context.graph', 'context.pack', 'state.verify'],
+        conflictsWith: [],
+        notes: 'Read-only status command; it does not create or update cache files. Use context.cache.warm for explicit source-manifest cache writes.'
+    }),
+    commandEntry({
+        id: 'context.cache.warm',
+        command: 'hadara context cache warm [--execute] --json',
+        summary: 'Dry-run or execute C6 source-manifest cache warm phase 1 under the ignored local context cache.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'project-health',
+        scope: 'local-state',
+        lifecycleStage: 'work',
+        requiredness: 'diagnostic',
+        writeBoundary: 'local-cache',
+        readOnly: false,
+        risk: 'low',
+        actor: 'agent-worker',
+        status: 'experimental',
+        schemaVersion: 'hadara.context.cacheWarm.v1',
+        since: '0.3.3',
+        docs: ['docs/CLI_JSON_CONTRACT.md', 'docs/COMMAND_SURFACE.md', 'docs/SCHEMAS.md'],
+        implementationFiles: ['src/cli/context.ts', 'src/context/context-cache-store.ts', 'src/context/source-manifest.ts'],
+        testFiles: ['tests/unit/context-cache-store.test.ts', 'tests/unit/context-graph-cli.test.ts'],
+        examples: [
+            example('Preview context cache warm', 'hadara context cache warm --json', 'Before writing the local source-manifest cache.'),
+            example('Execute context cache warm', 'hadara context cache warm --execute --json', 'After reviewing the warm plan and accepting the ignored local cache write.')
+        ],
+        related: ['context.cache.status', 'context.graph', 'context.pack'],
+        conflictsWith: [],
+        notes: 'Phase 1 warm command writes only source-manifest cache. It does not warm graph, code-index, context-pack, or slice caches.'
+    }),
     commandEntry({
         id: 'debt.list',
         command: 'hadara debt list [--json]',
@@ -1405,6 +1658,8 @@ exports.HADARA_COMMAND_REGISTRY = [
         status: 'stable',
         schemaVersion: 'hadara.releaseDryRun.v1',
         docs: ['docs/RELEASE_READINESS.md'],
+        implementationFiles: ['src/cli/release-dry-run.ts', 'src/services/release-dry-run.ts'],
+        testFiles: ['tests/unit/release-dry-run.test.ts'],
         examples: [example('Run release dry-run', 'hadara release dry-run --json', 'Before publish/deploy readiness checks.')],
         related: ['release.gate', 'release.publish', 'release.artifact'],
         conflictsWith: []
@@ -1617,6 +1872,8 @@ function cloneCommandRegistryEntry(entry) {
     return {
         ...entry,
         aliases: entry.aliases ? [...entry.aliases] : undefined,
+        implementationFiles: entry.implementationFiles ? [...entry.implementationFiles] : undefined,
+        testFiles: entry.testFiles ? [...entry.testFiles] : undefined,
         docs: [...entry.docs],
         examples: entry.examples.map((item) => ({ ...item })),
         related: [...entry.related],

package/dist/services/lifecycle-guide.js

@@ -4,16 +4,14 @@ exports.PORTFOLIO_AUDIT_DECISIONS = exports.PRIMARY_LIFECYCLE_ORDER = void 0;
 exports.createLifecycleGuideReport = createLifecycleGuideReport;
 exports.createCommandPortfolioAuditReport = createCommandPortfolioAuditReport;
 const capability_registry_1 = require("./capability-registry");
-exports.PRIMARY_LIFECYCLE_ORDER = ['discover', 'create', 'inspect', 'evidence', 'finish', 'ready', 'close', 'audit', 'handoff'];
+exports.PRIMARY_LIFECYCLE_ORDER = ['discover', 'create', 'inspect', 'evidence', 'phase-check', 'finalize', 'handoff'];
 const PRIMARY_WHEN = {
     'task.next': 'At session start or after completing a task.',
     'task.create': 'When no suitable Task Capsule exists.',
     'task.status': 'Before editing, validating, or closing a capsule.',
     'evidence.add-command': 'After running project validation or recording relevant work proof.',
-    'task.finish': 'After implementation and evidence are ready, before readiness checks.',
-    'task.ready': 'Before executing task close.',
-    'task.close': 'After task ready passes and the close plan is reviewed.',
-    'task.audit-close': 'Immediately after close evidence is appended.',
+    'task.lifecycle': 'When the agent needs a compact phase report and next action.',
+    'task.finalize': 'After implementation, evidence, capsule docs, and tracked state docs are ready.',
     'handoff.update': 'Before stopping after meaningful task progress or completion.'
 };
 const DIAGNOSTIC_USE_WHEN = {
@@ -22,7 +20,7 @@ const DIAGNOSTIC_USE_WHEN = {
     'proof.explain': 'Proof status is stale, weak, or confusing.',
     'ci.gate': 'You need an aggregated advisory or strict project/task gate.',
     'protocol.doctor': 'Protocol docs, task board rows, or profile state may be inconsistent.',
-    'harness.validate': 'task ready reports format or done-level blockers.'
+    'harness.validate': 'task finalize or low-level task ready reports format or done-level blockers.'
 };
 const ADVANCED_FAMILY_USE_WHEN = [
     { family: 'release-package', useWhen: 'Release/package capsules only.' },
@@ -35,27 +33,27 @@ const ADVANCED_FAMILY_USE_WHEN = [
 ];
 exports.PORTFOLIO_AUDIT_DECISIONS = [
     {
-        decision: 'Task inspection is separate from readiness.',
-        commands: ['task.status', 'task.ready', 'harness.validate'],
-        rule: '`task status` report generation success is not readiness; readiness lives in readiness/proof fields and `task ready`.',
-        evidence: 'Phase 7.2 non-overlap rules.'
+        decision: 'Task inspection is separate from lifecycle phase and readiness.',
+        commands: ['task.status', 'task.lifecycle', 'task.finalize', 'task.ready', 'harness.validate'],
+        rule: '`task status` report generation success is not readiness; 0.3.3 agents use `task lifecycle` for phase and `task finalize` for guarded close execution, while low-level readiness remains in `task ready`.',
+        evidence: '0.3.3 finalize-first lifecycle default.'
     },
     {
-        decision: 'Completion guidance is read-only, finish is bookkeeping.',
-        commands: ['task.complete', 'task.finish'],
-        rule: '`task complete` is a read-only workflow compressor; `task finish` may update only bounded task status bookkeeping.',
-        evidence: 'Phase 7.2 confusable command audit.'
+        decision: 'Finalize is the default agent close path; finish is low-level bookkeeping.',
+        commands: ['task.finalize', 'task.complete', 'task.finish'],
+        rule: '`task finalize` is the default reviewed close path. `task complete` is a legacy read-only workflow compressor; low-level `task finish` may update only bounded task status bookkeeping.',
+        evidence: '0.3.3 lifecycle convenience contract.'
     },
     {
-        decision: 'Close appends proof, audit verifies proof.',
-        commands: ['task.close', 'task.audit-close'],
-        rule: '`task close --execute` appends close evidence only; `task audit-close` is read-only post-close verification.',
-        evidence: 'Phase 7.2 non-overlap rules.'
+        decision: 'Close appends proof, audit verifies proof, finalize composes both.',
+        commands: ['task.finalize', 'task.close', 'task.audit-close'],
+        rule: '`task finalize --execute --plan-hash <hash>` preserves the underlying boundaries: low-level `task close --execute` appends close evidence only and `task audit-close` is read-only post-close verification.',
+        evidence: '0.3.3 finalize-first lifecycle default.'
     },
     {
         decision: 'Proof and CI gates diagnose, they do not replace close.',
-        commands: ['proof.status', 'proof.explain', 'ci.gate', 'task.close'],
-        rule: 'Proof and CI reports explain readiness; they do not append close proof or substitute for audit.',
+        commands: ['proof.status', 'proof.explain', 'ci.gate', 'task.finalize', 'task.close'],
+        rule: 'Proof and CI reports explain readiness; they do not append close proof or substitute for finalize/audit.',
         evidence: 'Phase 7.2 non-overlap rules.'
     },
     {
@@ -66,7 +64,7 @@ exports.PORTFOLIO_AUDIT_DECISIONS = [
     },
     {
         decision: 'Release and dev validation are not ordinary capsule lifecycle steps.',
-        commands: ['release.gate', 'task.ready', 'dev.docker-check'],
+        commands: ['release.gate', 'task.finalize', 'task.ready', 'dev.docker-check'],
         rule: 'Release/dev commands are operator or HADARA-dev validation surfaces and stay hidden from primary lifecycle help.',
         evidence: 'Phase 7.2 advanced family boundary.'
     }
@@ -169,14 +167,10 @@ function primaryCommandForEntry(entry) {
             return 'hadara task status --task T-XXXX --json';
         case 'evidence.add-command':
             return 'hadara evidence add-command --task T-XXXX --summary "..." --result passed --json';
-        case 'task.finish':
-            return 'hadara task finish --task T-XXXX --json';
-        case 'task.ready':
-            return 'hadara task ready --task T-XXXX --level done --json';
-        case 'task.close':
-            return 'hadara task close --task T-XXXX --json';
-        case 'task.audit-close':
-            return 'hadara task audit-close --task T-XXXX --json';
+        case 'task.lifecycle':
+            return 'hadara task lifecycle --task T-XXXX --json';
+        case 'task.finalize':
+            return 'hadara task finalize --task T-XXXX --json';
         case 'handoff.update':
             return 'hadara handoff update --task T-XXXX --json';
         default: