hadara 0.3.0-rc.1 → 0.3.0-rc.2

package/README.md

@@ -5,7 +5,8 @@
 </p>
 
 <p align="center">
-  <img alt="Published npm release" src="https://img.shields.io/badge/npm-0.3.0--rc.0-blue">
+  <img alt="Published npm release" src="https://img.shields.io/badge/npm-0.3.0--rc.1-blue">
+  <img alt="Source candidate" src="https://img.shields.io/badge/source-0.3.0--rc.2-orange">
   <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>
@@ -20,13 +21,19 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 
 ## Release Status
 
-Current release candidate prepared for operator publish:
+Current published npm release:
 
 ```text
 hadara@0.3.0-rc.1
 ```
 
-Current published npm release:
+Current source release candidate:
+
+```text
+hadara@0.3.0-rc.2
+```
+
+Previous published npm release:
 
 ```text
 hadara@0.3.0-rc.0
@@ -34,7 +41,7 @@ hadara@0.3.0-rc.0
 
 The 0.3.0 line is the Phase 7 Surface Refactor. It organizes HADARA's existing task, evidence, proof, lifecycle, release, and document surfaces so agents can distinguish primary lifecycle commands, diagnostics, advanced surfaces, canonical documents, historical documents, and safe Markdown update boundaries.
 
-Phase 7.x labels are internal implementation phases, not npm release-candidate labels. Publishing `0.3.0-rc.1` or any later release still requires the approval-gated release path and explicit operator confirmation.
+Phase 7.x labels are internal implementation phases, not npm release-candidate labels. Publishing any later release still requires the approval-gated release path and explicit operator confirmation.
 
 | Surface | Status |
 |---|---|
@@ -42,8 +49,9 @@ Phase 7.x labels are internal implementation phases, not npm release-candidate l
 | `hadara@0.2.0-rc.1` | Previous published npm RC. |
 | `hadara@0.2.0-rc.2` | Previous published npm RC. |
 | `hadara@0.2.0-rc.3` | Previous published npm RC. |
-| `hadara@0.3.0-rc.0` | Current published npm RC; package metadata lacks the intended discovery fields. |
-| `hadara@0.3.0-rc.1` | Current publish candidate; T-0301 prepares the operator-confirmed npm publish path. |
+| `hadara@0.3.0-rc.0` | Previous published npm RC; package metadata lacks the intended discovery fields. |
+| `hadara@0.3.0-rc.1` | Current published npm RC; T-0301 publish evidence verified `npm view` returned `0.3.0-rc.1`. |
+| `hadara@0.3.0-rc.2` | Current source candidate prepared by T-0310; publish remains approval-gated. |
 | GitHub Release | Secondary target, approval-gated. |
 | Docker image | Deferred. |
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
@@ -55,10 +63,10 @@ No release command should publish, create a GitHub Release, build Docker images,
 
 Requires Node.js 22.
 
-Install the latest published RC before the T-0301 publish step:
+Install the latest published RC:
 
 ```bash
-npm install -g hadara@0.3.0-rc.0
+npm install -g hadara@0.3.0-rc.1
 hadara help
 hadara doctor --json
 ```
@@ -66,16 +74,8 @@ hadara doctor --json
 Run without a global install:
 
 ```bash
-npx hadara@0.3.0-rc.0 help
-npx hadara@0.3.0-rc.0 doctor --json
-```
-
-After the T-0301 npm publish helper verifies `hadara@0.3.0-rc.1` on the registry, install the new RC:
-
-```bash
-npm install -g hadara@0.3.0-rc.1
-hadara help
-hadara doctor --json
+npx hadara@0.3.0-rc.1 help
+npx hadara@0.3.0-rc.1 doctor --json
 ```
 
 ## What HADARA Gives You

package/dist/cli/init.js

@@ -140,6 +140,7 @@ function createGeneratedScaffoldFiles(profile) {
     const spec = INIT_PROFILE_SPECS[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/docs-registry.json', content: (0, docs_registry_1.registryJson)(docsRegistry) },
         { path: 'docs/DOC_REGISTRY.md', content: (0, docs_registry_1.renderDocRegistryMarkdown)(docsRegistry) },
         { path: 'docs/PROJECT_STATE.md', content: createProjectStateDoc(profile) },
@@ -169,7 +170,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', 'docs/TASK_WORKFLOW_COMMANDS.md'];
+    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) {
         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.` });
@@ -934,6 +935,7 @@ function createArchitectureDoc(profile) {
 }
 function createImplementationSopDoc(spec) {
     const sessionStart = [
+        'Read `.hadara/context/HADARA_CONTEXT.md` as the compact project-local context anchor.',
         'Read `docs/PROJECT_STATE.md`.',
         'Read `docs/AGENT_HANDOFF.md`.',
         'Read `docs/TASK_BOARD.md`.',
@@ -949,6 +951,7 @@ function createImplementationSopDoc(spec) {
         'Propose or choose the smallest useful implementation slice.'
     ];
     const requiredReadingRows = [
+        ['`.hadara/context/HADARA_CONTEXT.md`', 'Every session', 'Compact project-local context anchor and read-routing guide.'],
         ['`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.'],
@@ -1022,6 +1025,20 @@ This project was initialized with the \`${spec.profile}\` HADARA profile.
 
 ${numberedList(sessionStart)}
 
+## Required Reading Tiers
+
+Use semantic tiers to keep session startup compact and deterministic:
+
+| Tier | Meaning | Default Read Behavior |
+|---|---|---|
+| \`current-state\` | Compact docs that establish live project state and route deeper reading, starting with \`.hadara/context/HADARA_CONTEXT.md\`. | Read first at session start or resume. |
+| \`task-work\` | Active Task Capsule docs, \`docs/TASK_BOARD.md\`, and \`docs/TASK_WORKFLOW_COMMANDS.md\`. | 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, capsule, or Required Reading row condition applies. |
+| \`historical\` | Completed-task history, older validation records, and previous-state detail. | Never default required reading; read only when investigating history through the handoff Historical Index. |
+| \`excluded\` | Superseded, archived, local-only, or intentionally non-default material. | Never default required reading unless explicitly reclassified. |
+
+\`.hadara/context/HADARA_CONTEXT.md\` is the current-state entry point and read-routing guide. Full historical review of \`docs/PROJECT_STATE.md\` is not mandatory every session; rely on compact current-state docs first and follow \`docs/AGENT_HANDOFF.md\` Historical Index only when older history matters. Historical and superseded docs are never default required reading.
+
 ## Required Reading
 
 ${requiredReadingTable}
@@ -1062,6 +1079,22 @@ 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.
 
+## Documentation Timing and Write Coordination
+
+Do not defer all documentation until after implementation. Documentation is part of the work, not a post-work report.
+
+Keep capsule docs current as work changes:
+
+| Timing | Documents |
+|---|---|
+| Before execution | \`PLAN.md\` |
+| During execution | \`DECISIONS.md\`, \`RISKS.md\`, and \`FILES.md\` |
+| Immediately after validation | \`TESTS.md\` and \`EVIDENCE.md\` |
+| Before finish/ready/close | \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs |
+| Before close-source hash is captured | \`docs/TASK_BOARD.md\`, \`docs/PROJECT_STATE.md\`, \`docs/AGENT_HANDOFF.md\`, and roadmap/slice docs when applicable |
+
+Parallelize read-only discovery, \`rg\`/file inspection, independent validation commands, package or registry metadata inspection, read-only diagnostics, and draft preparation before writes. Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board writes, Project State writes, Agent Handoff writes, before-hash execute operations, \`task finish --execute\`, \`task close --execute\`, and release artifact or publish operations.
+
 ## Standard Task Workflow Loop
 
 The authoritative command semantics live in \`docs/TASK_WORKFLOW_COMMANDS.md\`. For ordinary implementation capsules, use this loop:
@@ -1276,6 +1309,10 @@ function createTaskWorkflowCommandsDoc() {
 
 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.
 
+## Required Reading Tier
+
+\`docs/TASK_WORKFLOW_COMMANDS.md\` is \`task-work\` required reading. Read it when selecting, implementing, finishing, closing, auditing, or changing task workflow commands; do not treat it as a historical archive or a replacement for current-state docs. Start from \`.hadara/context/HADARA_CONTEXT.md\` and compact state docs, then use this document for lifecycle command semantics.
+
 ## Standard Task Loop
 
 Use this loop for ordinary implementation capsules:
@@ -1318,6 +1355,14 @@ The close model has three separate phases: validation proves readiness, close re
 
 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".
 
+## Documentation Timing and Write Coordination
+
+Do not defer all documentation until after implementation. Keep \`PLAN.md\` current before execution; update \`DECISIONS.md\`, \`RISKS.md\`, and \`FILES.md\` during execution; update \`TESTS.md\` and \`EVIDENCE.md\` immediately after validation; update \`ACCEPTANCE.md\`, \`HANDOFF.md\`, and shared state docs before finish/ready/close; and update shared close-source docs before the close-source hash is captured.
+
+Parallelize read-only discovery, \`rg\`/file inspection, independent validation commands, package or registry metadata inspection, read-only diagnostics, and draft preparation before writes.
+
+Serialize same-file writes, evidence append, Task Capsule doc writes, Task Board writes, Project State writes, Agent Handoff writes, before-hash execute operations, \`task finish --execute\`, \`task close --execute\`, and release artifact or publish operations.
+
 ## Command Semantics
 
 | Command | Default Write Behavior | Notes |
@@ -1340,7 +1385,7 @@ Before close, finish all close-source edits: Task Capsule docs, acceptance/tests
 - \`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. \`--idempotency-key\` is optional; when supplied, same-key repeats return the existing record without appending duplicate Markdown or JSONL rows.
-- \`task finish\` may update only the Task Capsule \`TASK.md\` status and matching \`docs/TASK_BOARD.md\` status/path row.
+- \`task finish\` may update only the Task Capsule \`TASK.md\` status and the matching \`docs/TASK_BOARD.md\` row's command-owned cells: \`ID\`, \`Title\`, \`Status\`, and \`Capsule\`. It preserves human/mixed-owned \`Notes\` and any extra cells.
 - \`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\`.
@@ -1352,13 +1397,14 @@ Before close, finish all close-source edits: Task Capsule docs, acceptance/tests
 }
 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.'],
-        ['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.']
+        ['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.']
     ];
-    let order = 6;
+    let order = 7;
     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)
@@ -1379,6 +1425,8 @@ function createAgentsDoc(spec) {
         ['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, finish/close executes, and release/publish operations.', 'Task Capsule evidence'],
         ['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'],
@@ -1403,6 +1451,20 @@ ${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.
 
+## 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. |
+
+\`.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.
+
 ## Rules
 
 | Rule | Requirement | Evidence / Update Location |

package/dist/core/fs.js

@@ -8,6 +8,11 @@ exports.writeFileIfMissing = writeFileIfMissing;
 exports.appendLine = appendLine;
 exports.readTextIfExists = readTextIfExists;
 exports.writeJsonl = writeJsonl;
+exports.prepareAtomicTextFileWrite = prepareAtomicTextFileWrite;
+exports.commitPreparedAtomicTextFileWrite = commitPreparedAtomicTextFileWrite;
+exports.cleanupPreparedAtomicTextFileWrite = cleanupPreparedAtomicTextFileWrite;
+exports.rollbackPreparedAtomicTextFileWrite = rollbackPreparedAtomicTextFileWrite;
+exports.atomicWriteTextFile = atomicWriteTextFile;
 exports.slugify = slugify;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -33,6 +38,63 @@ function readTextIfExists(filePath) {
 function writeJsonl(filePath, event) {
     appendLine(filePath, JSON.stringify(event));
 }
+function prepareAtomicTextFileWrite(projectRoot, relativePath, content) {
+    const targetPath = resolveProjectRelativeWritePath(projectRoot, relativePath);
+    ensureDir(node_path_1.default.dirname(targetPath));
+    const previousExists = node_fs_1.default.existsSync(targetPath);
+    const previousContent = previousExists ? node_fs_1.default.readFileSync(targetPath, 'utf8') : '';
+    const tempPath = uniqueTempPath(targetPath, 'write');
+    node_fs_1.default.writeFileSync(tempPath, content, { encoding: 'utf8', flag: 'wx' });
+    return { relativePath, targetPath, tempPath, content, previousExists, previousContent };
+}
+function commitPreparedAtomicTextFileWrite(write) {
+    node_fs_1.default.renameSync(write.tempPath, write.targetPath);
+}
+function cleanupPreparedAtomicTextFileWrite(write) {
+    if (node_fs_1.default.existsSync(write.tempPath))
+        node_fs_1.default.rmSync(write.tempPath, { force: true });
+}
+function rollbackPreparedAtomicTextFileWrite(write) {
+    cleanupPreparedAtomicTextFileWrite(write);
+    if (write.previousExists) {
+        const rollbackTempPath = uniqueTempPath(write.targetPath, 'rollback');
+        node_fs_1.default.writeFileSync(rollbackTempPath, write.previousContent, { encoding: 'utf8', flag: 'wx' });
+        node_fs_1.default.renameSync(rollbackTempPath, write.targetPath);
+    }
+    else if (node_fs_1.default.existsSync(write.targetPath)) {
+        node_fs_1.default.rmSync(write.targetPath, { force: true });
+    }
+}
+function atomicWriteTextFile(projectRoot, relativePath, content) {
+    const prepared = prepareAtomicTextFileWrite(projectRoot, relativePath, content);
+    try {
+        commitPreparedAtomicTextFileWrite(prepared);
+    }
+    catch (error) {
+        cleanupPreparedAtomicTextFileWrite(prepared);
+        throw error;
+    }
+}
+function uniqueTempPath(targetPath, purpose) {
+    const dir = node_path_1.default.dirname(targetPath);
+    const base = node_path_1.default.basename(targetPath);
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        const suffix = `${process.pid}-${Date.now()}-${attempt}-${Math.random().toString(16).slice(2)}`;
+        const candidate = node_path_1.default.join(dir, `.hadara-atomic-${purpose}-${suffix}-${base}`);
+        if (!node_fs_1.default.existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`Could not allocate temporary path for ${targetPath}`);
+}
+function resolveProjectRelativeWritePath(projectRoot, relativePath) {
+    const rootPath = node_path_1.default.resolve(projectRoot);
+    const targetPath = node_path_1.default.resolve(rootPath, relativePath);
+    const relative = node_path_1.default.relative(rootPath, targetPath);
+    if (relative.startsWith('..') || node_path_1.default.isAbsolute(relative)) {
+        throw new Error(`Refusing to write outside project: ${relativePath}`);
+    }
+    return targetPath;
+}
 function slugify(input) {
     return input
         .normalize('NFKD')

package/dist/core/schema.js

@@ -30,6 +30,7 @@ const evidence_list_schema_json_1 = __importDefault(require("../schemas/evidence
 const evidence_migration_preview_schema_json_1 = __importDefault(require("../schemas/evidence-migration-preview.schema.json"));
 const event_schema_json_1 = __importDefault(require("../schemas/event.schema.json"));
 const feature_smoke_schema_json_1 = __importDefault(require("../schemas/feature-smoke.schema.json"));
+const harness_validate_schema_json_1 = __importDefault(require("../schemas/harness-validate.schema.json"));
 const handoff_suggestion_schema_json_1 = __importDefault(require("../schemas/handoff-suggestion.schema.json"));
 const install_plan_schema_json_1 = __importDefault(require("../schemas/install-plan.schema.json"));
 const next_action_schema_json_1 = __importDefault(require("../schemas/next-action.schema.json"));
@@ -95,6 +96,7 @@ const registeredSchemas = {
     'hadara.evidence.migration_preview.v1': evidence_migration_preview_schema_json_1.default,
     'hadara.event.v1': event_schema_json_1.default,
     'hadara.featureSmoke.v1': feature_smoke_schema_json_1.default,
+    'hadara.harness.validate.v1': harness_validate_schema_json_1.default,
     'hadara.handoff.suggestion.v1': handoff_suggestion_schema_json_1.default,
     'hadara.install.plan.v1': install_plan_schema_json_1.default,
     'hadara.next_action.v1': next_action_schema_json_1.default,