hadara 0.3.3 → 0.4.0-rc.0

package/dist/context/context-pack.js

@@ -10,6 +10,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const context_graph_builder_1 = require("./context-graph-builder");
 const context_slice_boundary_1 = require("./context-slice-boundary");
 const extractor_contract_1 = require("./extractor-contract");
+const docs_registry_1 = require("../services/docs-registry");
 exports.CONTEXT_PACK_SCHEMA_ID = 'hadara.contextPack.v1';
 exports.CONTEXT_PACK_COMMAND = 'context.pack';
 exports.CONTEXT_PACK_DEFAULT_BUDGET = {
@@ -62,31 +63,43 @@ function buildContextPackReport(input) {
         });
     }
     const connectedIds = taskId ? connectedNodeIds(graphReport.edges, (0, extractor_contract_1.createTaskNodeId)(taskId)) : new Set();
+    const docsReadMap = resolveDocsReadMap(input, taskId);
+    const readMapExcludedPaths = new Set((docsReadMap?.doNotReadByDefault ?? []).map((entry) => entry.path));
     const rankedNodes = rankContextPackNodes(graphReport.nodes, graphReport.edges, connectedIds, taskNode);
-    const readFirstRanked = rankedNodes.filter((ranked) => isReadFirstAllowed(ranked.node));
-    const readFirst = readFirstRanked
-        .slice(0, budget.maxReadFirstItems)
-        .map((ranked) => itemFromRankedNode(ranked, true, input.projectRoot));
-    if (readFirstRanked.length > readFirst.length) {
+    const readFirstRanked = rankedNodes
+        .filter((ranked) => isReadFirstAllowed(ranked.node))
+        .filter((ranked) => !isExcludedByReadMap(ranked.node, readMapExcludedPaths));
+    const graphReadFirst = readFirstRanked.map((ranked) => itemFromRankedNode(ranked, true, input.projectRoot));
+    const readFirstCandidates = mergeContextPackItems([
+        ...graphReadFirst.filter((item) => item.id === `task:${taskId}`),
+        ...readMapItems(docsReadMap?.readFirst ?? [], input.projectRoot, true),
+        ...graphReadFirst.filter((item) => item.id !== `task:${taskId}`)
+    ]);
+    const readFirst = readFirstCandidates.slice(0, budget.maxReadFirstItems);
+    if (readFirstCandidates.length > readFirst.length) {
         issues.push({
             severity: 'warning',
             code: 'CONTEXT_PACK_BUDGET_TRUNCATED',
-            message: `Context pack readFirst items were truncated from ${readFirstRanked.length} to ${readFirst.length}.`
+            message: `Context pack readFirst items were truncated from ${readFirstCandidates.length} to ${readFirst.length}.`
         });
     }
     const selectedIds = new Set(readFirst.map((item) => item.id));
+    const selectedPaths = new Set(readFirst.map((item) => item.path).filter((value) => Boolean(value)));
     const maxReadIfNeeded = Math.max(0, (budget.maxItems ?? 30) - readFirst.length);
     const readIfNeededRanked = rankedNodes
-        .filter((ranked) => !selectedIds.has(ranked.node.id))
+        .filter((ranked) => !selectedIds.has(ranked.node.id) && (!ranked.node.path || !selectedPaths.has(ranked.node.path)))
+        .filter((ranked) => !isExcludedByReadMap(ranked.node, readMapExcludedPaths))
         .filter((ranked) => !isDoNotReadByDefault(ranked.node));
-    const readIfNeeded = readIfNeededRanked
-        .slice(0, maxReadIfNeeded)
-        .map((ranked) => itemFromRankedNode(ranked, false, input.projectRoot));
-    if (readIfNeededRanked.length > readIfNeeded.length) {
+    const readIfNeededCandidates = mergeContextPackItems([
+        ...readMapItems(docsReadMap?.readIfNeeded ?? [], input.projectRoot, false),
+        ...readIfNeededRanked.map((ranked) => itemFromRankedNode(ranked, false, input.projectRoot))
+    ]).filter((item) => !selectedIds.has(item.id) && (!item.path || !selectedPaths.has(item.path)));
+    const readIfNeeded = readIfNeededCandidates.slice(0, maxReadIfNeeded);
+    if (readIfNeededCandidates.length > readIfNeeded.length) {
         issues.push({
             severity: 'warning',
             code: 'CONTEXT_PACK_BUDGET_TRUNCATED',
-            message: `Context pack readIfNeeded items were truncated from ${readIfNeededRanked.length} to ${readIfNeeded.length}.`
+            message: `Context pack readIfNeeded items were truncated from ${readIfNeededCandidates.length} to ${readIfNeeded.length}.`
         });
     }
     const doNotReadByDefault = graphReport.nodes
@@ -108,6 +121,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 +137,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,
@@ -132,16 +150,86 @@ function buildContextPackReport(input) {
             graphAvailable: true,
             codeIndexAvailable: codeIndexAvailable(graphReport),
             stateProjectionAvailable: true,
-            docsRegistryAvailable: graphReport.stateProjection.sources.some((source) => source.kind === 'docs-registry'),
+            docsRegistryAvailable: Boolean(docsReadMap?.source.registryPresent) || graphReport.stateProjection.sources.some((source) => source.kind === 'docs-registry'),
             commandRegistryAvailable: graphReport.nodes.some((node) => node.type === 'Command'),
             degraded: graphReport.summary.degraded || issues.some((issue) => issue.severity !== 'info'),
             graphSourceHash: graphReport.sourceHash,
-            sourcesRead: graphReport.summary.sourcesRead
+            sourcesRead: graphReport.summary.sourcesRead,
+            docsReadMapAvailable: Boolean(docsReadMap),
+            docsReadMapReadFirstCount: docsReadMap?.readFirst.length ?? 0,
+            docsReadMapDoNotReadByDefaultCount: docsReadMap?.doNotReadByDefault.length ?? 0
         },
         cache,
         issues
     };
 }
+function resolveDocsReadMap(input, taskId) {
+    if (input.docsReadMap)
+        return input.docsReadMap;
+    if (input.graphReport || !taskId)
+        return undefined;
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(input.projectRoot, '.hadara', 'docs-registry.json')))
+        return undefined;
+    return (0, docs_registry_1.createDocsReadMapReport)(input.projectRoot, taskId);
+}
+function readMapItems(entries, projectRoot, required) {
+    return [...entries].sort(compareReadMapEntriesForContextPack).map((entry) => {
+        const sourceHash = sourceHashForPath(projectRoot, entry.path);
+        return {
+            id: `doc:${entry.path}`,
+            type: 'Document',
+            path: entry.path,
+            title: entry.title,
+            reason: `Docs read-map ${entry.readTier}: ${entry.reason}`,
+            confidence: entry.readTier === 'active-task' || entry.readTier === 'active-spec' ? 'explicit' : 'derived',
+            ...(sourceHash ? { sourceHash } : {}),
+            estimatedTokens: estimateTokensForPath(entry.path, entry.title),
+            required,
+            sourceAccess: sourceAccessForPath(entry.path)
+        };
+    });
+}
+function compareReadMapEntriesForContextPack(a, b) {
+    return readMapTierPriority(a.readTier) - readMapTierPriority(b.readTier) || a.path.localeCompare(b.path);
+}
+function readMapTierPriority(tier) {
+    if (tier === 'active-task')
+        return 0;
+    if (tier === 'active-spec')
+        return 1;
+    if (tier === 'current-state')
+        return 2;
+    if (tier === 'workflow-reference')
+        return 3;
+    if (tier === 'conditional-reference')
+        return 4;
+    if (tier === 'implemented-reference')
+        return 5;
+    if (tier === 'drift-review')
+        return 6;
+    if (tier === 'historical')
+        return 7;
+    return 8;
+}
+function mergeContextPackItems(items) {
+    const seenIds = new Set();
+    const seenPaths = new Set();
+    const merged = [];
+    for (const item of items) {
+        if (seenIds.has(item.id))
+            continue;
+        if (item.path && seenPaths.has(item.path))
+            continue;
+        seenIds.add(item.id);
+        if (item.path)
+            seenPaths.add(item.path);
+        merged.push(item);
+    }
+    return merged;
+}
+function isExcludedByReadMap(node, excludedPaths) {
+    return Boolean(node.path && excludedPaths.has(node.path));
+}
 function normalizeContextBudget(input = {}) {
     const maxReadFirstItems = positiveInteger(input.maxReadFirstItems) ?? exports.CONTEXT_PACK_DEFAULT_BUDGET.maxReadFirstItems;
     return {
@@ -159,7 +247,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 +262,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 +274,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 +291,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 +308,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))
@@ -256,19 +367,24 @@ function itemFromRankedNode(ranked, required, projectRoot) {
 function sourceHashForItem(projectRoot, node) {
     if (!node.path || !(0, context_slice_boundary_1.isContextSliceProjectRelativePath)(node.path))
         return node.source.hash;
-    const normalized = (0, context_slice_boundary_1.normalizeContextSliceInputPath)(node.path);
+    return sourceHashForPath(projectRoot, node.path) ?? node.source.hash;
+}
+function sourceHashForPath(projectRoot, relativePath) {
+    if (!(0, context_slice_boundary_1.isContextSliceProjectRelativePath)(relativePath))
+        return undefined;
+    const normalized = (0, context_slice_boundary_1.normalizeContextSliceInputPath)(relativePath);
     const root = node_path_1.default.resolve(projectRoot);
     const absolutePath = node_path_1.default.resolve(root, normalized);
     if (absolutePath !== root && !absolutePath.startsWith(`${root}${node_path_1.default.sep}`))
-        return node.source.hash;
+        return undefined;
     try {
         const stat = node_fs_1.default.statSync(absolutePath);
         if (!stat.isFile())
-            return node.source.hash;
+            return undefined;
         return (0, extractor_contract_1.hashContextGraphText)(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
     }
     catch {
-        return node.source.hash;
+        return undefined;
     }
 }
 function sourceAccessForNode(node) {
@@ -278,7 +394,10 @@ function sourceAccessForNode(node) {
             reason: 'This context item has no project file path for raw context slicing.'
         };
     }
-    if ((0, context_slice_boundary_1.isContextSliceProjectRelativePath)(node.path)) {
+    return sourceAccessForPath(node.path);
+}
+function sourceAccessForPath(relativePath) {
+    if ((0, context_slice_boundary_1.isContextSliceProjectRelativePath)(relativePath)) {
         return {
             rawSlice: 'sliceable',
             reason: 'This item path is inside the raw context-slice read boundary.'
@@ -294,6 +413,9 @@ function estimateTokens(node) {
     const pathCost = node.path ? Math.ceil(node.path.length / 4) : 0;
     return Math.max(24, labelCost + pathCost + 16);
 }
+function estimateTokensForPath(relativePath, title) {
+    return Math.max(24, Math.ceil(title.length / 4) + Math.ceil(relativePath.length / 4) + 16);
+}
 function validationSuggestionsForTask(taskId, graphReport) {
     const suggestions = new Map();
     if (taskId) {
@@ -388,6 +510,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

@@ -7,6 +7,8 @@ const context_graph_builder_1 = require("./context-graph-builder");
 const context_cache_store_1 = require("./context-cache-store");
 const source_manifest_1 = require("./source-manifest");
 const code_graph_extractor_1 = require("./code-graph-extractor");
+const validate_1 = require("../harness/validate");
+const docs_registry_1 = require("../services/docs-registry");
 exports.SESSION_START_SCHEMA_ID = 'hadara.sessionStart.v1';
 exports.SESSION_START_COMMAND = 'session.start';
 function buildSessionStartReport(input) {
@@ -41,6 +43,7 @@ function buildSessionStartReport(input) {
         lifecycle,
         allowLiveContextPack: Boolean(input.allowLiveContextPack)
     });
+    const docsReadMap = taskId ? createSessionStartDocsReadMap(input.projectRoot, taskId, input.budget?.maxReadFirstItems ?? 7) : undefined;
     return {
         schemaVersion: exports.SESSION_START_SCHEMA_ID,
         command: exports.SESSION_START_COMMAND,
@@ -56,6 +59,7 @@ function buildSessionStartReport(input) {
         contextPack,
         lifecycle,
         guidance,
+        ...(docsReadMap ? { docsReadMap } : {}),
         knownProblems: contextPack.knownProblems,
         sourceSummary: contextPack.sourceSummary,
         cache: contextPack.cache,
@@ -70,6 +74,43 @@ function buildSessionStartReport(input) {
         issues
     };
 }
+function createSessionStartDocsReadMap(projectRoot, taskId, maxReadFirst) {
+    const readMap = (0, docs_registry_1.createDocsReadMapReport)(projectRoot, taskId);
+    const sourceValidation = (0, validate_1.validateTaskCapsule)(projectRoot, taskId, { level: 'done' });
+    const sourceDocumentDrift = sourceValidation.issues
+        .filter((issue) => issue.code === 'TASK_SOURCE_DOCUMENT_CHANGED' || issue.code === 'TASK_SOURCE_DOCUMENT_MISSING_HASH')
+        .map((issue) => ({
+        code: issue.code,
+        message: issue.message,
+        ...(issue.path ? { path: issue.path } : {}),
+        ...(issue.heading ? { heading: issue.heading } : {})
+    }));
+    return {
+        taskId: readMap.taskId,
+        command: `node dist/cli/main.js docs read-map --task ${taskId} --json`,
+        source: readMap.source,
+        task: readMap.task,
+        readFirstCount: readMap.readFirst.length,
+        readIfNeededCount: readMap.readIfNeeded.length,
+        doNotReadByDefaultCount: readMap.doNotReadByDefault.length,
+        driftWarningCount: readMap.driftWarnings.length,
+        sourceDocumentDriftCount: sourceDocumentDrift.length,
+        readFirst: readMap.readFirst.slice(0, maxReadFirst).map((entry) => ({
+            path: entry.path,
+            readTier: entry.readTier,
+            authority: entry.authority,
+            reason: entry.reason
+        })),
+        driftWarnings: readMap.driftWarnings.slice(0, 10),
+        sourceDocumentDrift,
+        issues: readMap.issues.map((issue) => ({
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            ...(issue.path ? { path: issue.path } : {})
+        }))
+    };
+}
 function buildWarmCachedContextPackReport(input) {
     const cachedManifest = (0, context_cache_store_1.readContextSourceManifestCache)(input.projectRoot);
     if (cachedManifest.status !== 'valid' || !cachedManifest.manifest)
@@ -137,7 +178,7 @@ function lifecycleForSessionStart(taskId, contextPack) {
             `node dist/cli/main.js task status --task ${taskId} --json`,
             `node dist/cli/main.js context pack --task ${taskId} --json`
         ]
-        : ['node dist/cli/main.js task next --json'];
+        : ['node dist/cli/main.js task status --json'];
     for (const suggestion of contextPack.validateWith) {
         if (suggestion.requiredForClose && !primaryNextCommands.includes(suggestion.command)) {
             primaryNextCommands.push(suggestion.command);
@@ -175,20 +216,39 @@ 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-status',
+            label: 'Select the next task',
+            command: 'node dist/cli/main.js task status --json',
+            args: ['task', 'status', '--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',
-            args: ['task', 'next', '--json'],
+            id: 'task-status',
+            command: 'node dist/cli/main.js task status --json',
+            args: ['task', 'status', '--json'],
             reason: 'Choose the next task before requesting task-scoped context.'
         });
     }
     else {
+        primaryAction = {
+            id: 'task-status',
+            label: 'Inspect task loop phase',
+            command: `node dist/cli/main.js task status --task ${taskId} --json`,
+            args: ['task', 'status', '--task', taskId, '--json'],
+            reason: 'A task id is available, so the fastest safe first step is to inspect loop phase, blockers, and the primary next action before editing files.',
+            writeBoundary: 'read-only',
+            recommendedActorRole: 'agent-worker'
+        };
         commands.push({
             id: 'task-status',
             command: `node dist/cli/main.js task status --task ${taskId} --json`,
             args: ['task', 'status', '--task', taskId, '--json'],
-            reason: 'Inspect task readiness, evidence, and lifecycle state.'
+            reason: 'Inspect task readiness, evidence, loop phase, and the primary next action.'
         });
         commands.push({
             id: 'context-pack',
@@ -196,6 +256,12 @@ function guidanceForSessionStart(input) {
             args: ['context', 'pack', '--task', taskId, '--json'],
             reason: 'Inspect the bounded task read plan without slicing raw source text.'
         });
+        commands.push({
+            id: 'docs-read-map',
+            command: `node dist/cli/main.js docs read-map --task ${taskId} --json`,
+            args: ['docs', 'read-map', '--task', taskId, '--json'],
+            reason: 'Inspect registry-backed task reading guidance and drift warnings before broad manual reads.'
+        });
     }
     commands.push({
         id: 'cache-warm',
@@ -216,6 +282,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,
@@ -240,7 +318,7 @@ function buildBoundedContextPackReport(input) {
                 severity: 'warning',
                 code: 'CONTEXT_PACK_TASK_NOT_FOUND',
                 message: 'No task id was supplied. Bounded session start returned task-selection guidance without running live project discovery.',
-                fixHint: 'Run hadara task next --json, then rerun hadara session start --task <task-id> --json.'
+                fixHint: 'Run hadara task status --json, then rerun hadara session start --task <task-id> --json.'
             }];
     const readFirst = input.taskId
         ? [{
@@ -273,6 +351,7 @@ function buildBoundedContextPackReport(input) {
             : [],
         writeBoundaries: [],
         sliceCandidates: [],
+        agentActions: [],
         knownProblems: [],
         stateProjection: {
             ...(input.taskId ? { activeTask: input.taskId } : {}),

package/dist/context/task-extractors.js

@@ -138,8 +138,9 @@ function readTaskStatus(content) {
     const sectionStatus = (0, markdown_table_1.readMarkdownSection)(content, '## Status').trim().split(/\r?\n/)[0]?.trim();
     if (sectionStatus)
         return sectionStatus;
-    const rows = (0, markdown_table_1.parseMarkdownRowsUnderHeading)(content, '## Metadata');
-    return (0, markdown_table_1.findMarkdownRowByCell)(rows, 0, 'Status')?.[1] ?? null;
+    const identityRows = (0, markdown_table_1.parseMarkdownRowsUnderHeading)(content, '## Identity');
+    const metadataRows = (0, markdown_table_1.parseMarkdownRowsUnderHeading)(content, '## Metadata');
+    return (0, markdown_table_1.findMarkdownRowByCell)(identityRows, 0, 'Status')?.[1] ?? (0, markdown_table_1.findMarkdownRowByCell)(metadataRows, 0, 'Status')?.[1] ?? null;
 }
 function readTaskHandoffStatus(content) {
     const rows = (0, markdown_table_1.parseMarkdownRowsUnderHeading)(content, '## Current State');

package/dist/core/schema.js

@@ -12,6 +12,7 @@ const actor_context_schema_json_1 = __importDefault(require("../schemas/actor-co
 const active_run_projection_schema_json_1 = __importDefault(require("../schemas/active-run-projection.schema.json"));
 const active_run_resume_schema_json_1 = __importDefault(require("../schemas/active-run-resume.schema.json"));
 const clean_checkout_smoke_schema_json_1 = __importDefault(require("../schemas/clean-checkout-smoke.schema.json"));
+const close_source_schema_json_1 = __importDefault(require("../schemas/close-source.schema.json"));
 const code_index_schema_json_1 = __importDefault(require("../schemas/code-index.schema.json"));
 const context_cache_record_schema_json_1 = __importDefault(require("../schemas/context-cache-record.schema.json"));
 const context_cache_status_schema_json_1 = __importDefault(require("../schemas/context-cache-status.schema.json"));
@@ -29,19 +30,26 @@ const dev_docker_check_schema_json_1 = __importDefault(require("../schemas/dev-d
 const docs_archive_plan_schema_json_1 = __importDefault(require("../schemas/docs-archive-plan.schema.json"));
 const docs_doctor_schema_json_1 = __importDefault(require("../schemas/docs-doctor.schema.json"));
 const docs_explain_schema_json_1 = __importDefault(require("../schemas/docs-explain.schema.json"));
+const docs_inbox_schema_json_1 = __importDefault(require("../schemas/docs-inbox.schema.json"));
 const docs_list_schema_json_1 = __importDefault(require("../schemas/docs-list.schema.json"));
 const docs_mark_schema_json_1 = __importDefault(require("../schemas/docs-mark.schema.json"));
 const docs_patch_plan_schema_json_1 = __importDefault(require("../schemas/docs-patch-plan.schema.json"));
+const docs_read_map_schema_json_1 = __importDefault(require("../schemas/docs-read-map.schema.json"));
+const docs_register_schema_json_1 = __importDefault(require("../schemas/docs-register.schema.json"));
 const docs_required_reading_schema_json_1 = __importDefault(require("../schemas/docs-required-reading.schema.json"));
 const evidence_lint_schema_json_1 = __importDefault(require("../schemas/evidence-lint.schema.json"));
 const evidence_list_schema_json_1 = __importDefault(require("../schemas/evidence-list.schema.json"));
 const evidence_migration_preview_schema_json_1 = __importDefault(require("../schemas/evidence-migration-preview.schema.json"));
+const evidence_projection_schema_json_1 = __importDefault(require("../schemas/evidence-projection.schema.json"));
+const evidence_summary_schema_json_1 = __importDefault(require("../schemas/evidence-summary.schema.json"));
 const event_schema_json_1 = __importDefault(require("../schemas/event.schema.json"));
 const feature_smoke_schema_json_1 = __importDefault(require("../schemas/feature-smoke.schema.json"));
 const harness_validate_schema_json_1 = __importDefault(require("../schemas/harness-validate.schema.json"));
+const handoff_stale_problems_schema_json_1 = __importDefault(require("../schemas/handoff-stale-problems.schema.json"));
 const handoff_suggestion_schema_json_1 = __importDefault(require("../schemas/handoff-suggestion.schema.json"));
 const install_plan_schema_json_1 = __importDefault(require("../schemas/install-plan.schema.json"));
 const next_action_schema_json_1 = __importDefault(require("../schemas/next-action.schema.json"));
+const package_recycle_schema_json_1 = __importDefault(require("../schemas/package-recycle.schema.json"));
 const package_smoke_schema_json_1 = __importDefault(require("../schemas/package-smoke.schema.json"));
 const plan_context_schema_json_1 = __importDefault(require("../schemas/plan-context.schema.json"));
 const private_evidence_schema_json_1 = __importDefault(require("../schemas/private-evidence.schema.json"));
@@ -52,6 +60,7 @@ const provider_call_schema_json_1 = __importDefault(require("../schemas/provider
 const provider_config_schema_json_1 = __importDefault(require("../schemas/provider-config.schema.json"));
 const release_artifact_manifest_schema_json_1 = __importDefault(require("../schemas/release-artifact-manifest.schema.json"));
 const release_artifact_schema_json_1 = __importDefault(require("../schemas/release-artifact.schema.json"));
+const release_closeout_schema_json_1 = __importDefault(require("../schemas/release-closeout.schema.json"));
 const release_dry_run_schema_json_1 = __importDefault(require("../schemas/release-dry-run.schema.json"));
 const release_gate_schema_json_1 = __importDefault(require("../schemas/release-gate.schema.json"));
 const release_publish_schema_json_1 = __importDefault(require("../schemas/release-publish.schema.json"));
@@ -70,9 +79,11 @@ const task_finish_schema_json_1 = __importDefault(require("../schemas/task-finis
 const task_lifecycle_schema_json_1 = __importDefault(require("../schemas/task-lifecycle.schema.json"));
 const task_next_schema_json_1 = __importDefault(require("../schemas/task-next.schema.json"));
 const task_ready_schema_json_1 = __importDefault(require("../schemas/task-ready.schema.json"));
+const task_status_schema_json_1 = __importDefault(require("../schemas/task-status.schema.json"));
 const task_upgrade_scaffold_schema_json_1 = __importDefault(require("../schemas/task-upgrade-scaffold.schema.json"));
 const task_workbench_schema_json_1 = __importDefault(require("../schemas/task-workbench.schema.json"));
 const tools_list_schema_json_1 = __importDefault(require("../schemas/tools-list.schema.json"));
+const validation_run_schema_json_1 = __importDefault(require("../schemas/validation-run.schema.json"));
 const write_preflight_schema_json_1 = __importDefault(require("../schemas/write-preflight.schema.json"));
 class SchemaValidationError extends Error {
     schemaId;
@@ -92,6 +103,7 @@ const registeredSchemas = {
     'hadara.active_run.projection.v1': active_run_projection_schema_json_1.default,
     'hadara.active_run.resume.v1': active_run_resume_schema_json_1.default,
     'hadara.cleanCheckoutSmoke.v1': clean_checkout_smoke_schema_json_1.default,
+    'hadara.closeSource.v1': close_source_schema_json_1.default,
     'hadara.codeIndex.v1': code_index_schema_json_1.default,
     'hadara.context.cacheRecord.v1': context_cache_record_schema_json_1.default,
     'hadara.context.cacheStatus.v1': context_cache_status_schema_json_1.default,
@@ -109,19 +121,26 @@ const registeredSchemas = {
     'hadara.docs.archivePlan.v1': docs_archive_plan_schema_json_1.default,
     'hadara.docs.doctor.v1': docs_doctor_schema_json_1.default,
     'hadara.docs.explain.v1': docs_explain_schema_json_1.default,
+    'hadara.docs.inbox.v1': docs_inbox_schema_json_1.default,
     'hadara.docs.list.v1': docs_list_schema_json_1.default,
     'hadara.docs.mark.v1': docs_mark_schema_json_1.default,
     'hadara.docs.patchPlan.v1': docs_patch_plan_schema_json_1.default,
+    'hadara.docs.readMap.v1': docs_read_map_schema_json_1.default,
+    'hadara.docs.register.v1': docs_register_schema_json_1.default,
     'hadara.docs.requiredReading.v1': docs_required_reading_schema_json_1.default,
     'hadara.evidence.lint.v1': evidence_lint_schema_json_1.default,
     'hadara.evidence.list.v1': evidence_list_schema_json_1.default,
     'hadara.evidence.migration_preview.v1': evidence_migration_preview_schema_json_1.default,
+    'hadara.evidence.projection.v1': evidence_projection_schema_json_1.default,
+    'hadara.evidence.summary.v1': evidence_summary_schema_json_1.default,
     'hadara.event.v1': event_schema_json_1.default,
     'hadara.featureSmoke.v1': feature_smoke_schema_json_1.default,
     'hadara.harness.validate.v1': harness_validate_schema_json_1.default,
+    'hadara.handoff.staleProblems.v1': handoff_stale_problems_schema_json_1.default,
     'hadara.handoff.suggestion.v1': handoff_suggestion_schema_json_1.default,
     'hadara.install.plan.v1': install_plan_schema_json_1.default,
     'hadara.next_action.v1': next_action_schema_json_1.default,
+    'hadara.packageRecycle.v1': package_recycle_schema_json_1.default,
     'hadara.packageSmoke.v1': package_smoke_schema_json_1.default,
     'hadara.plan_context.v1': plan_context_schema_json_1.default,
     'hadara.privateEvidence.v1': private_evidence_schema_json_1.default,
@@ -132,6 +151,7 @@ const registeredSchemas = {
     'hadara.provider.config.v1': provider_config_schema_json_1.default,
     'hadara.releaseArtifact.manifest.v1': release_artifact_manifest_schema_json_1.default,
     'hadara.releaseArtifact.v1': release_artifact_schema_json_1.default,
+    'hadara.releaseCloseout.v1': release_closeout_schema_json_1.default,
     'hadara.releaseDryRun.v1': release_dry_run_schema_json_1.default,
     'hadara.releaseGate.v1': release_gate_schema_json_1.default,
     'hadara.releasePublish.v1': release_publish_schema_json_1.default,
@@ -150,9 +170,11 @@ const registeredSchemas = {
     'hadara.task.lifecycle.v1': task_lifecycle_schema_json_1.default,
     'hadara.task.next.v1': task_next_schema_json_1.default,
     'hadara.task.ready.v1': task_ready_schema_json_1.default,
+    'hadara.task.status.v1': task_status_schema_json_1.default,
     'hadara.task.upgrade_scaffold.v1': task_upgrade_scaffold_schema_json_1.default,
     'hadara.task.workbench.v1': task_workbench_schema_json_1.default,
     'hadara.tools.list.v1': tools_list_schema_json_1.default,
+    'hadara.validation.run.v1': validation_run_schema_json_1.default,
     'hadara.write.preflight.v1': write_preflight_schema_json_1.default
 };
 function loadSchema(schemaId) {