hadara 0.2.0-rc.1 → 0.2.0-rc.2

package/README.md

@@ -1,11 +1,11 @@
 # HADARA
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ictseoyoungmin/HADARA-dev/main/docs/assets/hadara_sub_right_name.png" alt="HADARA" width="720">
+  <img src="https://raw.githubusercontent.com/ictseoyoungmin/HADARA/main/docs/assets/hadara_sub_right_name.png" alt="HADARA" width="720">
 </p>
 
 <p align="center">
-  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.1-blue">
+  <img alt="Release candidate" src="https://img.shields.io/badge/release-0.2.0--rc.2-blue">
   <img alt="Node.js" src="https://img.shields.io/badge/node-%3E%3D22-brightgreen">
   <img alt="License" src="https://img.shields.io/badge/license-MIT-lightgrey">
 </p>
@@ -23,10 +23,10 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 The current source checkout targets:
 
 ```text
-hadara@0.2.0-rc.1
+hadara@0.2.0-rc.2
 ```
 
-T-0275 refreshes package smoke, clean-checkout smoke, release artifact, release dry-run, and publish dry-run evidence for `0.2.0-rc.1`. T-0269 prepared the previous `0.2.0-rc.0` publish path, but rc.1 supersedes it after the installed-package recycle fixes.
+T-0282 refreshes the npm release-candidate source state for `0.2.0-rc.2` after the init scaffold protocol guidance follow-up. T-0275 published the previous `0.2.0-rc.1` RC after the installed-package recycle fixes.
 
 Current publish boundaries:
 
@@ -35,10 +35,11 @@ Current publish boundaries:
 | npm package | Primary release target. |
 | `hadara@0.1.0-rc.0` | Published first RC. |
 | `hadara@0.2.0-rc.0` | Superseded internal publish candidate after recycle findings. |
-| `hadara@0.2.0-rc.1` | Current source and publish-candidate version. |
+| `hadara@0.2.0-rc.1` | Current published npm RC until rc.2 is operator-published. |
+| `hadara@0.2.0-rc.2` | Current source version and next npm RC target. |
 | GitHub Release | Secondary target, still approval-gated. |
 | Docker image | Deferred. |
-| PyPI/Python package | Advisory preview only. |
+| PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
 | Installer scripts / USB launchers | Deferred. |
 
 No release command should publish, create a GitHub Release, build Docker images, upload artifacts, or load token values unless an operator explicitly approves the mutation path for the active release capsule.
@@ -50,7 +51,7 @@ Requires Node.js 22.
 Install the current RC:
 
 ```bash
-npm install -g hadara@0.2.0-rc.1
+npm install -g hadara@0.2.0-rc.2
 hadara doctor --json
 hadara task list --json
 hadara tools list --json
@@ -59,11 +60,11 @@ hadara tools list --json
 Run without a global install:
 
 ```bash
-npx hadara@0.2.0-rc.1 doctor --json
-npx hadara@0.2.0-rc.1 tools list --json
+npx hadara@0.2.0-rc.2 doctor --json
+npx hadara@0.2.0-rc.2 tools list --json
 ```
 
-Previous published RC: `hadara@0.1.0-rc.0` remains available on npm for comparison or rollback, but new installs should use the current RC once it is published.
+Previous published RCs: `hadara@0.2.0-rc.1` and `hadara@0.1.0-rc.0` remain available on npm for comparison or rollback, but new installs should use the current RC after the operator publishes it.
 
 ## What HADARA Gives You
 
@@ -99,9 +100,9 @@ Task workflow:
 hadara task next --json
 hadara task create "implement a focused change" --json
 hadara task status --task T-0001 --json
-hadara task ready --task T-0001 --level done --json
 hadara task finish --task T-0001 --json
 hadara task finish --task T-0001 --execute --json
+hadara task ready --task T-0001 --level done --json
 hadara task close --task T-0001 --json
 hadara task close --task T-0001 --execute --json
 hadara task audit-close --task T-0001 --json
@@ -151,14 +152,17 @@ hadara task status --task T-XXXX --json
 # Do the scoped work.
 
 hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+
+hadara task finish --task T-XXXX --json
+hadara task finish --task T-XXXX --execute --json
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
 hadara task ready --task T-XXXX --level done --json
 
 # Optional workflow compression / next action preview:
 hadara task complete --task T-XXXX --json
 
-hadara task finish --task T-XXXX --json
-hadara task finish --task T-XXXX --execute --json
-
 hadara task close --task T-XXXX --json
 hadara task close --task T-XXXX --execute --json
 
@@ -175,6 +179,8 @@ Important distinctions:
 | `task close --execute` | Appends close evidence only. |
 | `task audit-close` | Read-only close proof audit. |
 
+Before `task close --execute`, finish Task Capsule docs, acceptance/tests/handoff notes, evidence summaries, Task Board updates, and tracked state docs. After close execute, changing those close-source docs intentionally invalidates the previous close proof and requires rerunning ready/close/audit. Use stable wording for close results instead of pasting volatile close evidence ids into close-source docs.
+
 ## Initialize a Project
 
 ```bash
@@ -184,6 +190,8 @@ hadara init --profile standard
 hadara init --profile governed
 ```
 
+Every profile generates `docs/TASK_WORKFLOW_COMMANDS.md` so fresh projects get the current evidence, ready, finish, close, and audit-close loop.
+
 | Profile | Use When |
 |---|---|
 | `basic` | Small project, only task/handoff discipline needed. |

package/dist/cli/init.js

@@ -14,9 +14,9 @@ const args_1 = require("./args");
 const INIT_PROFILE_SPECS = {
     basic: {
         profile: 'basic',
-        generatedDocsDescription: 'Core session docs only',
+        generatedDocsDescription: 'Core session docs plus task workflow commands',
         intendedUse: 'Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead.',
-        specialNotes: 'SOP required reading references only core docs plus active Task Capsule docs.',
+        specialNotes: 'SOP required reading references core docs, task workflow docs, and active Task Capsule docs.',
         docs: {
             architecture: false,
             developmentSlices: false,
@@ -141,6 +141,7 @@ function createGeneratedScaffoldFiles(profile) {
         { path: 'docs/TASK_BOARD.md', content: '# TASK_BOARD\n\n| ID | Title | Status | Capsule | Notes |\n|---|---|---|---|---|\n' },
         { path: 'docs/AGENT_HANDOFF.md', content: createAgentHandoffDoc() },
         { path: 'docs/IMPLEMENTATION_SOP.md', content: createImplementationSopDoc(spec) },
+        { path: 'docs/TASK_WORKFLOW_COMMANDS.md', content: createTaskWorkflowCommandsDoc() },
         { path: 'AGENTS.md', content: createAgentsDoc(spec) },
         { path: '.gitignore', content: createGitignoreDoc() }
     ];
@@ -163,7 +164,7 @@ function createGeneratedScaffoldFiles(profile) {
 function createInitDoctorReport(projectRoot) {
     const issues = [];
     const actions = [];
-    const requiredCore = ['AGENTS.md', '.gitignore', 'docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md'];
+    const requiredCore = ['AGENTS.md', '.gitignore', '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) {
         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.` });
@@ -391,6 +392,7 @@ const CANONICAL_TABLE_HEADERS = {
     '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/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 |'],
     'docs/DEVELOPMENT_SLICES.md': ['| Order | Slice | Capsule | Purpose | Done Evidence |'],
     'docs/DECISIONS.md': ['| ID | Date | Decision | Status | Rationale | Evidence |'],
@@ -493,7 +495,8 @@ function sopRequiredReadingRowsForProfile(profile) {
         ['`docs/PROJECT_STATE.md`', 'Every session', 'Current product state and source-of-truth map.'],
         ['`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact handoff and next recommended step.'],
         ['`docs/TASK_BOARD.md`', 'Every session', 'Work queue and task status.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
     if (profile === 'standard' || profile === 'governed') {
         rows.push(['`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.'], ['`docs/DEVELOPMENT_SLICES.md`', 'Starting, completing, or reclassifying slices', 'Roadmap ordering and completion evidence.'], ['`docs/DECISIONS.md`', 'Project-level decision work', 'Durable decisions that affect architecture or workflow.'], ['`docs/TEST_STRATEGY.md`', 'Validation planning or completion checks', 'Routine suites and special-case smoke boundaries.']);
@@ -508,7 +511,8 @@ function agentsRequiredReadingRowsForProfile(profile) {
         { document: '`docs/PROJECT_STATE.md`', when: 'Every session', purpose: 'Current product and capability state.' },
         { document: '`docs/AGENT_HANDOFF.md`', when: 'Every session', purpose: 'Compact continuation state.' },
         { document: '`docs/TASK_BOARD.md`', when: 'Every session', purpose: 'Current task queue and status.' },
-        { document: '`docs/IMPLEMENTATION_SOP.md`', when: 'Every session', purpose: 'Local workflow and required-reading registry.' }
+        { document: '`docs/IMPLEMENTATION_SOP.md`', when: 'Every session', purpose: 'Local workflow and required-reading registry.' },
+        { document: '`docs/TASK_WORKFLOW_COMMANDS.md`', when: 'Starting, finishing, closing, auditing, or explaining task workflow commands', purpose: 'Standard task loop, dry-run boundaries, and command `ok` semantics.' }
     ];
     if (profile === 'standard' || profile === 'governed') {
         rows.push({ document: '`docs/ARCHITECTURE.md`', when: 'Architecture, component, or boundary work', purpose: 'Current system shape and ownership boundaries.' }, { document: '`docs/DEVELOPMENT_SLICES.md`', when: 'Starting, completing, or reclassifying a development slice', purpose: 'Roadmap ordering, prerequisites, and completion evidence.' }, { document: '`docs/DECISIONS.md`', when: 'Project-level decision work', purpose: 'Durable project decisions.' }, { document: '`docs/TEST_STRATEGY.md`', when: 'Validation planning or completion checks', purpose: 'Routine suites and special-case checks.' });
@@ -632,7 +636,7 @@ function inferProfileFromGeneratedDocs(projectRoot) {
     return 'basic';
 }
 function requiredDocsForProfile(profile) {
-    const docs = ['docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md'];
+    const docs = ['docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/TASK_BOARD.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/TASK_WORKFLOW_COMMANDS.md'];
     if (profile === 'standard' || profile === 'governed') {
         docs.push('docs/ARCHITECTURE.md', 'docs/DEVELOPMENT_SLICES.md', 'docs/DECISIONS.md', 'docs/TEST_STRATEGY.md');
     }
@@ -765,7 +769,7 @@ function createAgentHandoffDoc() {
 | Area | State | Notes |
 |---|---|---|
 | Scaffold | Initialized | HADARA protocol scaffold is initialized. |
-| Required Reading | Pending | Read \`PROJECT_STATE\`, \`TASK_BOARD\`, and \`IMPLEMENTATION_SOP\` before starting. |
+| Required Reading | Pending | Read \`PROJECT_STATE\`, \`AGENT_HANDOFF\`, \`TASK_BOARD\`, \`IMPLEMENTATION_SOP\`, and \`TASK_WORKFLOW_COMMANDS\` before starting. |
 
 ## Last 3 Completed Tasks
 
@@ -843,7 +847,8 @@ function createImplementationSopDoc(spec) {
         ['`docs/PROJECT_STATE.md`', 'Every session', 'Current product state and source-of-truth map.'],
         ['`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact handoff and next recommended step.'],
         ['`docs/TASK_BOARD.md`', 'Every session', 'Work queue and task status.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local HADARA workflow rules and project-specific required-reading registry.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
     if (spec.docs.architecture) {
         requiredReadingRows.push(['`docs/ARCHITECTURE.md`', 'Architecture, component, or boundary work', 'Current system shape and ownership boundaries.']);
@@ -872,7 +877,8 @@ function createImplementationSopDoc(spec) {
         ['`docs/PROJECT_STATE.md`', 'Product, Current Phase, Current Status, and Single Source of Truth sections.'],
         ['`docs/AGENT_HANDOFF.md`', 'Current State, Last 3 Completed Tasks, Current Known Problems, Next Recommended Step, Validation Baseline, and Historical Index sections.'],
         ['`docs/TASK_BOARD.md`', 'One task table with ID, Title, Status, Capsule, and Notes columns.'],
-        ['`docs/IMPLEMENTATION_SOP.md`', 'Session Start, Required Reading, Init Profile Matrix, Scaffold Document Structure, Implementation, Validation, Session End, and Handoff Compaction sections.']
+        ['`docs/IMPLEMENTATION_SOP.md`', 'Session Start, Required Reading, Project-Specific Documents, Init Profile Matrix, Scaffold Document Structure, Implementation, Standard Task Workflow Loop, Validation, Evidence Records, Session End, and Handoff Compaction sections.'],
+        ['`docs/TASK_WORKFLOW_COMMANDS.md`', 'Standard Task Loop, Command Semantics, Non-Overlap Rules, and State Documents sections.']
     ];
     if (spec.docs.architecture)
         structureRows.push(['`docs/ARCHITECTURE.md`', 'Overview, Boundaries, and Current Components sections.']);
@@ -905,14 +911,23 @@ ${numberedList(sessionStart)}
 |---|---|---|
 ${requiredReadingRows.map(formatTableRow).join('\n')}
 
-When adding project-specific specs, contracts, or roadmap files, add them to this table and explain when agents must read them. Use \`hadara init register-doc --path <path> --when <text> --purpose <text> --json\` to preview registration, and add \`--execute\` to update this table.
+## Project-Specific Documents
+
+When adding project-specific specs, contracts, roadmap files, or human/agent operating notes, register them in the Required Reading table before expecting people or agents to rely on them. Each row must explain when to read the document and what decision or workflow boundary it owns.
+
+\`\`\`bash
+hadara init register-doc --path docs/specs/example.md --when "When changing example behavior" --purpose "Example behavior contract" --json
+hadara init register-doc --path docs/specs/example.md --when "When changing example behavior" --purpose "Example behavior contract" --execute --json
+\`\`\`
+
+Use \`--require-exists\` when the document must already exist before registration. Keep local-only notes out of committed required reading unless they are intentionally part of the project handoff.
 
 ## Init Profile Matrix
 
 | Profile | Scale | Generated Docs | Intended Use | Special Notes |
 |---|---|---|---|---|
-| \`basic\` | Small | Core session docs only | Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead. | SOP required reading references only core docs plus active Task Capsule docs. |
-| \`standard\` | Medium, default | Core docs plus planning, architecture, decision, and validation docs | Most multi-session projects that need roadmap slices and repeatable validation. | Optional integrations must be registered before agents rely on them. |
+| \`basic\` | Small | Core session docs plus task workflow commands | Small projects that need Task Capsules, evidence, and handoff discipline without planning overhead. | SOP required reading references core docs, task workflow docs, and active Task Capsule docs. |
+| \`standard\` | Medium, default | Basic docs plus planning, architecture, decision, and validation docs | Most multi-session projects that need roadmap slices and repeatable validation. | Optional integrations must be registered before agents rely on them. |
 | \`governed\` | Heavy | Standard docs plus security, refactor log, and roadmap docs | Long-lived projects with stronger governance, security boundaries, refactor history, or roadmap-level planning. | Project-specific contracts still must be manually registered in Required Reading. |
 
 ## Scaffold Document Structure
@@ -932,12 +947,71 @@ Prefer tables for repeated records and \`##\`/\`###\` headings for durable secti
 3. Make the smallest coherent change that satisfies acceptance criteria.
 4. Update task-local docs when scope changes.
 
+## Standard Task Workflow Loop
+
+The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. For ordinary implementation capsules, use this loop:
+
+\`\`\`bash
+hadara task next --json
+
+# If a matching capsule already exists:
+hadara task status --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
+
+# Do the scoped work.
+
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+
+hadara task finish --task T-XXXX --json
+hadara task finish --task T-XXXX --execute --json
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
+hadara task ready --task T-XXXX --level done --json
+
+# Optional workflow compression / next action preview:
+hadara task complete --task T-XXXX --json
+
+hadara task close --task T-XXXX --json
+hadara task close --task T-XXXX --execute --json
+
+hadara task audit-close --task T-XXXX --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\`. |
+| \`evidence add-command\` | Write | Appends command-log evidence; does not execute shell commands. |
+| \`task ready\` | Read-only | Checks readiness; does not mutate evidence or status docs. |
+| \`task finish\` | Dry-run by default; writes only with \`--execute\` | Bounded to \`TASK.md\` and \`docs/TASK_BOARD.md\`. |
+| \`task close\` | Dry-run by default; writes only with \`--execute\` | Bounded to close evidence append. |
+| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+
+Before running \`task ready\` and \`task close\`, 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 \`task close --execute --json\`, do not edit those close-source documents unless you intend to rerun \`task ready\`, \`task close\`, and \`task audit-close\`. 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. Run \`hadara harness validate --task <task-id> --json\`.
-3. Record evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
-4. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
+2. Record meaningful evidence in \`EVIDENCE.md\` and \`evidence.jsonl\`.
+3. Preview and execute \`hadara task finish --task <task-id> --json\` and \`hadara task finish --task <task-id> --execute --json\`.
+4. Finalize Task Capsule docs and tracked state docs before close so the close source hash remains stable.
+5. Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close.
+6. Preview and execute \`hadara task close --task <task-id> --json\` and \`hadara task close --task <task-id> --execute --json\`, then run \`hadara task audit-close --task <task-id> --json\`.
+7. Add project-specific integration or deployment smoke checks only after those surfaces exist and are documented for this project.
+
+\`task ready\` and \`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task <task-id> --level done --json\` directly when you need to debug capsule format or done-level validation failures.
+
+## Evidence Records
+
+1. Do not hand-edit Task Capsule \`evidence.jsonl\`.
+2. Append evidence through HADARA commands so schema, visibility, and artifact-safety checks run consistently.
+3. Record failed or blocked checks honestly. Do not replace them later with optimistic summaries; add newer evidence that explains the fix or residual risk.
+4. Use \`hadara evidence add-command --task <task-id> --summary <text> --result passed|failed|blocked|unknown --json\` for command results when no artifact file is attached.
+5. Use \`hadara evidence lint --task <task-id> --json\` when evidence drift is suspected or before close if evidence files were touched manually by mistake.
 
 ## Session End
 
@@ -1042,8 +1116,18 @@ function createTestStrategyDoc() {
 | Step | Check | Evidence Location |
 |---|---|---|
 | 1 | Run the relevant suite from the table above. | Task Capsule \`EVIDENCE.md\` |
-| 2 | Run \`hadara harness validate --task <task-id> --json\`. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
-| 3 | Record meaningful evidence in the Task Capsule. | Task Capsule files |
+| 2 | Record meaningful evidence in the Task Capsule. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
+| 3 | Preview and execute \`task finish\` to synchronize status bookkeeping. | Task Capsule \`TASK.md\` and \`docs/TASK_BOARD.md\` |
+| 4 | Finalize Task Capsule docs and tracked state docs before close. | Task Capsule docs and tracked state docs |
+| 5 | Run \`hadara task ready --task <task-id> --level done --json\` after finish and before close. | Task Capsule \`EVIDENCE.md\` and \`evidence.jsonl\` |
+| 6 | Preview and execute \`task close\`, then run \`task audit-close\`. | Task Capsule close evidence |
+
+## Diagnostic Checks
+
+| Check | Command | When To Use |
+|---|---|---|
+| Task Capsule format | \`hadara harness validate --task <task-id> --level done --json\` | \`task ready\` or \`task close\` reports done-level validation failures. |
+| Evidence index | \`hadara evidence lint --task <task-id> --json\` | Evidence files were touched manually by mistake or evidence drift is suspected. |
 
 ## Special-Case Checks
 
@@ -1072,14 +1156,94 @@ function createRoadmapDoc() {
 |---|---|---|
 `;
 }
+function createTaskWorkflowCommandsDoc() {
+    return `# TASK_WORKFLOW_COMMANDS
+
+HADARA task workflow commands are split by responsibility. Similar-looking commands are not interchangeable: some only report state, some check readiness, some perform bounded bookkeeping writes, and some append close evidence.
+
+## Standard Task Loop
+
+Use this loop for ordinary implementation capsules:
+
+\`\`\`bash
+hadara task next --json
+
+# If a matching capsule already exists:
+hadara task status --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
+
+# Do the scoped work.
+
+hadara evidence add-command --task T-XXXX --summary "..." --result passed --json
+
+hadara task finish --task T-XXXX --json
+hadara task finish --task T-XXXX --execute --json
+
+# Finalize Task Capsule docs and tracked state docs before closing.
+
+hadara task ready --task T-XXXX --level done --json
+
+# Optional workflow compression / next action preview:
+hadara task complete --task T-XXXX --json
+
+hadara task close --task T-XXXX --json
+hadara task close --task T-XXXX --execute --json
+
+hadara task audit-close --task T-XXXX --json
+\`\`\`
+
+\`task finish\`, \`task ready\`, and \`task close\` are intentionally separate. \`finish\` synchronizes bounded status bookkeeping first. \`ready\` then validates the Done-level state. \`close\` records close evidence after validation succeeds. \`audit-close\` checks the resulting close evidence after the write.
+
+The close model has three separate phases: validation proves readiness, close records the proof, and audit checks the already-recorded close evidence. Close evidence is excluded from the current validation loop because it is appended after validation; requiring it as a same-run precondition would create a fixed-point loop.
+
+\`task ready\` and \`task close\` include done-level Task Capsule validation. Use \`hadara harness validate --task T-XXXX --level done --json\` directly when debugging capsule format, status-history, acceptance, evidence, or handoff validation failures.
+
+Before close, 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 \`task close --execute --json\`, changing those documents changes the close source hash and requires rerunning \`task ready\`, \`task close\`, and \`task audit-close\`. Do not paste volatile close evidence ids into close-source docs; prefer stable wording such as "close evidence appended; audit returned closed-valid".
+
+## Command Semantics
+
+| 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 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. |
+| \`task finish\` | Dry-run by default; writes only with \`--execute\` | Updates only \`TASK.md\` status bookkeeping and the matching \`docs/TASK_BOARD.md\` row. |
+| \`task ready\` | Read-only | Checks whether the task can satisfy the requested readiness level after finish. |
+| \`task complete\` | Read-only | Summarizes the current completion stage and next command; it does not execute lifecycle writes. |
+| \`task close\` | Dry-run by default; writes only with \`--execute\` | Appends only canonical close evidence after close preconditions pass. |
+| \`task audit-close\` | Read-only | Verifies close evidence after close. |
+
+## Non-Overlap Rules
+
+- \`task next\` chooses work; it does not create a capsule or infer completion.
+- \`task status\` is an operator console; \`ok: true\` means report generation succeeded, not that the task is ready.
+- \`task ready\` checks readiness; it does not write evidence or status.
+- \`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 read-only workflow compressor. It may report the next lifecycle command, but it must not execute finish, ready, close, or audit commands.
+- \`evidence add-command\` records an operator-supplied command result; it does not run the command.
+- \`task finish\` may update only the Task Capsule \`TASK.md\` status and matching \`docs/TASK_BOARD.md\` status/path row.
+- \`task close\` may append only close evidence. It must not update status docs, Task Board rows, handoff, Project State, roadmap docs, or arbitrary evidence.
+- After \`task close --execute --json\`, close-source document edits intentionally invalidate the previous close proof. Make those edits before close, or rerun ready/close/audit if the edit is unavoidable.
+- \`task audit-close\` is read-only and should be run after \`task close --execute --json\`.
+
+## State Documents
+
+\`task finish --execute --json\` deliberately does not update broad prose state. Operators still update \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and any roadmap/slice docs generated for the selected profile when the task changes project state.
+`;
+}
 function createAgentsDoc(spec) {
     const requiredReadingRows = [
         ['1', '`docs/PROJECT_STATE.md`', 'Every session', 'Current product and capability state.'],
         ['2', '`docs/AGENT_HANDOFF.md`', 'Every session', 'Compact continuation state.'],
         ['3', '`docs/TASK_BOARD.md`', 'Every session', 'Current task queue and status.'],
-        ['4', '`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local workflow and required-reading registry.']
+        ['4', '`docs/IMPLEMENTATION_SOP.md`', 'Every session', 'Local workflow and required-reading registry.'],
+        ['5', '`docs/TASK_WORKFLOW_COMMANDS.md`', 'Starting, finishing, closing, auditing, or explaining task workflow commands', 'Standard task loop, dry-run boundaries, and command `ok` semantics.']
     ];
-    let order = 5;
+    let order = 6;
     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)
@@ -1099,7 +1263,8 @@ function createAgentsDoc(spec) {
     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.', '`EVIDENCE.md`, `evidence.jsonl`'],
+        ['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`'],
+        ['Task workflow', 'For task workflow commands, follow `docs/TASK_WORKFLOW_COMMANDS.md`: record evidence, preview and execute `task finish`, finalize close-source docs, run `task ready`, preview and execute `task close`, then run `task audit-close`.', '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`'],
@@ -1143,6 +1308,22 @@ dist/
 coverage/
 *.log
 
+# Python and test artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+env/
+*.db
+*.sqlite
+*.sqlite3
+
 # HADARA local/private state
 .hadara/local/
 .hadara/tmp/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadara",
-  "version": "0.2.0-rc.1",
+  "version": "0.2.0-rc.2",
   "private": false,
   "license": "MIT",
   "description": "HADARA: portable agentic development workbench",