hadara 0.3.2 → 0.3.3-rc.0

package/dist/task/task-finalize.js

@@ -0,0 +1,377 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskFinalizeReport = createTaskFinalizeReport;
+exports.formatTaskFinalizeReport = formatTaskFinalizeReport;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const task_close_1 = require("./task-close");
+const task_finish_1 = require("./task-finish");
+const lifecycle_next_actions_1 = require("./lifecycle-next-actions");
+const task_ready_1 = require("./task-ready");
+function createTaskFinalizeReport(projectRoot, taskId, options = {}) {
+    const actor = options.actor ?? (0, lifecycle_next_actions_1.defaultTaskLifecycleActor)();
+    const reports = createFinalizeReports(projectRoot, taskId, actor);
+    const steps = createSteps(taskId, reports);
+    const issues = collectIssues(reports);
+    const planHash = hashPlan(taskId, steps);
+    if (options.executeRequested)
+        return executeFinalizePlan(projectRoot, taskId, actor, reports, steps, issues, planHash, options.planHash);
+    return createFinalizeReport(taskId, actor, 'dry-run', true, steps, issues, planHash, undefined, reports);
+}
+function formatTaskFinalizeReport(report) {
+    const lines = [`[HADARA] task finalize ${report.taskId}: ${report.mode}`];
+    lines.push(`readOnly=${report.readOnly} ok=${report.ok} planHash=${report.planHash ?? 'none'}`);
+    if (report.primaryNextAction)
+        lines.push(`next=${report.primaryNextAction.command ?? report.primaryNextAction.summary ?? report.primaryNextAction.id}`);
+    for (const step of report.steps)
+        lines.push(`${step.status.toUpperCase()}\t${step.id}\t${step.command}`);
+    for (const issue of report.issues)
+        lines.push(`[${issue.severity}] ${issue.code}: ${issue.message}`);
+    return lines.join('\n');
+}
+function executeFinalizePlan(projectRoot, taskId, actor, initialReports, initialSteps, initialIssues, currentPlanHash, requestedPlanHash) {
+    if (!requestedPlanHash)
+        return createExecuteRefusal(taskId, actor, 'TASK_FINALIZE_PLAN_HASH_REQUIRED', 'task finalize --execute requires a reviewed --plan-hash from a dry-run report.', currentPlanHash, initialSteps);
+    if (requestedPlanHash !== currentPlanHash) {
+        return createExecuteRefusal(taskId, actor, 'TASK_FINALIZE_PLAN_HASH_MISMATCH', 'task finalize --execute refused because --plan-hash does not match the current dry-run plan.', currentPlanHash, initialSteps, {
+            requestedPlanHash,
+            currentPlanHash,
+            planHashMatched: false,
+            executedSteps: []
+        });
+    }
+    const executedSteps = [];
+    const initialBlocker = initialSteps.find((step) => step.status === 'blocked');
+    if (initialBlocker) {
+        return createFinalizeReport(taskId, actor, 'execute', false, initialSteps, initialIssues, currentPlanHash, {
+            requestedPlanHash,
+            currentPlanHash,
+            planHashMatched: true,
+            executedSteps: [createExecutedStep(initialBlocker, false, initialReports[reportKeyForStep(initialBlocker.id)], 'blocked')],
+            stoppedAt: initialBlocker.id
+        }, initialReports);
+    }
+    let reports = initialReports;
+    let steps = initialSteps;
+    let finishStep = steps.find((step) => step.id === 'finish');
+    if (finishStep?.status === 'required') {
+        const finishReport = (0, task_finish_1.createTaskFinishReport)(projectRoot, taskId, 'execute', { actor });
+        executedSteps.push(createExecutedStep(finishStep, finishReport.ok, finishReport, finishReport.ok ? 'executed' : 'blocked'));
+        if (!finishReport.ok)
+            return createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, currentPlanHash, executedSteps, 'finish');
+        reports = createFinalizeReports(projectRoot, taskId, actor);
+        steps = createSteps(taskId, reports);
+    }
+    else if (finishStep?.status === 'satisfied') {
+        executedSteps.push(createExecutedStep(finishStep, true, reports.finish, 'satisfied'));
+    }
+    const readyStep = steps.find((step) => step.id === 'ready');
+    if (readyStep?.status !== 'satisfied') {
+        const readyReport = reports.ready;
+        executedSteps.push(createExecutedStep(readyStep ?? fallbackStep(taskId, 'ready'), readyReport?.ok ?? false, readyReport, readyReport?.ok ? 'satisfied' : 'blocked'));
+        return createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, currentPlanHash, executedSteps, 'ready');
+    }
+    executedSteps.push(createExecutedStep(readyStep, true, reports.ready, 'satisfied'));
+    const closeStep = steps.find((step) => step.id === 'close');
+    if (closeStep?.status === 'required') {
+        const closeReport = (0, task_close_1.createTaskCloseReport)(projectRoot, taskId, 'execute', { actor });
+        if (closeReport.ok)
+            (0, task_close_1.executeTaskCloseEvidence)(projectRoot, closeReport);
+        executedSteps.push(createExecutedStep(closeStep, closeReport.ok, closeReport, closeReport.ok ? 'executed' : 'blocked'));
+        if (!closeReport.ok)
+            return createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, currentPlanHash, executedSteps, 'close');
+        reports = createFinalizeReports(projectRoot, taskId, actor);
+        steps = createSteps(taskId, reports);
+    }
+    else if (closeStep?.status === 'satisfied') {
+        executedSteps.push(createExecutedStep(closeStep, true, reports.close, 'satisfied'));
+    }
+    else {
+        executedSteps.push(createExecutedStep(closeStep ?? fallbackStep(taskId, 'close'), false, reports.close, 'blocked'));
+        return createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, currentPlanHash, executedSteps, 'close');
+    }
+    const auditStep = steps.find((step) => step.id === 'audit-close');
+    const auditReport = reports.audit;
+    executedSteps.push(createExecutedStep(auditStep ?? fallbackStep(taskId, 'audit-close'), auditReport?.ok ?? false, auditReport, auditReport?.ok ? 'satisfied' : 'blocked'));
+    return createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, currentPlanHash, executedSteps, auditReport?.ok ? undefined : 'audit-close');
+}
+function createPostExecutionReport(projectRoot, taskId, actor, requestedPlanHash, reviewedPlanHash, executedSteps, stoppedAt) {
+    const reports = createFinalizeReports(projectRoot, taskId, actor);
+    const steps = createSteps(taskId, reports);
+    const issues = collectIssues(reports);
+    const nextAction = createPrimaryNextAction(taskId, steps, issues);
+    const finalAudit = reports.audit?.auditVerdict.verdict === 'closed-valid';
+    const execution = {
+        requestedPlanHash,
+        currentPlanHash: reviewedPlanHash,
+        planHashMatched: true,
+        executedSteps,
+        ...(stoppedAt ? { stoppedAt } : {})
+    };
+    return {
+        schemaVersion: 'hadara.task.finalize.v1',
+        command: 'task.finalize',
+        ok: finalAudit && issues.every((issue) => issue.severity !== 'error') && steps.every((step) => step.status === 'satisfied'),
+        readOnly: false,
+        mode: 'execute',
+        taskId,
+        generatedAt: new Date().toISOString(),
+        actor,
+        planHash: reviewedPlanHash,
+        summary: summarizeSteps(steps, reports),
+        steps,
+        execution,
+        ...(nextAction ? { primaryNextAction: nextAction } : {}),
+        nextActions: nextAction ? [nextAction] : [],
+        issues
+    };
+}
+function createFinalizeReport(taskId, actor, mode, readOnly, steps, issues, planHash, execution, reports) {
+    const nextAction = createPrimaryNextAction(taskId, steps, issues);
+    return {
+        schemaVersion: 'hadara.task.finalize.v1',
+        command: 'task.finalize',
+        ok: mode === 'execute' ? false : issues.every((issue) => issue.severity !== 'error') && steps.every((step) => step.status === 'satisfied'),
+        readOnly,
+        mode,
+        taskId,
+        generatedAt: new Date().toISOString(),
+        actor,
+        ...(planHash ? { planHash } : {}),
+        summary: summarizeSteps(steps, reports),
+        steps,
+        ...(execution ? { execution } : {}),
+        ...(nextAction ? { primaryNextAction: nextAction } : {}),
+        nextActions: nextAction ? [nextAction] : [],
+        issues
+    };
+}
+function createExecuteRefusal(taskId, actor, code, message, currentPlanHash, steps, execution) {
+    return {
+        ...createFinalizeReport(taskId, actor, 'execute-refused', true, steps, [{ severity: 'error', code, message }], currentPlanHash, execution),
+        ok: false
+    };
+}
+function createFinalizeReports(projectRoot, taskId, actor) {
+    const finish = (0, task_finish_1.createTaskFinishReport)(projectRoot, taskId, 'dry-run', { actor });
+    const finishStatus = getFinishStatus(finish);
+    if (finishStatus === 'blocked')
+        return { finish };
+    if (finishStatus === 'required' && finish.status.taskStatus !== 'Done')
+        return { finish };
+    const close = (0, task_close_1.createTaskCloseReport)(projectRoot, taskId, 'dry-run', { actor });
+    const ready = (0, task_ready_1.createTaskReadyReportFromClosePlan)(projectRoot, taskId, 'done', close, actor);
+    if (!ready.ok)
+        return { finish, ready, close };
+    const audit = (0, task_close_1.createTaskAuditCloseReport)(projectRoot, taskId, { actor });
+    return { finish, ready, close, audit };
+}
+function createSteps(taskId, reports) {
+    const finishStatus = getFinishStatus(reports.finish);
+    const readyStatus = finishStatus === 'satisfied' ? (reports.ready ? (reports.ready.ok ? 'satisfied' : 'required') : 'pending') : 'pending';
+    const closeStatus = readyStatus === 'satisfied'
+        ? reports.audit?.auditVerdict.closeEvidenceFound
+            ? 'satisfied'
+            : reports.close?.ok
+                ? 'required'
+                : 'blocked'
+        : 'pending';
+    const auditStatus = reports.audit ? (reports.audit.auditVerdict.closeEvidenceFound ? (reports.audit.ok ? 'satisfied' : 'required') : 'pending') : 'pending';
+    return [
+        {
+            id: 'finish',
+            status: finishStatus,
+            summary: finishStatus === 'required' ? 'Apply bounded finish bookkeeping.' : finishStatus === 'satisfied' ? 'Finish bookkeeping is current.' : 'Finish blockers must be resolved.',
+            command: finishStatus === 'required' ? `hadara task finish --task ${taskId} --execute --json` : `hadara task finish --task ${taskId} --json`,
+            mode: finishStatus === 'required' ? 'execute' : 'dry-run',
+            writeBoundary: finishStatus === 'required' ? 'task-local' : 'read-only',
+            expectedWritePaths: reports.finish.writes.map((write) => write.path),
+            alreadySatisfied: finishStatus === 'satisfied',
+            sourceReport: 'hadara.task.finish.v1'
+        },
+        {
+            id: 'ready',
+            status: readyStatus,
+            summary: readyStatus === 'satisfied' ? 'Done-level readiness passed.' : readyStatus === 'pending' ? 'Ready waits for finish.' : 'Run readiness and resolve blockers.',
+            command: `hadara task ready --task ${taskId} --level done --json`,
+            mode: 'read-only',
+            writeBoundary: 'read-only',
+            expectedWritePaths: [],
+            alreadySatisfied: readyStatus === 'satisfied',
+            sourceReport: 'hadara.task.ready.v1'
+        },
+        {
+            id: 'close',
+            status: closeStatus,
+            summary: closeStatus === 'required' ? 'Append close evidence after reviewing close dry-run.' : closeStatus === 'satisfied' ? 'Close evidence exists.' : closeStatus === 'pending' ? 'Close waits for readiness.' : 'Close preconditions have blockers.',
+            command: closeStatus === 'required' ? `hadara task close --task ${taskId} --execute --json` : `hadara task close --task ${taskId} --json`,
+            mode: closeStatus === 'required' ? 'execute' : 'dry-run',
+            writeBoundary: closeStatus === 'required' ? 'evidence-append' : 'read-only',
+            expectedWritePaths: closeStatus === 'required' && reports.finish.task ? [`${reports.finish.task.capsule}/evidence.jsonl`] : [],
+            alreadySatisfied: closeStatus === 'satisfied',
+            sourceReport: 'hadara.task.close.v1'
+        },
+        {
+            id: 'audit-close',
+            status: auditStatus,
+            summary: auditStatus === 'satisfied' ? 'Close audit passed.' : auditStatus === 'pending' ? 'Audit waits for close evidence.' : 'Run close audit and repair any drift.',
+            command: `hadara task audit-close --task ${taskId} --json`,
+            mode: 'read-only',
+            writeBoundary: 'read-only',
+            expectedWritePaths: [],
+            alreadySatisfied: auditStatus === 'satisfied',
+            sourceReport: 'hadara.task.audit_close.v1'
+        }
+    ];
+}
+function collectIssues(reports) {
+    const seen = new Set();
+    const issues = [];
+    const reportIssues = [...reports.finish.issues, ...(reports.ready?.issues ?? []), ...(reports.close?.issues ?? []), ...(reports.audit?.issues ?? [])];
+    for (const issue of reportIssues) {
+        const key = `${issue.severity}:${issue.code}:${issue.path ?? ''}:${issue.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        issues.push({
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            ...(issue.path ? { path: issue.path } : {}),
+            ...('fixHint' in issue && issue.fixHint ? { fixHint: issue.fixHint } : {}),
+            ...('example' in issue && issue.example ? { example: issue.example } : {})
+        });
+    }
+    const evidenceQualityIssue = issues.find(isEvidenceQualityIssue);
+    if (evidenceQualityIssue) {
+        issues.push({
+            severity: 'info',
+            code: 'TASK_FINALIZE_EVIDENCE_QUALITY_HINT',
+            message: 'Done-level evidence is missing substantive passed proof. Record validation evidence with --result passed and --category validation after a meaningful check succeeds.',
+            path: evidenceQualityIssue.path,
+            fixHint: 'Use evidence add-command with an explicit passed result/category for real validation output; do not rewrite existing unknown/failed evidence.',
+            example: 'hadara evidence add-command --task T-XXXX --summary "Focused validation passed." --result passed --category validation --json'
+        });
+    }
+    return issues;
+}
+function createPrimaryNextAction(taskId, steps, issues) {
+    const nextStep = steps.find((step) => step.status === 'required' || step.status === 'blocked');
+    if (!nextStep)
+        return undefined;
+    if (nextStep.id === 'ready' && issues.some(isEvidenceQualityIssue)) {
+        return (0, lifecycle_next_actions_1.createTaskLifecycleNextAction)({
+            id: 'finalize-record-passed-evidence',
+            kind: 'command',
+            required: true,
+            command: `hadara evidence add-command --task ${taskId} --summary "Focused validation passed." --result passed --category validation --json`,
+            message: 'Record substantive passed validation evidence before rerunning readiness.',
+            writeBoundary: 'evidence-append',
+            recommendedActorRole: 'worker',
+            requiresBeforeHash: false,
+            stalePlanRisk: 'low'
+        });
+    }
+    return (0, lifecycle_next_actions_1.createTaskLifecycleNextAction)({
+        id: `finalize-${nextStep.id}`,
+        kind: nextStep.status === 'blocked' ? 'review' : 'command',
+        required: true,
+        command: nextStep.status === 'blocked' ? undefined : nextStep.command,
+        message: nextStep.summary,
+        writeBoundary: nextStep.writeBoundary,
+        recommendedActorRole: nextStep.writeBoundary === 'read-only' ? 'reviewer' : 'worker',
+        requiresBeforeHash: false,
+        stalePlanRisk: nextStep.writeBoundary === 'read-only' ? 'none' : 'low'
+    });
+}
+function summarizeSteps(steps, reports) {
+    const evaluatedReports = evaluatedReportNames(steps, reports);
+    const skippedReports = ['finish', 'ready', 'close', 'audit-close'].filter((name) => !evaluatedReports.includes(name));
+    return {
+        steps: steps.length,
+        required: steps.filter((step) => step.status === 'required').length,
+        blocked: steps.filter((step) => step.status === 'blocked').length,
+        satisfied: steps.filter((step) => step.status === 'satisfied').length,
+        executeSupported: true,
+        evaluatedReports,
+        skippedReports
+    };
+}
+function createExecutedStep(step, ok, report, status) {
+    return {
+        id: step.id,
+        status,
+        command: step.command,
+        ok,
+        reportHash: hashReport(report),
+        summary: step.summary,
+        writeBoundary: step.writeBoundary
+    };
+}
+function hashReport(report) {
+    return `sha256:${node_crypto_1.default.createHash('sha256').update(JSON.stringify(report)).digest('hex')}`;
+}
+function reportKeyForStep(stepId) {
+    if (stepId === 'finish')
+        return 'finish';
+    if (stepId === 'ready')
+        return 'ready';
+    if (stepId === 'close')
+        return 'close';
+    return 'audit';
+}
+function getFinishStatus(finish) {
+    return finish.ok ? (finish.summary.plannedWrites > 0 ? 'required' : 'satisfied') : 'blocked';
+}
+function evaluatedReportNames(steps, reports) {
+    if (reports)
+        return ['finish', ...(reports.ready ? ['ready'] : []), ...(reports.close ? ['close'] : []), ...(reports.audit ? ['audit-close'] : [])];
+    const evaluated = new Set(['finish']);
+    for (const step of steps) {
+        if (step.id === 'ready' && step.status !== 'pending')
+            evaluated.add('ready');
+        if (step.id === 'close' && step.status !== 'pending')
+            evaluated.add('close');
+        if (step.id === 'audit-close' && step.status !== 'pending')
+            evaluated.add('audit-close');
+    }
+    return [...evaluated];
+}
+function isEvidenceQualityIssue(issue) {
+    return (issue.code.includes('TASK_DONE_WITHOUT_SUBSTANTIVE_EVIDENCE') ||
+        issue.code.includes('TASK_DONE_WITH_ONLY_WEAK_EVIDENCE') ||
+        issue.code.includes('EVIDENCE_REQUIRED') ||
+        issue.code.includes('WITHOUT_SUBSTANTIVE_EVIDENCE') ||
+        issue.code.includes('ONLY_WEAK_EVIDENCE'));
+}
+function fallbackStep(taskId, id) {
+    return {
+        id,
+        status: 'unknown',
+        summary: 'Step state could not be determined.',
+        command: id === 'audit-close' ? `hadara task audit-close --task ${taskId} --json` : `hadara task ${id} --task ${taskId} --json`,
+        mode: 'read-only',
+        writeBoundary: 'read-only',
+        expectedWritePaths: [],
+        alreadySatisfied: false,
+        sourceReport: 'unknown'
+    };
+}
+function hashPlan(taskId, steps) {
+    const stable = {
+        taskId,
+        steps: steps.map((step) => ({
+            id: step.id,
+            status: step.status,
+            command: step.command,
+            mode: step.mode,
+            writeBoundary: step.writeBoundary,
+            expectedWritePaths: step.expectedWritePaths,
+            alreadySatisfied: step.alreadySatisfied,
+            sourceReport: step.sourceReport
+        }))
+    };
+    return `sha256:${node_crypto_1.default.createHash('sha256').update(JSON.stringify(stable)).digest('hex')}`;
+}

package/dist/task/task-lifecycle.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskLifecycleReport = createTaskLifecycleReport;
+exports.formatTaskLifecycleReport = formatTaskLifecycleReport;
+const task_close_1 = require("./task-close");
+const task_finish_1 = require("./task-finish");
+const lifecycle_next_actions_1 = require("./lifecycle-next-actions");
+const task_ready_1 = require("./task-ready");
+function createTaskLifecycleReport(projectRoot, taskId, options = {}) {
+    const actor = options.actor ?? (0, lifecycle_next_actions_1.defaultTaskLifecycleActor)();
+    const reports = {
+        finish: (0, task_finish_1.createTaskFinishReport)(projectRoot, taskId, 'dry-run', { actor }),
+        ready: (0, task_ready_1.createTaskReadyReport)(projectRoot, taskId, 'done', { actor }),
+        close: (0, task_close_1.createTaskCloseReport)(projectRoot, taskId, 'dry-run', { actor }),
+        audit: (0, task_close_1.createTaskAuditCloseReport)(projectRoot, taskId, { actor })
+    };
+    const checks = createChecks(taskId, reports);
+    const repair = createRepair(taskId, reports.audit);
+    const phase = choosePhase(reports, checks, repair);
+    const nextAction = chooseNextAction(taskId, phase, reports, checks, repair);
+    const issues = collectIssues(reports);
+    const blockers = collectBlockers(phase, reports, checks, repair);
+    const satisfied = Object.entries(checks)
+        .filter(([, check]) => check.status === 'satisfied')
+        .map(([id]) => id);
+    return {
+        schemaVersion: 'hadara.task.lifecycle.v1',
+        command: 'task.lifecycle',
+        ok: !reports.finish.issues.some((issue) => issue.code === 'TASK_NOT_FOUND'),
+        readOnly: true,
+        taskId,
+        generatedAt: new Date().toISOString(),
+        actor,
+        phase,
+        checks,
+        satisfied,
+        blockers,
+        ...(repair ? { repair } : {}),
+        ...(nextAction ? { primaryNextAction: nextAction } : {}),
+        nextActions: nextAction ? [nextAction] : [],
+        issues
+    };
+}
+function formatTaskLifecycleReport(report) {
+    const lines = [`[HADARA] task lifecycle ${report.taskId}: ${report.phase}`];
+    lines.push(`readOnly=${report.readOnly} ok=${report.ok}`);
+    if (report.primaryNextAction)
+        lines.push(`next=${report.primaryNextAction.command ?? report.primaryNextAction.summary ?? report.primaryNextAction.id}`);
+    for (const [id, check] of Object.entries(report.checks))
+        lines.push(`${check.status.toUpperCase()}\t${id}\t${check.summary}`);
+    for (const blocker of report.blockers)
+        lines.push(`[${blocker.severity}] ${blocker.code}: ${blocker.summary}`);
+    if (report.repair && report.repair.classification !== 'closed-valid')
+        lines.push(`repair=${report.repair.classification}\t${report.repair.summary}`);
+    return lines.join('\n');
+}
+function createChecks(taskId, reports) {
+    const sharedDocsPending = reports.finish.stateDocs.filter((doc) => doc.state === 'pending' || doc.state === 'missing');
+    return {
+        finish: {
+            status: reports.finish.ok ? (reports.finish.summary.plannedWrites > 0 ? 'required' : 'satisfied') : 'blocked',
+            summary: reports.finish.summary.plannedWrites > 0 ? 'Task status bookkeeping has planned writes.' : reports.finish.ok ? 'Task finish bookkeeping is current.' : 'Task finish blockers exist.',
+            sourceReport: 'hadara.task.finish.v1',
+            command: reports.finish.summary.plannedWrites > 0 ? `hadara task finish --task ${taskId} --json` : undefined
+        },
+        sharedDocs: {
+            status: sharedDocsPending.length > 0 ? 'warning' : reports.finish.ok ? 'satisfied' : 'pending',
+            summary: sharedDocsPending.length > 0 ? `${sharedDocsPending.length} shared state doc(s) are pending or missing this task.` : 'Shared state docs are current for this task.',
+            sourceReport: 'hadara.task.finish.v1'
+        },
+        ready: {
+            status: reports.ready.ok ? 'satisfied' : 'required',
+            summary: reports.ready.ok ? 'Done-level readiness passed.' : 'Done-level readiness requires remediation.',
+            sourceReport: 'hadara.task.ready.v1',
+            command: `hadara task ready --task ${taskId} --level done --json`
+        },
+        close: {
+            status: reports.audit.auditVerdict.closeEvidenceFound ? 'satisfied' : reports.close.ok ? 'required' : 'blocked',
+            summary: reports.audit.auditVerdict.closeEvidenceFound ? 'Close evidence exists.' : reports.close.ok ? 'Close evidence has not been appended.' : 'Close preconditions have blockers.',
+            sourceReport: 'hadara.task.close.v1',
+            command: reports.audit.auditVerdict.closeEvidenceFound ? undefined : `hadara task close --task ${taskId} --json`
+        },
+        audit: {
+            status: reports.audit.ok ? 'satisfied' : reports.audit.auditVerdict.closeEvidenceFound ? 'required' : 'pending',
+            summary: reports.audit.ok ? 'Close audit passed.' : reports.audit.auditVerdict.closeEvidenceFound ? 'Close audit requires repair.' : 'Audit waits for close evidence.',
+            sourceReport: 'hadara.task.audit_close.v1',
+            command: `hadara task audit-close --task ${taskId} --json`
+        }
+    };
+}
+function choosePhase(reports, checks, repair) {
+    if (reports.finish.issues.some((issue) => issue.code === 'TASK_NOT_FOUND'))
+        return 'unknown';
+    if (!reports.finish.ok)
+        return 'blocked';
+    if (checks.finish.status === 'required')
+        return 'finish-required';
+    if (checks.sharedDocs.status === 'warning')
+        return 'ready-required';
+    if (!reports.ready.ok)
+        return 'ready-required';
+    if (!reports.close.ok)
+        return 'ready-required';
+    if (!reports.audit.auditVerdict.closeEvidenceFound)
+        return 'close-required';
+    if (reports.audit.ok)
+        return 'closed-valid';
+    if (repair && repair.classification !== 'closed-valid')
+        return 'repair-required';
+    return 'audit-required';
+}
+function chooseNextAction(taskId, phase, reports, checks, repair) {
+    if (phase === 'closed-valid')
+        return undefined;
+    if (phase === 'unknown')
+        return reviewAction('select-existing-task', `Select an existing Task Capsule before inspecting lifecycle state for ${taskId}.`);
+    if (phase === 'blocked')
+        return reports.finish.primaryNextAction ?? reviewAction('resolve-finish-blockers', `Resolve task finish blockers for ${taskId}.`);
+    if (phase === 'finish-required')
+        return reports.finish.primaryNextAction;
+    if (checks.sharedDocs.status === 'warning') {
+        return reports.finish.primaryNextAction ?? reviewAction('update-state-docs', `Update shared state docs for ${taskId} before close.`, 'shared-doc', 'coordinator', true, 'medium');
+    }
+    if (phase === 'ready-required')
+        return reports.ready.primaryNextAction ?? reports.close.primaryNextAction;
+    if (phase === 'close-required')
+        return reports.close.nextActions.find((action) => action.id === 'append-close-evidence') ?? reports.close.primaryNextAction;
+    if (phase === 'repair-required') {
+        return reviewAction('repair-close-proof', repair?.summary ?? `Repair close proof for ${taskId}.`, 'read-only', 'reviewer', false, 'none', repair?.nextCommand);
+    }
+    if (phase === 'audit-required')
+        return reports.audit.primaryNextAction ?? reviewAction('run-audit-close', `Run close audit for ${taskId}.`, 'read-only', 'reviewer', false, 'none', `hadara task audit-close --task ${taskId} --json`);
+    return undefined;
+}
+function createRepair(taskId, audit) {
+    if (audit.ok) {
+        return {
+            classification: 'closed-valid',
+            summary: 'Close proof is current and valid.',
+            sourceReport: 'hadara.task.audit_close.v1'
+        };
+    }
+    if (!audit.auditVerdict.closeEvidenceFound) {
+        return {
+            classification: 'not-closed',
+            summary: 'No close evidence exists for this task.',
+            nextCommand: `hadara task close --task ${taskId} --json`,
+            sourceReport: 'hadara.task.audit_close.v1'
+        };
+    }
+    if (!audit.auditVerdict.closeEvidenceValid) {
+        return {
+            classification: 'closed-invalid',
+            summary: 'Close evidence exists but is invalid or malformed.',
+            nextCommand: `hadara task close --task ${taskId} --json`,
+            sourceReport: 'hadara.task.audit_close.v1'
+        };
+    }
+    if (!audit.auditVerdict.reportHashMatches || !audit.auditVerdict.sourceHashMatches) {
+        return {
+            classification: 'closed-stale',
+            summary: 'Close evidence exists but no longer matches current validation or source hashes.',
+            nextCommand: `hadara task close --task ${taskId} --json`,
+            sourceReport: 'hadara.task.audit_close.v1'
+        };
+    }
+    return {
+        classification: 'unknown',
+        summary: 'Close audit did not pass and no specific repair classification matched.',
+        nextCommand: `hadara task audit-close --task ${taskId} --json`,
+        sourceReport: 'hadara.task.audit_close.v1'
+    };
+}
+function collectBlockers(phase, reports, checks, repair) {
+    const blockers = [];
+    if (phase === 'unknown')
+        blockers.push({ code: 'TASK_LIFECYCLE_TASK_UNKNOWN', severity: 'error', summary: 'Task was not found.' });
+    if (phase === 'blocked')
+        blockers.push({ code: 'TASK_LIFECYCLE_FINISH_BLOCKED', severity: 'error', summary: 'Task finish report has blockers.', command: reports.finish.primaryNextAction?.command });
+    if (checks.sharedDocs.status === 'warning')
+        blockers.push({ code: 'TASK_LIFECYCLE_SHARED_DOCS_PENDING', severity: 'warning', summary: checks.sharedDocs.summary, command: reports.finish.primaryNextAction?.command });
+    if (phase === 'repair-required' && repair)
+        blockers.push({ code: 'TASK_LIFECYCLE_CLOSE_REPAIR_REQUIRED', severity: 'warning', summary: repair.summary, command: repair.nextCommand });
+    return blockers;
+}
+function collectIssues(reports) {
+    const seen = new Set();
+    const issues = [];
+    for (const issue of [...reports.finish.issues, ...reports.ready.issues, ...reports.close.issues, ...reports.audit.issues]) {
+        const key = `${issue.severity}:${issue.code}:${issue.path ?? ''}:${issue.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        issues.push({ severity: issue.severity, code: issue.code, message: issue.message, ...(issue.path ? { path: issue.path } : {}) });
+    }
+    return issues;
+}
+function reviewAction(id, message, writeBoundary = 'read-only', recommendedActorRole = 'worker', requiresBeforeHash = false, stalePlanRisk = 'none', command) {
+    return (0, lifecycle_next_actions_1.createTaskLifecycleNextAction)({
+        id,
+        kind: command ? 'command' : 'review',
+        required: true,
+        message,
+        ...(command ? { command } : {}),
+        writeBoundary,
+        recommendedActorRole,
+        requiresBeforeHash,
+        stalePlanRisk
+    });
+}

package/dist/task/task-next.js

@@ -97,7 +97,7 @@ function recommendationFromHandoff(projectRoot, step, boardRows, capsules) {
     };
 }
 function recommendationFromTaskBoard(boardRows, capsules) {
-    const row = boardRows.find((candidate) => isOpenBoardStatus(candidate.status));
+    const row = boardRows.find((candidate) => isPrimaryOpenBoardStatus(candidate.status)) ?? boardRows.find((candidate) => isOpenBoardStatus(candidate.status));
     if (!row)
         return null;
     const capsule = capsules.find((task) => task.id === row.taskId);
@@ -169,10 +169,16 @@ function isActionableHandoffStep(step) {
     const normalized = step.trim().toLowerCase();
     if (!normalized || normalized === 'step' || normalized === 'tbd')
         return false;
+    if (isTaskNextMetaGuidance(normalized))
+        return false;
     if (normalized.startsWith('migrate selected historical evidence only when explicitly requested'))
         return false;
     return true;
 }
+function isTaskNextMetaGuidance(normalizedStep) {
+    const compact = normalizedStep.replace(/[`*_]/g, '').replace(/\s+/g, ' ');
+    return /\b(hadara\s+)?task\s+next\b/.test(compact) && /\b(run|select|choose|create)\b/.test(compact);
+}
 function normalizeHandoffTitle(step) {
     return step
         .replace(/^continue\s+(with\s+)?/i, '')
@@ -189,6 +195,9 @@ function isOpenBoardStatus(status) {
     const normalized = status.trim().toLowerCase();
     return Boolean(normalized) && !normalized.startsWith('done') && !normalized.startsWith('superseded');
 }
+function isPrimaryOpenBoardStatus(status) {
+    return isOpenBoardStatus(status) && !status.trim().toLowerCase().startsWith('partial');
+}
 function toPortablePath(value) {
     return value.split(node_path_1.default.sep).join('/');
 }

package/dist/task/task-ready.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTaskReadyReport = createTaskReadyReport;
+exports.createTaskReadyReportFromClosePlan = createTaskReadyReportFromClosePlan;
 const task_close_1 = require("./task-close");
 const lifecycle_next_actions_1 = require("./lifecycle-next-actions");
 function createTaskReadyReport(projectRoot, taskId, level = 'done', options = {}) {
     const actor = options.actor ?? (0, lifecycle_next_actions_1.defaultTaskLifecycleActor)();
     const closePlan = (0, task_close_1.createTaskCloseReport)(projectRoot, taskId, 'dry-run', { actor });
+    return createTaskReadyReportFromClosePlan(projectRoot, taskId, level, closePlan, actor);
+}
+function createTaskReadyReportFromClosePlan(projectRoot, taskId, level, closePlan, actor) {
     const ready = closePlan.ok;
     const nextActions = ready
         ? [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadara",
-  "version": "0.3.2",
+  "version": "0.3.3-rc.0",
   "private": false,
   "license": "MIT",
   "description": "Portable AI-assisted development workbench for evidence-backed task capsules, handoffs, and release gates.",