hadara 0.3.3 → 0.4.0-rc.0

package/dist/cli/init.js

@@ -11,14 +11,15 @@ const node_path_1 = __importDefault(require("node:path"));
 const paths_1 = require("../core/paths");
 const fs_1 = require("../core/fs");
 const args_1 = require("./args");
+const legacy_boundary_1 = require("./legacy-boundary");
 const docs_registry_1 = require("../services/docs-registry");
 const managed_sections_1 = require("../services/managed-sections");
 const INIT_PROFILE_SPECS = {
     basic: {
         profile: 'basic',
-        generatedDocsDescription: 'Core session docs plus task workflow commands',
+        generatedDocsDescription: 'Core current-state docs, workflow reference, registries, and task directory',
         intendedUse: 'Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead.',
-        specialNotes: 'SOP required reading references core docs, task workflow docs, and active Task Capsule docs.',
+        specialNotes: 'Basic keeps continuation fields in PROJECT_STATE instead of generating AGENT_HANDOFF.',
         docs: {
             architecture: false,
             developmentSlices: false,
@@ -26,37 +27,40 @@ const INIT_PROFILE_SPECS = {
             refactorLog: false,
             securityModel: false,
             testStrategy: false,
-            roadmap: false
+            roadmap: false,
+            agentHandoff: false
         }
     },
     standard: {
         profile: 'standard',
-        generatedDocsDescription: 'Core docs plus planning, architecture, decision, and validation docs',
-        intendedUse: 'Most multi-session projects that need roadmap slices and repeatable validation.',
+        generatedDocsDescription: 'Core scaffold plus architecture, roadmap, and decision docs',
+        intendedUse: 'Most multi-session projects that need lightweight planning and decision context.',
         specialNotes: 'Default profile. Optional integrations must be registered before agents rely on them.',
         docs: {
             architecture: true,
-            developmentSlices: true,
+            developmentSlices: false,
             decisions: true,
             refactorLog: false,
             securityModel: false,
-            testStrategy: true,
-            roadmap: false
+            testStrategy: false,
+            roadmap: true,
+            agentHandoff: false
         }
     },
     governed: {
         profile: 'governed',
-        generatedDocsDescription: 'Standard docs plus security, refactor log, and roadmap docs',
+        generatedDocsDescription: 'Standard scaffold plus handoff and security docs',
         intendedUse: 'Long-lived projects with stronger governance, security boundaries, refactor history, or roadmap-level planning.',
-        specialNotes: 'Project-specific contracts still must be manually registered in the SOP when they become real.',
+        specialNotes: 'Governed projects generate AGENT_HANDOFF for compact continuation state.',
         docs: {
             architecture: true,
-            developmentSlices: true,
+            developmentSlices: false,
             decisions: true,
-            refactorLog: true,
+            refactorLog: false,
             securityModel: true,
-            testStrategy: true,
-            roadmap: true
+            testStrategy: false,
+            roadmap: true,
+            agentHandoff: true
         }
     }
 };
@@ -99,17 +103,35 @@ function parseInitProfile(value) {
 }
 function handleInitCommand(input) {
     const subcommand = input.args[1];
+    if (subcommand === 'help' || (0, args_1.getFlag)(input.args, '--help') || (0, args_1.getFlag)(input.args, '-h')) {
+        console.log(renderInitHelp());
+        return true;
+    }
     if (subcommand === 'doctor') {
         printInitFollowUpReport(createInitDoctorReport(input.projectRoot), input.jsonOutput);
         return true;
     }
     if (subcommand === 'upgrade') {
+        const legacyReport = (0, legacy_boundary_1.createLegacyMutationBlockedReport)(input.projectRoot, 'init.upgrade');
+        if (legacyReport) {
+            (0, legacy_boundary_1.printLegacyMutationBlockedReport)(legacyReport, input.jsonOutput === true);
+            process.exitCode = 6;
+            return true;
+        }
         const profile = parseInitProfile((0, args_1.getRequiredStringOption)(input.args, '--profile'));
         const report = createInitUpgradeReport(input.projectRoot, profile, getInitFollowUpMode(input.args));
         printInitFollowUpReport(report, input.jsonOutput);
         return true;
     }
     if (subcommand === 'register-doc') {
+        if ((0, args_1.getFlag)(input.args, '--execute') === true) {
+            const legacyReport = (0, legacy_boundary_1.createLegacyMutationBlockedReport)(input.projectRoot, 'init.register-doc');
+            if (legacyReport) {
+                (0, legacy_boundary_1.printLegacyMutationBlockedReport)(legacyReport, input.jsonOutput === true);
+                process.exitCode = 6;
+                return true;
+            }
+        }
         const report = createRequiredReadingRegistrationReport(input.projectRoot, {
             documentPath: (0, args_1.getRequiredStringOption)(input.args, '--path'),
             when: (0, args_1.getRequiredStringOption)(input.args, '--when'),
@@ -121,6 +143,14 @@ function handleInitCommand(input) {
         return true;
     }
     if (subcommand === 'enable-integration') {
+        if ((0, args_1.getFlag)(input.args, '--execute') === true) {
+            const legacyReport = (0, legacy_boundary_1.createLegacyMutationBlockedReport)(input.projectRoot, 'init.enable-integration');
+            if (legacyReport) {
+                (0, legacy_boundary_1.printLegacyMutationBlockedReport)(legacyReport, input.jsonOutput === true);
+                process.exitCode = 6;
+                return true;
+            }
+        }
         const report = createIntegrationEnableReport(input.projectRoot, {
             integration: (0, args_1.getRequiredStringOption)(input.args, '--integration'),
             mode: getInitFollowUpMode(input.args)
@@ -133,6 +163,25 @@ function handleInitCommand(input) {
         console.log(JSON.stringify(report, null, 2));
     return true;
 }
+function renderInitHelp() {
+    return `HADARA init
+
+Usage:
+  hadara init [--profile basic|standard|governed] [--json]
+  hadara init doctor [--json]
+  hadara init upgrade --profile <profile> [--execute] [--json]
+  hadara init register-doc --path <path> --when <text> --purpose <text> [--execute] [--json]
+  hadara init enable-integration --integration <name> [--execute] [--json]
+
+Profiles:
+  basic      Core current-state docs, workflow reference, registries, and task directory.
+  standard   Default profile with architecture, roadmap, and decision docs.
+  governed   Standard profile plus handoff and security docs.
+
+Notes:
+  --help is read-only and does not create scaffold files.
+`;
+}
 function getInitFollowUpMode(args) {
     return (0, args_1.getFlag)(args, '--execute') ? 'execute' : 'dry-run';
 }
@@ -141,39 +190,58 @@ function createGeneratedScaffoldFiles(profile) {
     const docsRegistry = (0, docs_registry_1.createSeedDocumentRegistry)(profile);
     const files = [
         { path: '.hadara/context/HADARA_CONTEXT.md', content: (0, docs_registry_1.createHadaraContextDoc)(profile) },
+        { path: '.hadara/scaffold.json', content: createScaffoldJson(profile) },
         { path: '.hadara/docs-registry.json', content: (0, docs_registry_1.registryJson)(docsRegistry) },
-        { path: 'docs/DOC_REGISTRY.md', content: (0, docs_registry_1.renderDocRegistryMarkdown)(docsRegistry) },
+        { path: '.hadara/slot-registry.json', content: createSlotRegistryJson() },
         { path: 'docs/PROJECT_STATE.md', content: createProjectStateDoc(profile) },
         { path: 'docs/TASK_BOARD.md', content: createTaskBoardDoc() },
-        { path: 'docs/AGENT_HANDOFF.md', content: createAgentHandoffDoc() },
-        { path: 'docs/IMPLEMENTATION_SOP.md', content: createImplementationSopDoc(spec) },
-        { path: 'docs/TASK_WORKFLOW_COMMANDS.md', content: createTaskWorkflowCommandsDoc() },
+        { path: 'docs/HADARA_WORKFLOW.md', content: createHadaraWorkflowDoc() },
         { path: 'AGENTS.md', content: createAgentsDoc(spec) },
-        { path: '.gitignore', content: createGitignoreDoc() }
+        { path: '.gitignore', content: createGitignoreDoc() },
+        { path: 'tasks/.gitkeep', content: '' }
     ];
     if (spec.docs.architecture)
         files.push({ path: 'docs/ARCHITECTURE.md', content: createArchitectureDoc(profile) });
-    if (spec.docs.developmentSlices)
-        files.push({ path: 'docs/DEVELOPMENT_SLICES.md', content: createDevelopmentSlicesDoc() });
     if (spec.docs.decisions)
         files.push({ path: 'docs/DECISIONS.md', content: createDecisionsDoc() });
-    if (spec.docs.refactorLog)
-        files.push({ path: 'docs/REFACTOR_LOG.md', content: createRefactorLogDoc() });
     if (spec.docs.securityModel)
         files.push({ path: 'docs/SECURITY_MODEL.md', content: createSecurityModelDoc() });
-    if (spec.docs.testStrategy)
-        files.push({ path: 'docs/TEST_STRATEGY.md', content: createTestStrategyDoc() });
     if (spec.docs.roadmap)
         files.push({ path: 'docs/ROADMAP.md', content: createRoadmapDoc() });
+    if (spec.docs.agentHandoff)
+        files.push({ path: 'docs/AGENT_HANDOFF.md', content: createAgentHandoffDoc() });
     return files;
 }
 function createInitDoctorReport(projectRoot) {
     const issues = [];
     const actions = [];
-    const requiredCore = ['AGENTS.md', '.gitignore', '.hadara/context/HADARA_CONTEXT.md', 'docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/TASK_WORKFLOW_COMMANDS.md'];
-    for (const relativePath of requiredCore) {
+    const requiredCore = [
+        { path: 'AGENTS.md', code: 'INIT_CORE_DOC_MISSING' },
+        { path: '.gitignore', code: 'INIT_GITIGNORE_MISSING' },
+        { path: '.hadara/context/HADARA_CONTEXT.md', code: 'INIT_CORE_DOC_MISSING' },
+        { path: '.hadara/scaffold.json', code: 'INIT_PROTOCOL_MISSING' },
+        { path: '.hadara/docs-registry.json', code: 'INIT_DOCS_REGISTRY_MISSING' },
+        { path: '.hadara/slot-registry.json', code: 'INIT_SLOT_REGISTRY_MISSING' },
+        { path: 'docs/PROJECT_STATE.md', code: 'INIT_CORE_DOC_MISSING' },
+        { path: 'docs/TASK_BOARD.md', code: 'INIT_CORE_DOC_MISSING' },
+        { path: 'docs/HADARA_WORKFLOW.md', code: 'INIT_WORKFLOW_DOC_MISSING' }
+    ];
+    for (const required of requiredCore) {
+        const relativePath = required.path;
         if (!node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath))) {
-            issues.push({ severity: 'error', code: 'INIT_CORE_DOC_MISSING', path: relativePath, message: `${relativePath} is missing from the init scaffold.` });
+            issues.push({ severity: 'error', code: required.code, path: relativePath, message: `${relativePath} is missing from the init scaffold.` });
+        }
+    }
+    const scaffold = readProjectText(projectRoot, '.hadara/scaffold.json');
+    if (scaffold !== null) {
+        try {
+            const parsed = JSON.parse(scaffold);
+            if (parsed.hadaraProtocol !== '0.4') {
+                issues.push({ severity: 'error', code: 'INIT_PROTOCOL_UNSUPPORTED', path: '.hadara/scaffold.json', message: '.hadara/scaffold.json must declare hadaraProtocol "0.4".' });
+            }
+        }
+        catch (error) {
+            issues.push({ severity: 'error', code: 'INIT_PROTOCOL_UNSUPPORTED', path: '.hadara/scaffold.json', message: `.hadara/scaffold.json could not be parsed: ${error instanceof Error ? error.message : String(error)}` });
         }
     }
     for (const relativePath of ['HERMES.md', '.hermes.md']) {
@@ -192,6 +260,9 @@ function createInitDoctorReport(projectRoot) {
     if (sop !== null && mentionsLegacyInitProfile(sop)) {
         issues.push({ severity: 'warning', code: 'INIT_OLD_PROFILE_NAME', path: 'docs/IMPLEMENTATION_SOP.md', message: 'SOP mentions old init profile names.' });
     }
+    issues.push(...detectEntryDocDuplication(projectRoot));
+    issues.push(...detectRequiredReadingTooBroad(projectRoot));
+    issues.push(...detectProductDefaultLeaks(projectRoot));
     issues.push(...detectProfileMetadataMismatches(projectRoot));
     for (const [relativePath, headers] of Object.entries(CANONICAL_TABLE_HEADERS)) {
         const content = readProjectText(projectRoot, relativePath);
@@ -217,6 +288,110 @@ function createInitDoctorReport(projectRoot) {
 function mentionsLegacyInitProfile(content) {
     return /(?:initialized with|profile(?:\s+name)?|init profile)\s+(?:the\s+)?`?(minimal|full|hadara-protocol)`?/i.test(content);
 }
+function detectEntryDocDuplication(projectRoot) {
+    const issues = [];
+    const agents = readProjectText(projectRoot, 'AGENTS.md');
+    if (agents !== null && commandRecipeCount(agents) >= 2) {
+        issues.push({
+            severity: 'warning',
+            code: 'INIT_AGENTS_COMMAND_COOKBOOK',
+            path: 'AGENTS.md',
+            message: 'AGENTS.md appears to duplicate lifecycle or context command recipes; keep command usage in docs/HADARA_WORKFLOW.md.'
+        });
+    }
+    const context = readProjectText(projectRoot, '.hadara/context/HADARA_CONTEXT.md');
+    if (context !== null && (context.includes('| Document | When to Read | Purpose |') || context.includes('## Required Reading') || commandRecipeCount(context) >= 2)) {
+        issues.push({
+            severity: 'warning',
+            code: 'INIT_CONTEXT_DUPLICATES_WORKFLOW',
+            path: '.hadara/context/HADARA_CONTEXT.md',
+            message: 'HADARA_CONTEXT.md appears to duplicate Required Reading or command recipes; keep it as a compact routing anchor.'
+        });
+    }
+    return issues;
+}
+function commandRecipeCount(content) {
+    const matches = content.match(/^\s*`?hadara\s+(?:task|context|session|evidence|docs|harness|init)\s+[a-z-]+/gm);
+    return new Set(matches ?? []).size;
+}
+function detectRequiredReadingTooBroad(projectRoot) {
+    const registry = readDocsRegistryForDoctor(projectRoot);
+    if (registry === null)
+        return [];
+    const broad = registry.documents.filter((doc) => {
+        const raw = doc;
+        const defaultRead = doc.requiredReading || doc.readWhen.includes('session-start') || doc.readWhen.includes('task-start');
+        if (!defaultRead)
+            return false;
+        return doc.status === 'historical'
+            || doc.status === 'superseded'
+            || doc.status === 'archived'
+            || raw.readTier === 'historical'
+            || raw.readTier === 'excluded'
+            || raw.readTier === 'drift-review'
+            || raw.drift?.reviewRequiredBeforeUse === true
+            || raw.drift?.risk === 'medium'
+            || raw.drift?.risk === 'high';
+    });
+    return broad.map((doc) => ({
+        severity: 'warning',
+        code: 'INIT_REQUIRED_READING_TOO_BROAD',
+        path: doc.path,
+        message: `${doc.path} is in the default read path but is historical, excluded, superseded, archived, or drift-risk.`
+    }));
+}
+function readDocsRegistryForDoctor(projectRoot) {
+    const registryPath = node_path_1.default.join(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH);
+    if (!node_fs_1.default.existsSync(registryPath))
+        return null;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(registryPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function detectProductDefaultLeaks(projectRoot) {
+    const paths = [
+        'AGENTS.md',
+        '.hadara/context/HADARA_CONTEXT.md',
+        'docs/HADARA_WORKFLOW.md',
+        'docs/PROJECT_STATE.md',
+        'docs/AGENT_HANDOFF.md',
+        'docs/ARCHITECTURE.md',
+        'docs/ROADMAP.md',
+        'docs/DECISIONS.md',
+        'docs/SECURITY_MODEL.md'
+    ];
+    const issues = [];
+    for (const relativePath of paths) {
+        const content = readProjectText(projectRoot, relativePath);
+        if (content === null)
+            continue;
+        const token = productDefaultLeakToken(content);
+        if (token) {
+            issues.push({
+                severity: 'warning',
+                code: 'INIT_PRODUCT_DEFAULT_LEAK',
+                path: relativePath,
+                message: `${relativePath} appears to contain project-specific generated default text (${token}); product scaffolds must stay generic.`
+            });
+        }
+    }
+    return issues;
+}
+function productDefaultLeakToken(content) {
+    const checks = [
+        [/\bHADARA-dev\b/, 'HADARA-dev'],
+        [/\bDocker\b|\bdocker\s+(?:exec|run|compose|ps|build)\b/i, 'Docker'],
+        [/\bnpm\s+(?:run|publish|view|ci|install|pack)\b/i, 'npm'],
+        [/\bnode\s+dist\/cli\/main\.js\b/i, 'node dist/cli/main.js'],
+        [/\bhadara\s+(?:release|package|smoke)\s+(?:publish|artifact|gate|dry-run|closeout|smoke|recycle|clean-checkout)\b/i, 'release/package command'],
+        [/\/workspace\b|\/mnt\/|[A-Za-z]:\\/, 'machine-local path'],
+        [/\bhadara@\d+\.\d+\.\d+/, 'package version']
+    ];
+    return checks.find(([pattern]) => pattern.test(content))?.[1] ?? null;
+}
 function createInitUpgradeReport(projectRoot, profile, mode) {
     const actions = [];
     const issues = [];
@@ -415,7 +590,12 @@ function createSopRowUpdatePlan(projectRoot, input) {
     const sopPath = node_path_1.default.join(projectRoot, 'docs', 'IMPLEMENTATION_SOP.md');
     const sop = node_fs_1.default.existsSync(sopPath) ? node_fs_1.default.readFileSync(sopPath, 'utf8') : null;
     if (sop === null) {
-        issues.push({ severity: 'error', code: 'INIT_SOP_MISSING', path: 'docs/IMPLEMENTATION_SOP.md', message: 'SOP Required Reading table cannot be updated because IMPLEMENTATION_SOP.md is missing.' });
+        issues.push({
+            severity: 'error',
+            code: 'INIT_SOP_MISSING',
+            path: 'docs/IMPLEMENTATION_SOP.md',
+            message: 'Legacy SOP Required Reading cannot be updated because IMPLEMENTATION_SOP.md is missing. In 0.4 projects, use `hadara docs register` to write .hadara/docs-registry.json metadata instead.'
+        });
         return { ok: false, actions, issues };
     }
     if (!input.allowMissingDocument && !node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, input.relativePath))) {
@@ -456,10 +636,11 @@ function createSopRowUpdatePlan(projectRoot, input) {
     };
 }
 const CANONICAL_TABLE_HEADERS = {
-    'AGENTS.md': ['| Order | Document | When | Purpose |', '| Rule | Requirement | Evidence / Update Location |'],
+    'AGENTS.md': ['| Document | When to Read | Purpose |'],
     'docs/PROJECT_STATE.md': ['| Field | Value |', '| Area | Status | Notes |', '| Source | Path | Purpose |'],
     'docs/AGENT_HANDOFF.md': ['| Area | State | Notes |', '| Task | Summary | Evidence |', '| Issue | Impact | Next Step |', '| Step | Reason | Done Evidence |', '| Check | Latest Evidence | Notes |', '| History Type | Path | When to Use |'],
     'docs/TASK_BOARD.md': ['| ID | Title | Status | Capsule | Notes |'],
+    'docs/HADARA_WORKFLOW.md': ['| Order | Authority | Allowed Reads |', '| Gate | Required State |', '| Timing | Update |', '| Situation | Use | Notes |', '| Surface | Human / Operator | Agent | CLI |'],
     'docs/IMPLEMENTATION_SOP.md': ['| Document | When to Read | Purpose |', '| Profile | Scale | Generated Docs | Intended Use | Special Notes |', '| Document | Required Structure |'],
     'docs/TASK_WORKFLOW_COMMANDS.md': ['| Command | Default Write Behavior | Notes |'],
     'docs/ARCHITECTURE.md': ['| Field | Value |', '| Boundary | Rule | Notes |', '| Component | Path / Surface | Responsibility | Status |'],
@@ -696,21 +877,21 @@ function detectProfileMetadataMismatches(projectRoot) {
     return issues;
 }
 function inferProfileFromGeneratedDocs(projectRoot) {
-    if (['docs/SECURITY_MODEL.md', 'docs/REFACTOR_LOG.md', 'docs/ROADMAP.md'].some((relativePath) => node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath)))) {
+    if (['docs/SECURITY_MODEL.md', 'docs/AGENT_HANDOFF.md'].some((relativePath) => node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath)))) {
         return 'governed';
     }
-    if (['docs/ARCHITECTURE.md', 'docs/DEVELOPMENT_SLICES.md', 'docs/DECISIONS.md', 'docs/TEST_STRATEGY.md'].some((relativePath) => node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath)))) {
+    if (['docs/ARCHITECTURE.md', 'docs/DECISIONS.md', 'docs/ROADMAP.md'].some((relativePath) => node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath)))) {
         return 'standard';
     }
     return 'basic';
 }
 function requiredDocsForProfile(profile) {
-    const docs = ['docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/TASK_WORKFLOW_COMMANDS.md'];
+    const docs = ['docs/PROJECT_STATE.md', 'docs/TASK_BOARD.md', 'docs/HADARA_WORKFLOW.md'];
     if (profile === 'standard' || profile === 'governed') {
-        docs.push('docs/ARCHITECTURE.md', 'docs/DEVELOPMENT_SLICES.md', 'docs/DECISIONS.md', 'docs/TEST_STRATEGY.md');
+        docs.push('docs/ARCHITECTURE.md', 'docs/DECISIONS.md', 'docs/ROADMAP.md');
     }
     if (profile === 'governed') {
-        docs.push('docs/SECURITY_MODEL.md', 'docs/ROADMAP.md');
+        docs.push('docs/AGENT_HANDOFF.md', 'docs/SECURITY_MODEL.md');
     }
     return docs;
 }
@@ -755,6 +936,339 @@ function parseIntegration(value) {
         return value;
     throw new Error(`unsupported init integration: ${value}; expected hermes or mcp`);
 }
+function createScaffoldJson(profile) {
+    return `${JSON.stringify({
+        schemaVersion: 'hadara.projectScaffold.v1',
+        hadaraProtocol: '0.4',
+        profile,
+        taskCapsuleSchema: 'hadara.taskCapsule.v1',
+        docsRegistrySchema: 'hadara.docsRegistry.v2',
+        managedSlotSchema: 'hadara.managedSlot.v2',
+        createdWith: 'hadara@0.4.0',
+        docsRegistryPath: '.hadara/docs-registry.json',
+        slotRegistryPath: '.hadara/slot-registry.json'
+    }, null, 2)}\n`;
+}
+function createSlotRegistryJson() {
+    return `${JSON.stringify({
+        schemaVersion: 'hadara.managedSlot.registry.v1',
+        registryVersion: 1,
+        slots: [
+            {
+                id: 'task.identity',
+                schemaVersion: 'hadara.managedSlot.v2',
+                owner: 'task.lifecycle',
+                allowedPaths: ['tasks/*/TASK.md'],
+                closeSourceRole: 'included',
+                kind: 'key-value-table',
+                fields: [
+                    { name: 'ID', required: true, editable: 'cli-only', pattern: '^T-[0-9]{4,}$' },
+                    { name: 'Title', required: true, editable: 'cli-on-create' },
+                    { name: 'Status', required: true, editable: 'lifecycle-or-constrained-md', allowedValues: ['Draft', 'In Progress', 'Blocked', 'Done', 'Partial', 'Superseded', 'Archived'] },
+                    { name: 'Created', required: true, editable: 'cli-only', pattern: '^\\\\d{4}-\\\\d{2}-\\\\d{2}$' },
+                    { name: 'Updated', required: true, editable: 'cli-or-managed', pattern: '^\\\\d{4}-\\\\d{2}-\\\\d{2}$' }
+                ]
+            }
+        ],
+        tableSchemas: [
+            {
+                id: 'task.acceptance',
+                kind: 'markdown-table',
+                allowedPaths: ['tasks/*/TASK.md'],
+                closeSourceRole: 'included',
+                columns: [
+                    { name: 'ID', pattern: '^AC-[0-9]+$', required: true },
+                    { name: 'Criterion', editable: 'agent-derived-prose', required: true },
+                    { name: 'Required', allowedValues: ['Yes', 'No'], required: true },
+                    { name: 'Status', allowedValues: ['Pending', 'Met', 'Not Met', 'Blocked', 'Not Applicable'], required: true },
+                    { name: 'Evidence', pattern: '^(TBD|ev:.*|)$', required: false },
+                    { name: 'Disposition', allowedValues: ['Required', 'Optional', 'Deferred', 'Accepted Risk', 'Not Applicable', 'Superseded'], required: true },
+                    { name: 'Reference', requiredWhenDispositionIn: ['Deferred', 'Accepted Risk', 'Superseded'] }
+                ]
+            }
+        ]
+    }, null, 2)}\n`;
+}
+function createHadaraWorkflowDoc() {
+    return `# HADARA_WORKFLOW
+
+## Purpose
+
+This document explains when to use HADARA CLI surfaces and when to update HADARA documents during normal project work.
+
+Use HADARA read models first. Do not manually read broad project files unless a HADARA command points you there or the task explicitly requires it.
+
+## Quickstart
+
+Use this section for the first pass through a new scaffold. Read the detailed sections below only when you reach that situation.
+
+| Situation | First Action |
+|---|---|
+| New project created | Read \`AGENTS.md\`, then \`.hadara/context/HADARA_CONTEXT.md\`, then this Quickstart. |
+| Need work to do | Run \`hadara task status --json\`. |
+| Need a task | Run \`hadara task create "task title" --json\`, then fill \`TASK.md\` Goal, Source Documents, Plan, and Acceptance. |
+| Need files to inspect | Run \`hadara session start --task T-XXXX --json\` or \`hadara context pack --task T-XXXX --json\`, then read only routed files. |
+| Ready to close | Run \`hadara task finalize --task T-XXXX --json\`, inspect the plan hash, then execute finalize with that hash. |
+
+## Minimal Loop
+
+\`\`\`text
+1. \`hadara task status --json\`
+2. \`hadara session start --task T-XXXX --json\` when resuming or changing tasks
+3. \`hadara task create "task title" --json\` only when no suitable capsule exists
+4. update \`TASK.md\`
+5. implement the scoped change
+6. run real validation
+7. record evidence
+8. update task/global docs
+9. review \`task finalize --json\`
+10. execute finalize only with the reviewed plan hash
+\`\`\`
+
+## Read Authority Rules
+
+Agents must follow this read order:
+
+| Order | Authority | Allowed Reads |
+|---:|---|---|
+| 1 | HADARA CLI read models | \`session start\`, \`task status\`, \`context pack\`, docs registry/read-map reports. |
+| 2 | Command-returned paths | Files, ranges, candidates, or docs explicitly returned by those read models. |
+| 3 | Active Task Capsule | \`TASK.md\`, \`HANDOFF.md\`, \`EVIDENCE.md\`, and task-local evidence summaries for the selected task. |
+| 4 | Shared state docs | Only when Required Reading says every session, or when a read model/task explicitly references them. |
+| 5 | Conditional reference docs | Only when the task, registry, read-map, or source document table points to them. |
+
+Agents must not scan the repository, open unrelated docs, or infer current state from directory structure when a HADARA read model can route the read.
+
+## Project Start
+
+Use \`hadara init\` only when creating a new HADARA project or initializing HADARA in an existing project that is not already governed by another HADARA protocol.
+
+\`\`\`bash
+hadara init --json
+hadara init --profile basic --json
+hadara init --profile standard --json
+hadara init --profile governed --json
+hadara init doctor --json
+\`\`\`
+
+After init, review:
+
+| Step | Document | Purpose |
+|---|---|---|
+| 1 | \`AGENTS.md\` | Entry rules and required reading. |
+| 2 | \`.hadara/context/HADARA_CONTEXT.md\` | Compact read routing. |
+| 3 | \`docs/PROJECT_STATE.md\` | Initial project state and next recommended step. |
+| 4 | \`docs/TASK_BOARD.md\` | Task index. |
+| 5 | \`docs/HADARA_WORKFLOW.md\` | How to work with HADARA from this point forward. |
+
+Use project-specific docs only after they are created and routed through the docs registry, a read-map, or the active task.
+
+## Session Start
+
+Use session start at the beginning of a work session, after switching tasks, or when project state is unclear.
+
+\`\`\`bash
+hadara session start --json
+hadara session start --task T-XXXX --json
+\`\`\`
+
+Session start is a read model. It does not create tasks, append evidence, warm caches, validate completion, or close work.
+
+## Selecting or Creating Work
+
+\`\`\`bash
+hadara task status --json
+hadara task create "task title" --json
+hadara task status --task T-XXXX --json
+\`\`\`
+
+Use \`task status --json\` to decide what to work on when no task is selected. Use \`task create\` only when no suitable capsule exists. Use \`task status --task T-XXXX --json\` as a fast selected-task loop cockpit for evidence, loop phase, and suggested next actions. Use \`task finalize --task T-XXXX --json\` or \`task status --task T-XXXX --detail full --json\` when you need close-grade readiness diagnostics.
+
+## Task Context
+
+\`\`\`bash
+hadara context pack --task T-XXXX --json
+\`\`\`
+
+Use context pack when starting implementation, resuming after a gap, deciding which files to inspect, or avoiding broad manual repo reads. Context pack is reading guidance, not validation.
+
+After context pack:
+
+1. Select only relevant files or candidates from the report.
+2. Use \`context slice\` for exact source reads when a range/candidate is available.
+3. Add or update \`TASK.md\` Source Documents for sources that constrain the work.
+
+## Exact Source Slices
+
+\`\`\`bash
+hadara context slice --path <path> --from <line> --to <line> --json
+hadara context slice --task T-XXXX --candidate <candidate-id> --json
+\`\`\`
+
+Use context slice only after a read model points to a specific file or range.
+
+## Task Capsule Lifecycle
+
+The normal task lifecycle is:
+
+\`\`\`text
+select or create task
+read task context
+author task contract
+do scoped work
+record evidence
+finish task docs and shared state
+review finalize plan
+execute finalize with the reviewed plan hash
+stop when finalize returns closed-valid
+\`\`\`
+
+Use the high-level lifecycle path for ordinary work:
+
+\`\`\`bash
+hadara task status --task T-XXXX --json
+hadara task finalize --task T-XXXX --json
+hadara task finalize --task T-XXXX --execute --plan-hash sha256:... --json
+\`\`\`
+
+Low-level lifecycle commands are for debugging, recovery, or command implementation work:
+
+\`\`\`bash
+hadara task finish --task T-XXXX --json
+hadara task ready --task T-XXXX --level done --json
+hadara task close --task T-XXXX --json
+\`\`\`
+
+## Finalize Entry Gate
+
+Before running \`hadara task finalize\`, all of these must be true:
+
+| Gate | Required State |
+|---|---|
+| Goal | \`TASK.md\` has a concrete task goal. |
+| Source Documents | Relevant sources are listed, or the task explicitly records that none are required. |
+| Plan | \`TASK.md\` Plan has the intended work steps. |
+| Acceptance | \`TASK.md\` Acceptance has the completion criteria. |
+| Validation | At least one validation method is defined, or a documented reason explains why validation is not applicable. |
+
+Do not use status/finalize to avoid authoring the task contract.
+
+## Task Document Timing
+
+HADARA 0.4 Task Capsules contain \`TASK.md\`, \`HANDOFF.md\`, \`EVIDENCE.md\`, and \`evidence.jsonl\`.
+
+| Timing | Update |
+|---|---|
+| Capsule created | Start \`TASK.md\` Goal, Source Documents, Plan, and Acceptance. |
+| Before execution | Refine \`TASK.md\` Plan, Source Documents, and Acceptance. |
+| During execution | Update \`TASK.md\` Plan, Change Summary, Risks / Follow-ups; update \`HANDOFF.md\` warnings if continuity changes. |
+| After validation | Use \`validation run\` when possible; record evidence, then update \`TASK.md\` Validation and Acceptance deliberately with evidence ids or residual notes. |
+| Before finalize dry-run | Finish \`TASK.md\` Change Summary, Acceptance, Validation, Risks / Follow-ups; update \`HANDOFF.md\`; update shared state docs when the task changed them. |
+| Finalize review | Inspect \`task finalize --json\` dry-run output and fix reported blockers before execute. |
+| Finalize execute | Do not edit close-source docs during execute. |
+| After close | Only clarify docs if the task contract did not change; rerun finalize after close-source edits. |
+
+Do not hand-edit \`evidence.jsonl\`. Treat \`EVIDENCE.md\` as a CLI-generated projection file.
+
+## Evidence
+
+\`\`\`bash
+hadara validation run --task T-XXXX --check "Focused tests" -- npm test
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --category validation --json
+hadara evidence summary --task T-XXXX --json
+hadara evidence project --task T-XXXX --json
+\`\`\`
+
+Use \`validation run\` for ordinary validation because it executes the command, records durable evidence from the real exit status, and refreshes \`EVIDENCE.md\`. Add \`--update-task\` only when you intentionally want the matching \`TASK.md\` Validation row updated by the CLI.
+
+Use \`evidence add-command\` only when recording an already-run result supplied by the operator. It does not execute shell commands. Use \`evidence summary\` to find durable evidence ids for docs and resolution markers.
+
+Evidence must reflect real execution results. Fabricated or assumed results are invalid.
+
+\`evidence project\` is the 0.4 projection refresh surface. It refreshes the generated \`EVIDENCE.md\` projection file without rewriting canonical evidence.
+
+## Repair and Diagnostics
+
+\`\`\`bash
+hadara task audit-close --task T-XXXX --json
+hadara harness validate --task T-XXXX --level done --json
+hadara init doctor --json
+\`\`\`
+
+Use finalize dry-run as the ordinary close-proof repair plan. Use diagnostics when finalize reports blockers. Do not repair close proof by editing evidence files by hand.
+
+Agents must not run \`task finalize --execute\` without inspecting the dry-run output and using the current \`planHash\` from that reviewed dry-run.
+
+## Useful CLI by Situation
+
+| Situation | Use | Notes |
+|---|---|---|
+| New HADARA project | \`hadara init --profile <profile> --json\` | Creates scaffold docs and registries. |
+| Check scaffold health | \`hadara init doctor --json\` | Reports missing or inconsistent scaffold files. |
+| Find next work | \`hadara task status --json\` | Read-only selection cockpit. |
+| Inspect selected task | \`hadara task status --task T-XXXX --json\` | Fast loop phase and next-action projection. |
+| Inspect close-grade diagnostics | \`hadara task status --task T-XXXX --detail full --json\` | Heavier readiness/protocol projection for explicit diagnostics. |
+| Find task-specific context | \`hadara context pack --task T-XXXX --json\` | Use before broad manual reads. |
+| Read exact source text | \`hadara context slice ... --json\` | Use after a context candidate points to a range. |
+| Run and record validation | \`hadara validation run --task T-XXXX --check "..." -- <command>\` | Executes the command and records evidence without editing \`TASK.md\` by default. |
+| Run, record, and sync task row | \`hadara validation run --task T-XXXX --check "..." --update-task -- <command>\` | Executes the command, records evidence, and updates the matching \`TASK.md\` Validation row. |
+| Record already-run validation | \`hadara evidence add-command ... --json\` | Append-only evidence writer; does not execute commands. |
+| Find evidence ids | \`hadara evidence summary --task T-XXXX --json\` | Compact copy hints. |
+| Review loop phase | \`hadara task status --task T-XXXX --json\` | Normal lifecycle state and next action. |
+| Close ordinary work | \`hadara task finalize --task T-XXXX --json\` then execute with its \`planHash\` | Default close path. |
+| Repair close drift | \`hadara task finalize --task T-XXXX --json\` then execute with its \`planHash\` | Default repair path for stale close proof. |
+| Register project-specific docs | \`hadara docs register --path <path> --json\` | 0.4 registry surface. Canonical state belongs in \`.hadara/docs-registry.json\`; use registry-backed help for exact options. |
+| Discover command details | \`hadara help lifecycle\`, \`hadara help command <id>\`, \`hadara commands --json\` | Prefer registry-backed help over copied command tables. |
+
+## Common Failure Modes
+
+| Failure Mode | Correct Behavior |
+|---|---|
+| Skipping read models and scanning the repository. | Start with session/task/context read models and only open routed files. |
+| Opening unrelated specs or historical docs. | Use read tiers, registry metadata, and context pack candidates. |
+| Running lifecycle before \`TASK.md\` is authored. | Satisfy the Lifecycle Entry Gate first. |
+| Treating context pack as validation. | Use it only for read guidance; run real checks separately. |
+| Recording evidence for checks that were not run. | Record only real execution results, including failed or blocked checks. |
+| Running finalize execute from memory. | Review fresh dry-run output and copy its current plan hash. |
+| Putting same-capsule chores in \`HANDOFF.md\` Next Recommended Step. | Use that section for next capsule or global-state recommendations. |
+
+## Design Source Documents and Read Maps
+
+Design source documents may live under \`docs/specs/**\` or other registered paths. Use registry/read-map output to decide whether they are active, conditional, implemented, drift-risk, historical, or excluded.
+
+Do not treat every file under \`docs/specs/**\` as default Required Reading.
+
+Document registration writes registry metadata, not prose rows in entry docs. Do not append project-specific document rows to \`AGENTS.md\`, \`.hadara/context/HADARA_CONTEXT.md\`, or this workflow document.
+
+## Authoring Model
+
+| Surface | Human / Operator | Agent | CLI |
+|---|---|---|---|
+| Requirements and source docs | Provides and approves | Summarizes into task docs | Indexes/read-map only |
+| \`TASK.md\` identity | Reviews | Does not hand-edit CLI-owned fields | Creates and lifecycle-updates |
+| \`TASK.md\` prose/tables | Reviews | Authors goal, source documents, plan, acceptance, validation, change summary, risks, and follow-ups | Validates controlled values |
+| \`HANDOFF.md\` | Reviews | Writes continuation guidance | May suggest or project summaries |
+| \`evidence.jsonl\` | Supplies command result facts | Does not hand-edit | Appends canonical evidence |
+| \`EVIDENCE.md\` | Reads | Does not hand-edit generated projection | Regenerates projection file |
+| Close proof | Reviews | Does not write by hand | Appends proof and audits freshness |
+
+## Automatic Writing Boundary
+
+HADARA auto-writes deterministic state, managed slots, indexes, evidence projections, and close snapshots. It reports read-only guidance for missing task prose.
+
+Agents write task-specific goal, source documents, plan, acceptance, validation, change summary, risks, follow-ups, and handoff guidance from user requirements and source documents.
+
+## Drift Avoidance
+
+Do not duplicate command registry metadata. For detailed options, point to registry-backed help:
+
+\`\`\`bash
+hadara help lifecycle
+hadara help command <id>
+hadara commands --json
+\`\`\`
+`;
+}
 function createHermesIntegrationDoc() {
     return `# Hermes Integration
 
@@ -795,6 +1309,9 @@ function createMcpIntegrationDoc() {
 `;
 }
 function createProjectStateDoc(profile) {
+    const handoffRow = profile === 'governed'
+        ? '| Next-session handoff | `docs/AGENT_HANDOFF.md` | Compact continuation state. |\n'
+        : '';
     const productTable = (0, managed_sections_1.managedSectionBlock)('project-state-metadata', {
         schema: 'hadara.managedSection.v1',
         owner: 'project-state.update',
@@ -836,7 +1353,7 @@ ${productTable}
 |---|---|---|
 | Current state | \`docs/PROJECT_STATE.md\` | Product and capability state. |
 | Work queue | \`docs/TASK_BOARD.md\` | Task status and queue. |
-| Next-session handoff | \`docs/AGENT_HANDOFF.md\` | Compact continuation state. |
+${handoffRow}| Workflow | \`docs/HADARA_WORKFLOW.md\` | Generic HADARA lifecycle and evidence rules. |
 | Task details | \`tasks/T-*/\` | Task-local evidence and decisions. |
 `;
 }
@@ -869,7 +1386,7 @@ function createAgentHandoffDoc() {
     }, `| Area | State | Notes |
 |---|---|---|
 | Scaffold | Initialized | HADARA protocol scaffold is initialized. |
-| Required Reading | Pending | Read \`PROJECT_STATE\`, \`AGENT_HANDOFF\`, \`TASK_BOARD\`, \`IMPLEMENTATION_SOP\`, and \`TASK_WORKFLOW_COMMANDS\` before starting. |
+| Required Reading | Pending | Read \`PROJECT_STATE\`, \`AGENT_HANDOFF\`, \`TASK_BOARD\`, and \`HADARA_WORKFLOW\` before starting. |
 `);
     return `# AGENT_HANDOFF
 
@@ -930,7 +1447,7 @@ function createArchitectureDoc(profile) {
 |---|---|---|---|
 | Task Capsules | \`tasks/T-*/\` | Task-local scope, evidence, decisions, and handoff. | Active |
 | Evidence records | \`EVIDENCE.md\`, \`evidence.jsonl\` | Validation evidence and artifact references. | Active |
-| Handoff | \`docs/AGENT_HANDOFF.md\` | Next-session continuation state. | Active |
+| Handoff | \`docs/PROJECT_STATE.md\` or \`docs/AGENT_HANDOFF.md\` | Next-session continuation state. | Active |
 `;
 }
 function createImplementationSopDoc(spec) {
@@ -976,7 +1493,7 @@ function createImplementationSopDoc(spec) {
     if (spec.docs.roadmap) {
         requiredReadingRows.push(['`docs/ROADMAP.md`', 'Roadmap, milestone, release, or scope planning', 'Longer-term priorities and deferred work.']);
     }
-    requiredReadingRows.push(['Active `tasks/T-*/TASK.md`', 'Working a task', 'Task-specific goal, scope, and status.'], ['Active Task Capsule docs', 'Working a task', '`DECISIONS.md`, `PLAN.md`, `CONTEXT.md`, `ACCEPTANCE.md`, `FILES.md`, `TESTS.md`, `RISKS.md`, and `HANDOFF.md`.']);
+    requiredReadingRows.push(['Active `tasks/T-*/TASK.md`', 'Working a task', 'Task-specific goal, scope, and status.'], ['Active Task Capsule docs', 'Working a task', '`TASK.md`, `HANDOFF.md`, `EVIDENCE.md`, and task-local evidence summaries.']);
     const requiredReadingTable = (0, managed_sections_1.managedSectionBlock)('required-reading', {
         schema: 'hadara.managedSection.v1',
         owner: 'init.register-doc',
@@ -1100,21 +1617,23 @@ Use distinct token families for persistent task state, close proof state, docume
 
 \`DocStatus\` belongs only to the docs registry and uses \`canonical\`, \`active\`, \`reference\`, \`historical\`, \`superseded\`, and \`archived\`. Evidence outcomes are \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`; preserve failed or blocked evidence and append newer corrective evidence instead of rewriting history.
 
-Ownership boundaries follow the lifecycle command model. \`task finalize --execute --plan-hash <hash>\` is the default 0.3.3 agent close path and preserves the underlying write boundaries: \`task finish --execute\` owns bounded status bookkeeping in \`TASK.md\` and command-owned \`docs/TASK_BOARD.md\` cells, and \`task close --execute\` owns only close evidence append. Operators own close-source prose and shared state docs before finalize execute, then rerun finalize or the low-level ready/close/audit sequence after any intentional close-source edit.
+Ownership boundaries follow the lifecycle command model. \`task finalize --execute --plan-hash <hash>\` is the default 0.3.3 agent close and close-proof repair path and preserves the underlying write boundaries: \`task finish --execute\` owns bounded status bookkeeping in \`TASK.md\` and command-owned \`docs/TASK_BOARD.md\` cells, and close execution owns only close evidence append. Operators own close-source prose and shared state docs before finalize execute, then rerun finalize after any intentional close-source edit.
 
 ## 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.4 onward, agents should start from \`task status\`, then use finalize for closure instead of starting with low-level proof-boundary commands:
 
 \`\`\`bash
-hadara task next --json
+hadara task status --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.
 
@@ -1122,29 +1641,27 @@ hadara evidence add-command --task T-XXXX --summary "..." --result passed --cate
 
 # Finalize Task Capsule docs and tracked state docs before closing.
 
-hadara task lifecycle --task T-XXXX --json
 hadara task finalize --task T-XXXX --json
 hadara task finalize --task T-XXXX --execute --plan-hash sha256:... --json
 \`\`\`
 
 | Command | Default Write Behavior | Notes |
 |---|---|---|
-| \`task next\` | Read-only | Recommends work; does not create tasks. |
-| \`task status\` | Read-only | \`ok\` means report generation succeeded; readiness is in \`state.ready\`, \`summary.blockers\`, and \`issues\`. |
+| \`task status\` | Read-only | Without \`--task\`, selects next work. With \`--task\`, default output is a fast loop cockpit; use \`--detail full\` or \`task finalize\` for close-grade readiness diagnostics. |
+| \`task next\` | Read-only compatibility | Planned removal candidate; prefer \`task status --json\`. |
 | \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands; optional \`--category\`/\`--outcome\`/\`--resolves\`/\`--supersedes\` enrich v2 metadata, result/outcome mismatches are rejected, and optional \`--idempotency-key\` prevents duplicate same-key records. |
-| \`task lifecycle\` | Read-only | Reports normalized lifecycle phase, checks, blockers, and one next action. |
-| \`task close-repair-plan\` | Read-only | Classifies close proof repair state and exact repair command. |
+| \`task lifecycle\` | Read-only compatibility | Planned removal candidate; prefer \`task status --task T-XXXX --json\`. |
 | \`task finalize\` | Read-only by default; guarded execute requires \`--plan-hash\` | Default agent close path. Rechecks the current plan hash, executes phases serially, stops on blockers, and preserves finish/close write boundaries. |
 | \`task finish\` / \`task ready\` / \`task close\` / \`task audit-close\` | Low-level proof-boundary commands | Use directly for debugging, recovery, or command implementation work. |
 
-Before running \`task finalize --execute\`, finish all close-source edits: Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, \`docs/TASK_BOARD.md\`, and tracked state docs such as \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when they apply. After finalize closes the task, do not edit those close-source documents unless you intend to rerun finalize or the low-level \`task ready\`, \`task close\`, and \`task audit-close\` sequence. Avoid writing volatile close evidence ids into close-source docs; use stable wording such as "close evidence appended; audit returned closed-valid".
+Before running \`task finalize --execute\`, finish all close-source edits: Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, \`docs/TASK_BOARD.md\`, and tracked state docs such as \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when they apply. After finalize closes the task, do not edit those close-source documents unless you intend to rerun finalize and execute its fresh repair plan. Avoid writing volatile close evidence ids into close-source docs; use stable wording such as "close evidence appended; audit returned closed-valid".
 
 ## Validation
 
 1. Run relevant tests.
 2. Record meaningful evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
 3. Finalize Task Capsule docs and tracked state docs before close so the close source hash remains stable.
-4. Run \`hadara task lifecycle --task <task-id> --json\` when you need a compact phase check.
+4. Run \`hadara task status --task <task-id> --json\` when you need a compact phase check or next action.
 5. Run \`hadara task finalize --task <task-id> --json\`, review the current plan hash and write boundaries, then execute \`hadara task finalize --task <task-id> --execute --plan-hash <hash> --json\`.
 6. Use low-level \`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` only when debugging or repairing one proof boundary directly.
 7. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
@@ -1266,7 +1783,7 @@ function createTestStrategyDoc() {
 | 1 | Run the relevant suite from the table above. | Task Capsule \`EVIDENCE.md\` |
 | 2 | Record meaningful evidence in the Task Capsule. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
 | 3 | Finalize Task Capsule docs and tracked state docs before close. | Task Capsule docs and tracked state docs |
-| 4 | Run \`hadara task lifecycle --task <task-id> --json\` when you need a compact phase check. | Task Capsule docs and evidence |
+| 4 | Run \`hadara task status --task <task-id> --json\` when you need a compact phase check or next action. | Task Capsule docs and evidence |
 | 5 | Run \`hadara task finalize --task <task-id> --json\`, review the plan hash, then execute \`hadara task finalize --task <task-id> --execute --plan-hash <hash> --json\`. | Task Capsule close evidence |
 | 6 | Use low-level \`task finish\`, \`task ready\`, \`task close\`, and \`task audit-close\` only when debugging or repairing one proof boundary directly. | Task Capsule evidence |
 
@@ -1315,17 +1832,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.4 onward, agents should use the status-first finalize loop for ordinary implementation capsules:
 
 \`\`\`bash
-hadara task next --json
+hadara task status --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.
 
@@ -1333,7 +1852,6 @@ hadara evidence add-command --task T-XXXX --summary "..." --result passed --cate
 
 # Finalize Task Capsule docs and tracked state docs before closing.
 
-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
 \`\`\`
@@ -1433,15 +1951,14 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 
 | Command | Default Write Behavior | Notes |
 |---|---|---|
-| \`task next\` | Read-only | Recommends work; does not create tasks. |
-| \`task status\` | Read-only | \`ok\` means report generation succeeded; readiness is in \`state.ready\`, \`summary.blockers\`, and \`issues\`. |
+| \`task status\` | Read-only | Without \`--task\`, selects next work. With \`--task\`, default output is a fast loop cockpit; use \`--detail full\` or \`task finalize\` for close-grade readiness diagnostics. |
+| \`task next\` | Read-only compatibility | Planned removal candidate; prefer \`task status --json\`. |
 | \`task create\` | Write | Creates a Draft Task Capsule and Task Board row. It does not imply the task is ready or done. |
 | \`evidence add-command\` | Write | Appends operator-supplied command-log evidence. It does not execute shell commands or capture stdout/stderr; optional \`--category\`/\`--outcome\`/\`--resolves\`/\`--supersedes\` enrich v2 metadata, result/outcome mismatches are rejected, and optional \`--idempotency-key\` prevents duplicate same-key records. |
-| \`task lifecycle\` | Read-only | Reports normalized lifecycle phase, checks, blockers, repair metadata, and one next action. |
-| \`task close-repair-plan\` | Read-only | Classifies close proof repair state and exact repair command. |
+| \`task lifecycle\` | Read-only compatibility | Planned removal candidate; prefer \`task status --task T-XXXX --json\`. |
 | \`task finalize\` | Read-only by default; guarded execute requires \`--plan-hash\` | Default agent close path. Rechecks the current plan hash, executes phases serially, stops on blockers, and succeeds only after final audit is \`closed-valid\`. |
 | \`task finish\` / \`task ready\` / \`task close\` / \`task audit-close\` | Low-level proof-boundary commands | Use directly for debugging, recovery, or command implementation work. |
-| \`task complete\` | Legacy read-only workflow compressor | Summarizes the current completion stage and next command; prefer \`task lifecycle\` and \`task finalize\` for 0.3.3 agent flows. |
+| \`task complete\` | Legacy read-only workflow compressor | Summarizes the current completion stage and next command; prefer \`task status\` and \`task finalize\` for current agent flows. |
 
 ## Non-Overlap Rules
 
@@ -1451,8 +1968,7 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 - \`harness validate\` is a direct diagnostic for Task Capsule structure and done-level gates; it is not a replacement for close evidence.
 - \`task complete\` is a legacy read-only workflow compressor. It may report the next lifecycle command, but it must not execute finish, ready, close, or audit commands. Prefer \`task lifecycle\` and \`task finalize\` for 0.3.3 agent flows.
 - \`task lifecycle\` is the read-only normalized phase API for agents.
-- \`task close-repair-plan\` is a read-only close-proof repair classifier.
-- \`task finalize\` is read-only by default. Guarded execute requires a matching current dry-run \`planHash\`, runs phases serially, stops on blockers, and returns success only after \`task audit-close\` is \`closed-valid\`.
+- \`task finalize\` is read-only by default and owns close-proof repair planning. Guarded execute requires a matching current dry-run \`planHash\`, runs phases serially, stops on blockers, and returns success only after the final audit is \`closed-valid\`.
 - \`evidence list\` is the supported evidence id discovery surface. Text output shows \`[id] time | category/outcome | visibility | summary\`; JSON records expose \`id\`, \`idSource\`, \`idStability\`, \`persistedSchemaVersion\`, \`category\`, \`outcome\`, and \`tags\`. Use durable persisted \`ev:\` ids for long-lived \`--resolves\` and \`--supersedes\` references. Legacy compatibility ids are inspection-only and are not the preferred durable reference.
 - \`evidence add-command\` records an operator-supplied command result; it does not run the command. \`--category\` and \`--outcome\` set persisted v2 metadata explicitly, while \`--result\` remains the legacy-compatible command result. When both are supplied, \`--result\` must match \`--outcome\` for \`passed\`, \`failed\`, \`blocked\`, and \`unknown\`; \`recorded\` and \`not-applicable\` require \`--result unknown\` or no explicit \`--result\`. \`--resolves\` and \`--supersedes\` append exact v2 resolution tags from passed or recorded follow-up evidence. \`--idempotency-key\` is optional; when supplied, same-key repeats return the existing record without appending duplicate Markdown or JSONL rows.
 - Evidence v2 deferred scope remains explicit: rebuild preview/execute, \`check-id\`, \`subject\`, and a new add-command report schema id are future candidates. Do not infer those commands or schema changes from the current \`evidence list\` and \`evidence add-command\` ergonomics.
@@ -1468,77 +1984,65 @@ Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board
 }
 function createAgentsDoc(spec) {
     const requiredReadingRows = [
-        ['1', '`.hadara/context/HADARA_CONTEXT.md`', 'Every session', 'Compact project-local context anchor and read routing.'],
-        ['2', '`docs/PROJECT_STATE.md`', 'Every session', 'Current product and capability state.'],
-        ['3', '`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact continuation state.'],
-        ['4', '`docs/TASK_BOARD.md`', 'Every session', 'Current task queue and status.'],
-        ['5', '`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local workflow and required-reading registry.'],
-        ['6', '`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
+        ['`.hadara/context/HADARA_CONTEXT.md`', 'Every session', 'Compact project-local context anchor and read-routing guide.'],
+        ['`docs/PROJECT_STATE.md`', 'Every session', 'Current state, active work, known problems, and next recommended step.'],
+        ['`docs/TASK_BOARD.md`', 'Every session', 'Task queue, task status, and capsule paths.'],
+        ['`docs/HADARA_WORKFLOW.md`', 'Every session; whenever using HADARA CLI workflow commands', 'Project start, task lifecycle, evidence, context, document timing, repair, and useful CLI guidance.']
     ];
-    let order = 7;
+    if (spec.docs.agentHandoff)
+        requiredReadingRows.push(['`docs/AGENT_HANDOFF.md`', 'When present in governed or long-running projects', 'Compact continuation handoff and current coordination notes.']);
     if (spec.docs.architecture)
-        requiredReadingRows.push([String(order++), '`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.']);
-    if (spec.docs.developmentSlices)
-        requiredReadingRows.push([String(order++), '`docs/DEVELOPMENT_SLICES.md`', 'Starting, completing, or reclassifying a development slice', 'Roadmap ordering, prerequisites, and completion evidence.']);
+        requiredReadingRows.push(['`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.']);
     if (spec.docs.decisions)
-        requiredReadingRows.push([String(order++), '`docs/DECISIONS.md`', 'Project-level decision work', 'Durable project decisions.']);
-    if (spec.docs.testStrategy)
-        requiredReadingRows.push([String(order++), '`docs/TEST_STRATEGY.md`', 'Validation planning or completion checks', 'Routine suites and special-case checks.']);
+        requiredReadingRows.push(['`docs/DECISIONS.md`', 'Project-level decision work', 'Durable project decisions.']);
     if (spec.docs.securityModel)
-        requiredReadingRows.push([String(order++), '`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants.']);
+        requiredReadingRows.push(['`docs/SECURITY_MODEL.md`', 'Security, secret, permission, or evidence-safety work', 'Project security invariants.']);
     if (spec.docs.roadmap)
-        requiredReadingRows.push([String(order++), '`docs/ROADMAP.md`', 'Roadmap, milestone, or scope planning', 'Longer-term priorities and deferred work.']);
-    requiredReadingRows.push([String(order++), 'Active `tasks/T-*/TASK.md`', 'Working a task', 'Task-specific goal, scope, and status.'], [String(order++), 'Active Task Capsule docs', 'Working a task', 'Decisions, plan, context, acceptance, files, tests, risks, handoff, and evidence.'], [String(order++), 'Project-specific registered docs', 'When listed in `docs/IMPLEMENTATION_SOP.md`', 'Specs, contracts, or roadmap files explicitly added by this project.']);
-    const trackedStateDocs = ['`docs/TASK_BOARD.md`', '`docs/PROJECT_STATE.md`', ...(spec.docs.developmentSlices ? ['`docs/DEVELOPMENT_SLICES.md`'] : [])];
-    const ruleRows = [
-        ['Task boundary', 'Keep work inside one Task Capsule whenever possible.', 'Active Task Capsule'],
-        ['Task creation', 'If no suitable capsule exists, create one with `hadara task create <title>`.', '`docs/TASK_BOARD.md`'],
-        ['Evidence', 'Do not mark work done without evidence. Do not hand-edit `evidence.jsonl`; record failed or blocked checks honestly instead of replacing them with optimistic summaries.', '`EVIDENCE.md`, `evidence.jsonl`'],
-        ['Documentation timing', 'Do not defer all documentation until after implementation; keep capsule docs current as work changes.', 'Task Capsule docs and shared state docs'],
-        ['Write coordination', 'Parallelize read-only discovery and independent validation; serialize evidence append, Task Capsule doc writes, shared state doc writes, before-hash executes, `task finalize --execute`, low-level finish/close executes, and release/publish operations.', 'Task Capsule evidence'],
-        ['Task workflow', 'For task workflow commands, follow `docs/TASK_WORKFLOW_COMMANDS.md`: from 0.3.3 onward, agents should use `task lifecycle` and reviewed `task finalize --json` / `task finalize --execute --plan-hash <hash>` as the default close path. Use `task finish`, `task ready`, `task close`, and `task audit-close` only as low-level proof-boundary commands for debugging, recovery, or command implementation work.', 'Task Capsule evidence'],
-        ['Safety', 'Do not execute dangerous commands without explicit user approval.', 'Task Capsule evidence'],
-        ['Secrets', 'Do not write secrets, private logs, or machine-local state into committed files.', 'Changed-file review'],
-        ['Store boundary', 'Preserve the portable/project store boundary.', spec.docs.architecture ? '`.gitignore`, `docs/ARCHITECTURE.md`' : '`.gitignore`'],
-        ['Validation', 'Follow validation constraints recorded in `docs/AGENT_HANDOFF.md` and the active Task Capsule.', 'Task Capsule evidence'],
-        ['Tracked state', `Update ${formatInlineList(trackedStateDocs)} when tracked state changes.`, 'Tracked docs'],
-        ['Handoff', 'Update `docs/AGENT_HANDOFF.md` before stopping.', '`docs/AGENT_HANDOFF.md`'],
-        ['Required reading', 'Register project-specific docs in `docs/IMPLEMENTATION_SOP.md` before expecting agents to rely on them.', '`docs/IMPLEMENTATION_SOP.md`']
-    ];
-    if (spec.docs.developmentSlices) {
-        ruleRows.push(['Slice order', 'Respect prerequisite order in `docs/DEVELOPMENT_SLICES.md`.', '`docs/DEVELOPMENT_SLICES.md`']);
-    }
+        requiredReadingRows.push(['`docs/ROADMAP.md`', 'Roadmap, milestone, or scope planning', 'Longer-term priorities and deferred work.']);
+    requiredReadingRows.push(['Active `tasks/T-*/TASK.md`', 'Every task-work session', 'Task scope, source documents, plan, acceptance, validation, and change summary.'], ['Active Task Capsule `HANDOFF.md` and `EVIDENCE.md`', 'Resuming, validating, finishing, or handing off a task', 'Continuation guidance and human-readable evidence projection.'], ['Project-specific docs referenced by the task, registry, or read-map', 'When referenced', 'Task-specific architecture, design, roadmap, validation, security, or integration constraints.']);
     return `# AGENTS
 
-This repository must be developed using the HADARA protocol.
+This repository uses the HADARA protocol for scoped, evidenced, resumable AI-assisted development.
 
 ## Required Reading
 
-| Order | Document | When | Purpose |
-|---|---|---|---|
+| Document | When to Read | Purpose |
+|---|---|---|
 ${requiredReadingRows.map(formatTableRow).join('\n')}
 
-\`docs/AGENT_HANDOFF.md\` is compact current-state handoff, not full project history. Follow its Historical Index when older completed-task or validation history is needed.
+\`AGENTS.md\` owns Required Reading. \`.hadara/context/HADARA_CONTEXT.md\` is a compact routing anchor that points to current-state and workflow documents; it is not a second Required Reading authority.
 
 ## Required Reading Tiers
 
-Use semantic tiers to keep session startup compact:
-
 | Tier | Meaning | Default Read Behavior |
 |---|---|---|
-| \`current-state\` | Compact docs that establish the live project state and route deeper reading. | Read first at session start or resume. |
-| \`task-work\` | Active Task Capsule docs and task workflow docs needed to safely perform lifecycle commands. | Read when selecting, implementing, finishing, closing, or auditing a task. |
-| \`conditional-reference\` | Architecture, security, roadmap, validation, release, or project-specific specs. | Read only when the task type or active capsule references them. |
-| \`historical\` | Completed-task history, older validation records, and previous-state detail. | Never default required reading; read only when investigating history. |
-| \`excluded\` | Superseded, archived, local-only, or intentionally non-default material. | Never default required reading unless explicitly reclassified. |
+| \`current-state\` | Compact docs that establish live project state and route deeper reading. | Read first at session start or resume. |
+| \`workflow\` | Shared HADARA workflow and command-use guidance. | Read before selecting, creating, implementing, finishing, closing, or auditing tasks. |
+| \`task-work\` | Active Task Capsule docs and task-local evidence/handoff surfaces. | Read when working inside a task. |
+| \`conditional-reference\` | Architecture, roadmap, decisions, validation, security, integration, or project-specific specs. | Read only when the task or read-map points to them. |
+| \`historical\` | Completed-task history and older validation records. | Do not read by default; use only when investigating history. |
+| \`excluded\` | Superseded, archived, local-only, or intentionally non-default material. | Do not read unless explicitly reclassified. |
 
-\`.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.
+## Operating Rules
 
-## Rules
+- Work inside one Task Capsule whenever possible.
+- If no suitable Task Capsule exists, create one through the HADARA workflow before implementation.
+- Prefer HADARA read models before broad manual file reading.
+- Keep committed state reproducible and project-local.
+- Do not write secrets, private logs, raw transcripts, credentials, or machine-local state into committed files.
+- Do not hand-edit canonical evidence logs.
+- Do not mark work done without evidence.
+- Keep Task Capsule docs current as work changes; do not defer all documentation until after implementation.
+- Do not execute destructive commands.
+- Do not run release, publish, package, installer, or other external mutation workflows without explicit operator approval.
 
-| Rule | Requirement | Evidence / Update Location |
-|---|---|---|
-${ruleRows.map(formatTableRow).join('\n')}
+## Workflow Reference
+
+Use \`docs/HADARA_WORKFLOW.md\` for project start, task lifecycle, context, evidence, document timing, repair, docs read-map, and useful CLI guidance.
+
+## Project Context
+
+Use \`.hadara/context/HADARA_CONTEXT.md\` as the compact project-local context anchor.
 `;
 }
 function formatInlineList(items) {