hadara 0.3.3-rc.0 → 0.3.4-rc.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.2-blue">
-  <img alt="Source version" src="https://img.shields.io/badge/source-0.3.3--rc.0-blue">
+  <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="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,31 +24,38 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 Current stable npm release:
 
 ```text
-hadara@0.3.2
+hadara@0.3.3
 ```
 
-Current release candidate:
+Current source release candidate:
+
+```text
+hadara@0.3.4-rc.0
+```
+
+Previous published release candidate:
 
 ```text
 hadara@0.3.3-rc.0
 ```
 
-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.
+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.
 
-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.
+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.
 
 | Surface | Status |
 |---|---|
-| Current stable | [`hadara@0.3.2`](docs/RELEASE_NOTES.md#032) |
-| 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) |
+| 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) |
+| 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. |
 | Docker image | Deferred. |
 | 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.
+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.
 
 ## Install
 
@@ -57,7 +64,7 @@ Requires Node.js 22.
 Install the stable release:
 
 ```bash
-npm install -g hadara@0.3.2
+npm install -g hadara@0.3.3
 hadara help
 hadara doctor --json
 ```
@@ -65,11 +72,11 @@ hadara doctor --json
 Run without a global install:
 
 ```bash
-npx hadara@0.3.2 help
-npx hadara@0.3.2 doctor --json
+npx hadara@0.3.3 help
+npx hadara@0.3.3 doctor --json
 ```
 
-Evaluate the release candidate explicitly:
+Evaluate the previous release candidate explicitly:
 
 ```bash
 npm install -g hadara@0.3.3-rc.0
@@ -80,11 +87,11 @@ For release or recycle evidence, prefer an isolated prefix install when PATH, gl
 
 ```bash
 tmp="$(mktemp -d)"
-npm --prefix "$tmp" install hadara@0.3.2
+npm --prefix "$tmp" install hadara@0.3.3
 "$tmp/node_modules/.bin/hadara" version --json
 ```
 
-`npx hadara@0.3.2 ...` 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.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.
 
 ## What HADARA Gives You
 
@@ -122,10 +129,11 @@ hadara help command task.close
 
 ## Primary Capsule Lifecycle
 
-The 0.3.3 primary path is intentionally small. Agents should use `task finalize` as the default lifecycle close path:
+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:
 
 ```bash
 hadara task next --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
@@ -260,7 +268,7 @@ Dashboard, TUI, Hermes, MCP, installer, package, release, and run commands stay
 
 ## Safety Boundaries
 
-HADARA 0.3.3-rc.0 is not:
+HADARA 0.3.4-rc.0 is not:
 
 - a full agent runtime;
 - Rack/enterprise behavior;
@@ -300,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.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.
+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.
 
 ## Development / Contributing
 
@@ -313,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.3 finalize-first lifecycle loop plus low-level proof-boundary reference commands.
+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.
 
 | Profile | Use When |
 |---|---|

package/dist/cli/dashboard.js

@@ -20,7 +20,6 @@ const dashboard_heavy_projection_1 = require("../services/dashboard-heavy-projec
 const evidence_lint_1 = require("../services/evidence-lint");
 const evidence_list_1 = require("../services/evidence-list");
 const dashboard_timeline_1 = require("../services/dashboard-timeline");
-const operational_debt_1 = require("../services/operational-debt");
 const operations_status_service_1 = require("../services/operations-status-service");
 const task_read_model_1 = require("../services/task-read-model");
 const task_workbench_1 = require("../services/task-workbench");
@@ -93,8 +92,11 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
     if (!url || !url.pathname.startsWith('/api/'))
         return null;
     const headOnly = normalizedMethod === 'HEAD';
-    if (url.pathname === '/api/status')
-        return jsonResponse((0, operations_status_service_1.createOpsStatusReport)(projectRoot), headOnly);
+    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);
+    }
     if (url.pathname === '/api/dashboard/core') {
         const bypassProjection = url.searchParams.get('cache') === 'bypass';
         const status = bypassProjection ? null : (0, dashboard_refresh_1.createDashboardProjectionStatusReport)(projectRoot);
@@ -116,7 +118,7 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
         return jsonResponse((0, dashboard_heavy_projection_1.createProjectedDashboardDebtReport)(projectRoot), headOnly);
     if (url.pathname === '/api/dashboard/bootstrap') {
         const selectedTaskId = url.searchParams.get('selectedTaskId')?.trim();
-        const tier = url.searchParams.get('tier') === 'core' ? 'core' : 'full';
+        const tier = url.searchParams.get('tier') === 'full' ? 'full' : 'core';
         const keyParts = ['bootstrap'];
         if (tier === 'core')
             keyParts.push('core');
@@ -140,8 +142,13 @@ function createDashboardApiResponse(projectRoot, requestUrl, method) {
         return jsonResponse((0, task_read_model_1.createTaskListReport)(projectRoot), headOnly);
     if (url.pathname === '/api/active-run')
         return jsonResponse((0, active_run_state_1.safeCreateActiveRunProjection)(projectRoot), headOnly);
-    if (url.pathname === '/api/debt')
-        return jsonResponse((0, operational_debt_1.createOperationalDebtReport)(projectRoot), headOnly);
+    if (url.pathname === '/api/debt') {
+        // Keep the legacy dashboard debt route on the same fast aggregate path as
+        // /api/dashboard/debt. The full operational-debt read model remains
+        // available through CLI/MCP surfaces; dashboard request handlers must not
+        // perform broad capsule scans on the hot API path.
+        return jsonResponse((0, dashboard_heavy_projection_1.createProjectedDashboardDebtReport)(projectRoot), headOnly);
+    }
     if (url.pathname === '/api/timeline') {
         const taskId = url.searchParams.get('taskId')?.trim();
         const key = taskId ? (0, dashboard_cache_1.createDashboardCacheKey)(projectRoot, 'timeline', taskId) : (0, dashboard_cache_1.createDashboardCacheKey)(projectRoot, 'timeline');

package/dist/cli/evidence.js

@@ -11,6 +11,7 @@ const evidence_json_1 = require("./evidence-json");
 const evidence_lint_1 = require("../services/evidence-lint");
 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");
 function handleEvidenceCommand(input) {
     const sub = input.args[1];
@@ -52,6 +53,32 @@ function handleEvidenceCommand(input) {
             process.exitCode = 6;
         return true;
     }
+    if (sub === 'summary') {
+        const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
+        const report = (0, evidence_summary_1.createEvidenceSummaryReport)(input.projectRoot, {
+            taskId,
+            limit: (0, args_1.getIntegerOption)(input.args, '--limit', { min: 0, max: 500 }),
+            includePrivate: (0, args_1.getFlag)(input.args, '--include-private')
+        });
+        if (input.jsonOutput) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(`[HADARA] evidence summary ${taskId}: ${report.ok ? 'ok' : 'issues'} | records ${report.summary.count} | durable ${report.summary.durableCount}`);
+            if (report.latest)
+                console.log(`latest: ${evidenceSummaryDisplay(report.latest)}`);
+            if (report.latestCloseEvidence)
+                console.log(`latest-close: ${evidenceSummaryDisplay(report.latestCloseEvidence)}`);
+            for (const record of report.records)
+                console.log(`- ${evidenceSummaryDisplay(record)}`);
+            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') {
         const taskId = (0, args_1.getRequiredStringOption)(input.args, '--task');
         const report = (0, evidence_migration_1.createEvidenceMigrationPreviewReport)({
@@ -175,6 +202,21 @@ function evidenceListCategory(record) {
 function evidenceListOutcome(record) {
     return record.outcome;
 }
+function evidenceSummaryDisplay(record) {
+    const tags = record.tags.length > 0 ? ` | tags:${record.tags.slice(0, 3).map(compactEvidenceTag).join(',')}${record.tags.length > 3 ? ',...' : ''}` : '';
+    return `${record.id} | ${record.time} | ${record.category}/${record.outcome} | ${record.visibility} | ${truncateSummary(record.summary)}${tags}`;
+}
+function truncateSummary(value) {
+    const maxLength = 160;
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength - 3)}...`;
+}
+function compactEvidenceTag(value) {
+    if (value.startsWith('idempotency:'))
+        return 'idempotency:*';
+    return truncateSummary(value);
+}
 function parseEvidenceKind(value) {
     if (['test-log', 'command-log', 'diff-summary', 'screenshot', 'note'].includes(value)) {
         return value;

package/dist/cli/handoff.js

@@ -2,11 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleHandoffCommand = handleHandoffCommand;
 const handoff_1 = require("../handoff/handoff");
+const handoff_stale_problems_1 = require("../handoff/handoff-stale-problems");
 const handoff_suggestion_1 = require("../handoff/handoff-suggestion");
 const actor_1 = require("./actor");
 const args_1 = require("./args");
 function handleHandoffCommand(input) {
     const sub = input.args[1];
+    if (sub === 'stale-problems') {
+        const report = (0, handoff_stale_problems_1.createHandoffStaleProblemsReport)(input.projectRoot);
+        if (input.jsonOutput) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log((0, handoff_stale_problems_1.formatHandoffStaleProblemsReport)(report));
+        }
+        if (!report.ok)
+            process.exitCode = 6;
+        return true;
+    }
     if (sub === 'suggest') {
         const taskId = (0, args_1.getStringOption)(input.args, '--task') ?? input.args[2];
         if (!taskId || taskId.startsWith('--'))

package/dist/cli/init.js

@@ -1104,17 +1104,19 @@ Ownership boundaries follow the lifecycle command model. \`task finalize --execu
 
 ## Standard Task Workflow 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:
+The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. From 0.3.4 onward, agents should start from a compact task/context packet, then use lifecycle/finalize for closure instead of starting with low-level proof-boundary commands:
 
 \`\`\`bash
 hadara task next --json
 
 # If a matching capsule already exists:
 hadara task status --task T-XXXX --json
+hadara session start --task T-XXXX --json
 
 # If no matching capsule exists, create one first:
 hadara task create "task title" --json
 hadara task status --task T-XXXX --json
+hadara session start --task T-XXXX --json
 
 # Do the scoped work.
 
@@ -1315,17 +1317,19 @@ HADARA task workflow commands are split by responsibility. Similar-looking comma
 
 ## Standard Task Loop
 
-From 0.3.3 onward, agents should use the finalize-first loop for ordinary implementation capsules:
+From 0.3.4 onward, agents should use the context-aware finalize-first loop for ordinary implementation capsules:
 
 \`\`\`bash
 hadara task next --json
 
 # If a matching capsule already exists:
 hadara task status --task T-XXXX --json
+hadara session start --task T-XXXX --json
 
 # If no matching capsule exists, create one first:
 hadara task create "task title" --json
 hadara task status --task T-XXXX --json
+hadara session start --task T-XXXX --json
 
 # Do the scoped work.
 
@@ -1534,6 +1538,20 @@ Use semantic tiers to keep session startup compact:
 
 \`.hadara/context/HADARA_CONTEXT.md\` is the current-state entry point. It should route readers to compact state before task-work or conditional-reference docs. Full historical review of \`docs/PROJECT_STATE.md\` is not mandatory every session; use \`docs/AGENT_HANDOFF.md\` and its Historical Index when older history is needed. Historical and superseded docs are never default required reading.
 
+## Default Agent Loop
+
+For ordinary implementation work, use the current context-aware loop:
+
+\`\`\`bash
+hadara task next --json
+hadara session start --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
+\`\`\`
+
+Use low-level \`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` only when debugging, repairing, or implementing those proof-boundary commands.
+
 ## Rules
 
 | Rule | Requirement | Evidence / Update Location |

package/dist/cli/main.js

@@ -222,6 +222,9 @@ async function main(args = process.argv.slice(2)) {
             break;
         }
         case 'release': {
+            const { handleReleaseCloseoutCommand } = await Promise.resolve().then(() => __importStar(require('./release-closeout')));
+            if (handleReleaseCloseoutCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
+                return;
             const { handleReleaseDryRunCommand } = await Promise.resolve().then(() => __importStar(require('./release-dry-run')));
             if (handleReleaseDryRunCommand({ args, projectRoot: paths.projectRoot, jsonOutput }))
                 return;

package/dist/cli/package-smoke.js

@@ -1,10 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handlePackageCommand = handlePackageCommand;
+const package_recycle_1 = require("../services/package-recycle");
 const package_smoke_1 = require("../services/package-smoke");
 const args_1 = require("./args");
 function handlePackageCommand(input) {
-    if (input.args[0] !== 'package' || input.args[1] !== 'smoke')
+    if (input.args[0] !== 'package')
+        return false;
+    if (input.args[1] === 'recycle') {
+        const report = (0, package_recycle_1.createPackageRecycleReport)({
+            paths: input.paths,
+            execute: (0, args_1.getFlag)(input.args, '--execute'),
+            packageSpecifier: (0, args_1.getStringOption)(input.args, '--package'),
+            expectedVersion: (0, args_1.getStringOption)(input.args, '--expected-version'),
+            workspace: (0, args_1.getStringOption)(input.args, '--workspace'),
+            taskId: (0, args_1.getStringOption)(input.args, '--task'),
+            attachEvidence: (0, args_1.getFlag)(input.args, '--attach-evidence'),
+            noEvidence: (0, args_1.getFlag)(input.args, '--no-evidence'),
+            keepTemp: (0, args_1.getFlag)(input.args, '--keep-temp'),
+            timeoutSeconds: (0, args_1.getIntegerOption)(input.args, '--timeout', { min: 1 })
+        });
+        if (input.jsonOutput) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(`${report.ok ? 'passed' : 'failed'} | package recycle | ${report.mode}`);
+            for (const step of report.steps) {
+                console.log(`${step.status} | ${step.label} | ${step.summary}`);
+            }
+            for (const issue of report.issues) {
+                console.log(`${issue.severity} | ${issue.code} | ${issue.message}`);
+            }
+        }
+        if (!report.ok)
+            process.exitCode = 6;
+        return true;
+    }
+    if (input.args[1] !== 'smoke')
         return false;
     const options = {
         paths: input.paths,

package/dist/cli/release-closeout.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleReleaseCloseoutCommand = handleReleaseCloseoutCommand;
+const release_closeout_1 = require("../services/release-closeout");
+const args_1 = require("./args");
+function handleReleaseCloseoutCommand(input) {
+    if (input.args[0] !== 'release' || input.args[1] !== 'closeout')
+        return false;
+    const report = (0, release_closeout_1.createReleaseCloseoutReport)(input.projectRoot, {
+        version: (0, args_1.getStringOption)(input.args, '--version'),
+        taskId: (0, args_1.getStringOption)(input.args, '--task')
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log((0, release_closeout_1.formatReleaseCloseoutReport)(report));
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}

package/dist/context/context-pack.js

@@ -108,6 +108,10 @@ function buildContextPackReport(input) {
         score: 0
     }, false, input.projectRoot))
         .sort(compareItems);
+    const validateWith = validationSuggestionsForTask(taskId, graphReport);
+    const writeBoundaries = writeBoundariesForItems([...readFirst, ...readIfNeeded], graphReport.nodes);
+    const sliceCandidates = sliceCandidatesForItems([...readFirst, ...readIfNeeded], graphReport.nodes);
+    const agentActions = agentActionsForContextPack(readFirst, sliceCandidates, validateWith, taskId);
     const cache = input.cache ?? graphReport.cache ?? { used: false, hit: false };
     return {
         schemaVersion: exports.CONTEXT_PACK_SCHEMA_ID,
@@ -120,9 +124,10 @@ function buildContextPackReport(input) {
         readFirst,
         readIfNeeded,
         doNotReadByDefault,
-        validateWith: validationSuggestionsForTask(taskId, graphReport),
-        writeBoundaries: writeBoundariesForItems([...readFirst, ...readIfNeeded], graphReport.nodes),
-        sliceCandidates: sliceCandidatesForItems([...readFirst, ...readIfNeeded], graphReport.nodes),
+        validateWith,
+        writeBoundaries,
+        sliceCandidates,
+        agentActions,
         knownProblems,
         stateProjection: {
             ...graphReport.stateProjection.summary,
@@ -159,7 +164,7 @@ function rankContextPackNodes(nodes, edges, connectedIds, taskNode) {
     if (taskNode) {
         ranked.set(taskNode.id, {
             node: taskNode,
-            reason: 'Active task capsule is the first read for task-scoped context routing.',
+            reason: 'Read the active task capsule first; it defines scope, acceptance, test expectations, and close handoff for this task.',
             confidence: 'explicit',
             score: 1000
         });
@@ -174,7 +179,7 @@ function rankContextPackNodes(nodes, edges, connectedIds, taskNode) {
                 continue;
             upsertRankedNode(ranked, {
                 node,
-                reason: edge.reason,
+                reason: concreteRankReason(node, edge.reason),
                 confidence: edge.confidence,
                 score: nodeScore(node, edge.confidence, connectedIds.has(node.id))
             });
@@ -186,7 +191,7 @@ function rankContextPackNodes(nodes, edges, connectedIds, taskNode) {
         if (metadataBoolean(node, 'requiredReading')) {
             upsertRankedNode(ranked, {
                 node,
-                reason: 'Document registry marks this document as required reading.',
+                reason: 'Required current-state document from the docs registry; read after task-local context if the task needs this surface.',
                 confidence: 'explicit',
                 score: nodeScore(node, 'explicit', false) - 25
             });
@@ -203,6 +208,8 @@ function upsertRankedNode(ranked, candidate) {
 function nodeScore(node, confidence, connected) {
     const confidenceScore = confidence === 'explicit' ? 80 : confidence === 'derived' ? 50 : 20;
     const connectedScore = connected ? 25 : 0;
+    const taskLocalScore = node.path?.startsWith('tasks/') ? 140 : 0;
+    const sourceScore = ['SourceFile', 'TestFile', 'Symbol'].includes(node.type) ? 40 : 0;
     const typeScore = {
         Task: 1000,
         Document: 700,
@@ -218,7 +225,28 @@ function nodeScore(node, confidence, connected) {
         FixtureFile: 380,
         ConfigFile: 360
     };
-    return typeScore[node.type] + confidenceScore + connectedScore;
+    return typeScore[node.type] + confidenceScore + connectedScore + taskLocalScore + sourceScore;
+}
+function concreteRankReason(node, sourceReason) {
+    if (node.path?.startsWith('tasks/')) {
+        return `Task-local file connected to the active task; read it before broad project history. ${sourceReason}`;
+    }
+    if (node.type === 'SourceFile') {
+        return `Implementation file connected to the active task; inspect it when changing code. ${sourceReason}`;
+    }
+    if (node.type === 'TestFile') {
+        return `Test file connected to the active task; inspect it when planning or verifying changes. ${sourceReason}`;
+    }
+    if (node.type === 'Symbol') {
+        return `Specific symbol connected to the active task; prefer this bounded location over opening the full file. ${sourceReason}`;
+    }
+    if (node.type === 'KnownProblem') {
+        return `Current handoff problem relevant to this task; check whether it changes implementation or validation. ${sourceReason}`;
+    }
+    if (node.type === 'Command') {
+        return `Command surface connected to this task; use it to choose dry-run/read-only validation before mutation. ${sourceReason}`;
+    }
+    return sourceReason;
 }
 function isReadFirstAllowed(node) {
     if (isDoNotReadByDefault(node))
@@ -388,6 +416,62 @@ function sliceCandidatesForItems(items, nodes) {
         };
     });
 }
+function agentActionsForContextPack(readFirst, sliceCandidates, validateWith, taskId) {
+    const actions = [];
+    const seenCommands = new Set();
+    const firstSliceableItem = readFirst.find((item) => item.path && item.sourceAccess?.rawSlice === 'sliceable');
+    if (firstSliceableItem?.path) {
+        const args = suggestedSliceCommandArgs(firstSliceableItem.path, 'explicit-range', undefined, {
+            lineStart: firstSliceableItem.lineStart ?? 1,
+            lineEnd: firstSliceableItem.lineEnd ?? Math.max(firstSliceableItem.lineStart ?? 1, (firstSliceableItem.lineStart ?? 1) + 80)
+        });
+        pushAgentAction(actions, seenCommands, {
+            id: 'agent-action:read-first:1',
+            kind: 'read-first',
+            priority: 100,
+            sourceItemId: firstSliceableItem.id,
+            path: firstSliceableItem.path,
+            reason: `Read the top context item ${firstSliceableItem.id} as a bounded raw slice before opening broader files.`,
+            command: suggestedSliceCommand(args),
+            commandArgs: args,
+            writeBoundary: 'read-only'
+        });
+    }
+    for (const [index, candidate] of sliceCandidates.slice(0, 3).entries()) {
+        pushAgentAction(actions, seenCommands, {
+            id: `agent-action:slice:${index + 1}`,
+            kind: 'slice',
+            priority: 90 - index,
+            sliceCandidateId: candidate.id,
+            path: candidate.path,
+            reason: `Use this bounded slice candidate before reading the full file: ${candidate.reason}`,
+            command: candidate.suggestedCommand,
+            commandArgs: candidate.suggestedCommandArgs,
+            writeBoundary: 'read-only'
+        });
+    }
+    const requiredValidation = validateWith.find((suggestion) => suggestion.requiredForClose);
+    if (requiredValidation) {
+        pushAgentAction(actions, seenCommands, {
+            id: 'agent-action:validate:required-close',
+            kind: 'validate',
+            priority: 50,
+            reason: taskId
+                ? `Run this read-only readiness check before planning close for ${taskId}.`
+                : 'Run this read-only readiness check before planning close.',
+            command: requiredValidation.command,
+            writeBoundary: 'read-only'
+        });
+    }
+    return actions.sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));
+}
+function pushAgentAction(actions, seenCommands, action) {
+    const key = action.commandArgs ? action.commandArgs.join('\0') : action.command;
+    if (seenCommands.has(key))
+        return;
+    seenCommands.add(key);
+    actions.push(action);
+}
 function explicitRangeForCandidate(item, node) {
     const lineStart = item.lineStart ?? numberMetadata(node, 'startLine') ?? node?.source.line ?? 1;
     const metadataEnd = numberMetadata(node, 'endLine');

package/dist/context/session-start.js

@@ -134,6 +134,7 @@ function buildWarmCachedContextPackReport(input) {
 function lifecycleForSessionStart(taskId, contextPack) {
     const primaryNextCommands = taskId
         ? [
+            `node dist/cli/main.js task lifecycle --task ${taskId} --json`,
             `node dist/cli/main.js task status --task ${taskId} --json`,
             `node dist/cli/main.js context pack --task ${taskId} --json`
         ]
@@ -175,7 +176,17 @@ function guidanceForSessionStart(input) {
                 ? 'Session Start used explicit live context-pack discovery because --live was supplied.'
                 : 'Session Start used the bounded no-live packet and avoided broad live graph discovery.';
     const commands = [];
+    let primaryAction;
     if (!taskId) {
+        primaryAction = {
+            id: 'task-next',
+            label: 'Select the next task',
+            command: 'node dist/cli/main.js task next --json',
+            args: ['task', 'next', '--json'],
+            reason: 'No task id is available, so the next useful step is to select a concrete task before reading task-scoped context.',
+            writeBoundary: 'read-only',
+            recommendedActorRole: 'agent-worker'
+        };
         commands.push({
             id: 'task-next',
             command: 'node dist/cli/main.js task next --json',
@@ -184,6 +195,21 @@ function guidanceForSessionStart(input) {
         });
     }
     else {
+        primaryAction = {
+            id: 'task-lifecycle',
+            label: 'Inspect task lifecycle phase',
+            command: `node dist/cli/main.js task lifecycle --task ${taskId} --json`,
+            args: ['task', 'lifecycle', '--task', taskId, '--json'],
+            reason: 'A task id is available, so the fastest safe first step is to inspect lifecycle phase and blockers before editing files.',
+            writeBoundary: 'read-only',
+            recommendedActorRole: 'agent-worker'
+        };
+        commands.push({
+            id: 'task-lifecycle',
+            command: `node dist/cli/main.js task lifecycle --task ${taskId} --json`,
+            args: ['task', 'lifecycle', '--task', taskId, '--json'],
+            reason: 'Inspect the task phase and the one primary lifecycle next action before editing.'
+        });
         commands.push({
             id: 'task-status',
             command: `node dist/cli/main.js task status --task ${taskId} --json`,
@@ -216,6 +242,18 @@ function guidanceForSessionStart(input) {
     return {
         mode,
         primaryNextAction,
+        primaryAction,
+        whyThisNow: primaryAction.reason,
+        avoidForNow: taskId
+            ? [
+                'Do not run task finalize before reviewing lifecycle blockers and required reads.',
+                'Do not opt into --live context reads unless the bounded or warm packet is insufficient.'
+            ]
+            : [
+                'Do not infer a task id from broad project files.',
+                'Do not run live context discovery before selecting a task.'
+            ],
+        nextCommandArgs: primaryAction.args,
         reason,
         taskRequired,
         liveContextPackAvailable: true,
@@ -273,6 +311,7 @@ function buildBoundedContextPackReport(input) {
             : [],
         writeBoundaries: [],
         sliceCandidates: [],
+        agentActions: [],
         knownProblems: [],
         stateProjection: {
             ...(input.taskId ? { activeTask: input.taskId } : {}),