hadara 0.3.0-rc.1 → 0.3.0

package/dist/harness/validate.js

@@ -63,7 +63,13 @@ function validateTaskCapsule(projectRoot, taskId, options = {}) {
                 severity: 'error',
                 code: 'MISSING_TASK_FILE',
                 message: `Required Task Capsule file is missing: ${fileName}`,
-                path: relativePath
+                path: relativePath,
+                fixHint: `Create ${fileName} using the Task Capsule scaffold for this task.`,
+                remediationHint: {
+                    path: relativePath,
+                    requiredChange: `Create the missing required Task Capsule file ${fileName}.`,
+                    blocking: true
+                }
             });
         }
     }
@@ -103,7 +109,15 @@ function validateTaskMarkdown(projectRoot, task, issues) {
                 severity: 'error',
                 code: 'TASK_SECTION_MISSING',
                 message: `TASK.md is missing required section: ${heading}`,
-                path: relativePath
+                path: relativePath,
+                heading,
+                fixHint: `Add the ${heading} section to TASK.md and fill it with task-specific content.`,
+                remediationHint: {
+                    path: relativePath,
+                    heading,
+                    requiredChange: `Add the missing ${heading} section to TASK.md.`,
+                    blocking: true
+                }
             });
         }
     }
@@ -142,7 +156,15 @@ function validateMarkdownFile(projectRoot, task, issues, fileName, checks) {
                 severity: 'error',
                 code: check.code,
                 message: `${fileName} is missing standard Task Capsule format marker: ${check.anyText.join(' or ')}`,
-                path: relativePath
+                path: relativePath,
+                fixHint: `Restore the standard ${fileName} Task Capsule frame: ${check.anyText.join(' or ')}.`,
+                example: check.anyText[0],
+                remediationHint: {
+                    path: relativePath,
+                    requiredChange: `Restore the standard ${fileName} format marker.`,
+                    example: check.anyText[0],
+                    blocking: true
+                }
             });
         }
     }
@@ -159,7 +181,17 @@ function validateEvidenceMarkdown(projectRoot, task, issues) {
             severity: 'error',
             code: 'EVIDENCE_TABLE_INVALID',
             message: 'EVIDENCE.md must contain the standard evidence table header.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Evidence',
+            fixHint: 'Restore the standard EVIDENCE.md table header.',
+            example: '| Time | Kind | Summary | Result | Visibility | JSONL |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Evidence',
+                requiredChange: 'Restore the standard EVIDENCE.md table header.',
+                example: '| Time | Kind | Summary | Result | Visibility | JSONL |',
+                blocking: true
+            }
         });
     }
 }
@@ -327,7 +359,17 @@ function validateTaskMetadataComplete(projectRoot, task, issues) {
             severity: 'error',
             code: 'TASK_METADATA_PLACEHOLDER',
             message: `Done-level validation requires TASK.md metadata field(s) to be concrete dates, not TBD: ${missing.join(', ')}.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'Metadata',
+            fixHint: 'Replace TASK.md Created and Updated metadata placeholders with YYYY-MM-DD dates.',
+            example: '| Created | 2026-06-12 |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Metadata',
+                requiredChange: 'Replace Created and Updated metadata placeholders with concrete YYYY-MM-DD dates.',
+                example: '| Created | 2026-06-12 |',
+                blocking: true
+            }
         });
         return;
     }
@@ -336,7 +378,17 @@ function validateTaskMetadataComplete(projectRoot, task, issues) {
             severity: 'error',
             code: 'TASK_METADATA_DATE_INVALID',
             message: 'Done-level validation requires TASK.md Created and Updated metadata to use YYYY-MM-DD dates.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Metadata',
+            fixHint: 'Use YYYY-MM-DD values for TASK.md Created and Updated metadata.',
+            example: '| Updated | 2026-06-12 |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Metadata',
+                requiredChange: 'Use YYYY-MM-DD values for Created and Updated metadata.',
+                example: '| Updated | 2026-06-12 |',
+                blocking: true
+            }
         });
     }
 }
@@ -351,7 +403,17 @@ function validateTaskStatusDone(projectRoot, task, issues) {
             severity: 'error',
             code: 'TASK_STATUS_NOT_DONE',
             message: 'Done-level validation requires TASK.md status to be Done.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Status',
+            fixHint: 'Run `hadara task finish --task <task-id> --execute --json` or set the TASK.md status section to Done after the capsule is actually complete.',
+            example: '## Status\n\nDone',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Status',
+                requiredChange: 'Set TASK.md status to Done after the capsule is complete.',
+                example: '## Status\n\nDone',
+                blocking: true
+            }
         });
     }
 }
@@ -366,7 +428,17 @@ function validateTaskStatusHistoryDone(projectRoot, task, issues) {
             severity: 'error',
             code: 'TASK_STATUS_HISTORY_NOT_DONE',
             message: 'Done-level validation requires TASK.md Status History to end with Done.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Status History',
+            fixHint: 'Run `hadara task finish --task <task-id> --execute --json` so Status History ends with a Done row.',
+            example: '| 2026-06-12 | Done | Finished task capsule. | `hadara task finish --execute` |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Status History',
+                requiredChange: 'Append or repair the latest Status History row so it records Done.',
+                example: '| 2026-06-12 | Done | Finished task capsule. | `hadara task finish --execute` |',
+                blocking: true
+            }
         });
     }
 }
@@ -391,7 +463,17 @@ function validateAcceptanceDone(projectRoot, task, issues) {
             severity: 'error',
             code: 'ACCEPTANCE_INCOMPLETE',
             message: 'Done-level validation requires all acceptance criteria to be complete.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Acceptance Criteria',
+            fixHint: 'Mark each acceptance criterion complete with concrete evidence, or replace placeholder checklist rows with completed task-specific criteria.',
+            example: '| AC-1 | Scope is implemented. | Done | evidence id or summary |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Acceptance Criteria',
+                requiredChange: 'Complete every acceptance criterion with evidence before closing.',
+                example: '| AC-1 | Scope is implemented. | Done | evidence id or summary |',
+                blocking: true
+            }
         });
     }
 }
@@ -453,7 +535,17 @@ function validateDoneLevelScaffoldContent(projectRoot, task, issues) {
                 severity: 'error',
                 code: check.code,
                 message: check.message,
-                path: toPortablePath(node_path_1.default.relative(projectRoot, filePath))
+                path: toPortablePath(node_path_1.default.relative(projectRoot, filePath)),
+                heading: scaffoldHeadingForFile(check.fileName),
+                fixHint: scaffoldFixHint(check.fileName),
+                example: scaffoldExample(check.fileName),
+                remediationHint: {
+                    path: toPortablePath(node_path_1.default.relative(projectRoot, filePath)),
+                    heading: scaffoldHeadingForFile(check.fileName),
+                    requiredChange: scaffoldRequiredChange(check.fileName),
+                    example: scaffoldExample(check.fileName),
+                    blocking: true
+                }
             });
         }
     }
@@ -468,7 +560,15 @@ function validateEvidenceIndexHasRecords(projectRoot, task, issues) {
             severity: 'error',
             code: 'EVIDENCE_REQUIRED',
             message: 'Done-level validation requires at least one evidence.jsonl record.',
-            path: relativePath
+            path: relativePath,
+            fixHint: 'Record validation evidence with `hadara evidence add-command --task <task-id> --summary "..." --result passed --json`.',
+            example: 'hadara evidence add-command --task T-0001 --summary "Focused tests passed." --result passed --json',
+            remediationHint: {
+                path: relativePath,
+                requiredChange: 'Append at least one substantive evidence record through the canonical evidence writer.',
+                example: 'hadara evidence add-command --task T-0001 --summary "Focused tests passed." --result passed --json',
+                blocking: true
+            }
         });
     }
 }
@@ -481,7 +581,15 @@ function validateEvidenceSemanticGates(projectRoot, task, issues) {
             severity: issue.severity === 'warning' ? 'warning' : 'error',
             code: issue.code,
             message: issue.message,
-            path: issue.path
+            path: issue.path,
+            fixHint: issue.severity === 'warning' ? 'Review evidence quality and add public validation evidence if needed.' : 'Add substantive passed validation evidence before closing.',
+            remediationHint: issue.path
+                ? {
+                    path: issue.path,
+                    requiredChange: issue.severity === 'warning' ? 'Review evidence quality for the task.' : 'Add substantive passed validation evidence for the task.',
+                    blocking: issue.severity !== 'warning'
+                }
+                : undefined
         });
     }
 }
@@ -497,7 +605,17 @@ function validateEvidenceMarkdownSingleTable(projectRoot, task, issues) {
             severity: 'error',
             code: 'EVIDENCE_TABLE_DUPLICATE_HEADER',
             message: `Done-level validation requires EVIDENCE.md to contain exactly one evidence table header; found ${tableHeaderCount}.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'Evidence',
+            fixHint: 'Remove duplicate EVIDENCE.md table headers and keep one canonical evidence table.',
+            example: '| Time | Kind | Summary | Result | Visibility | JSONL |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Evidence',
+                requiredChange: 'Remove duplicate EVIDENCE.md table headers and keep one canonical table.',
+                example: '| Time | Kind | Summary | Result | Visibility | JSONL |',
+                blocking: true
+            }
         });
     }
 }
@@ -513,7 +631,17 @@ function validateHandoffDone(projectRoot, task, issues) {
             severity: 'error',
             code: 'HANDOFF_PLACEHOLDER',
             message: 'Done-level validation requires non-placeholder handoff sections.',
-            path: relativePath
+            path: relativePath,
+            heading: 'Last Completed / Next Recommended Step',
+            fixHint: 'Replace HANDOFF.md placeholder rows with concrete last-completed work and next-step guidance.',
+            example: '| Continue with T-0002. | T-0001 is closed-valid. | docs/TASK_BOARD.md |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'Last Completed / Next Recommended Step',
+                requiredChange: 'Replace handoff placeholders with concrete last-completed and next recommended step rows.',
+                example: '| Continue with T-0002. | T-0001 is closed-valid. | docs/TASK_BOARD.md |',
+                blocking: true
+            }
         });
     }
 }
@@ -526,7 +654,17 @@ function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
             severity: 'error',
             code: 'TASK_BOARD_MISSING',
             message: 'Done-level validation requires docs/TASK_BOARD.md to contain the completed task row.',
-            path: relativePath
+            path: relativePath,
+            heading: 'TASK_BOARD',
+            fixHint: 'Restore docs/TASK_BOARD.md with the canonical task table and a row for this task.',
+            example: '| ID | Title | Status | Capsule | Notes |',
+            remediationHint: {
+                path: relativePath,
+                heading: 'TASK_BOARD',
+                requiredChange: 'Restore docs/TASK_BOARD.md with the canonical task table and completed task row.',
+                example: '| ID | Title | Status | Capsule | Notes |',
+                blocking: true
+            }
         });
         return;
     }
@@ -536,7 +674,17 @@ function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
             severity: 'error',
             code: 'TASK_BOARD_ROW_MISSING',
             message: `Done-level validation requires docs/TASK_BOARD.md to contain exactly one row for ${task.id}.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'TASK_BOARD',
+            fixHint: `Add a docs/TASK_BOARD.md row for ${task.id}, or rerun the task workflow command that should synchronize it.`,
+            example: `| ${task.id} | ${task.title} | Done | ${toPortablePath(node_path_1.default.relative(projectRoot, task.dir))} | |`,
+            remediationHint: {
+                path: relativePath,
+                heading: 'TASK_BOARD',
+                requiredChange: `Add exactly one Task Board row for ${task.id}.`,
+                example: `| ${task.id} | ${task.title} | Done | ${toPortablePath(node_path_1.default.relative(projectRoot, task.dir))} | |`,
+                blocking: true
+            }
         });
         return;
     }
@@ -545,7 +693,15 @@ function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
             severity: 'error',
             code: 'TASK_BOARD_ROW_DUPLICATE',
             message: `docs/TASK_BOARD.md contains ${rows.length} rows for ${task.id}; expected exactly one.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'TASK_BOARD',
+            fixHint: `Remove duplicate docs/TASK_BOARD.md rows for ${task.id} so exactly one row remains.`,
+            remediationHint: {
+                path: relativePath,
+                heading: 'TASK_BOARD',
+                requiredChange: `Remove duplicate Task Board rows for ${task.id}.`,
+                blocking: true
+            }
         });
         return;
     }
@@ -556,7 +712,17 @@ function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
             severity: 'error',
             code: 'TASK_BOARD_STATUS_NOT_DONE',
             message: `Done-level validation requires docs/TASK_BOARD.md status for ${task.id} to be Done.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'TASK_BOARD',
+            fixHint: `Run \`hadara task finish --task ${task.id} --execute --json\` or update the Task Board status cell for ${task.id} to Done.`,
+            example: `| ${task.id} | ${row.title} | Done | ${row.capsule} | ${row.notes} |`,
+            remediationHint: {
+                path: relativePath,
+                heading: 'TASK_BOARD',
+                requiredChange: `Set the Task Board status cell for ${task.id} to Done.`,
+                example: `| ${task.id} | ${row.title} | Done | ${row.capsule} | ${row.notes} |`,
+                blocking: true
+            }
         });
     }
     if (row.capsule !== expectedCapsule) {
@@ -564,7 +730,17 @@ function validateTaskBoardDone(projectRoot, task, issues, checkedFiles) {
             severity: 'error',
             code: 'TASK_BOARD_CAPSULE_MISMATCH',
             message: `docs/TASK_BOARD.md capsule for ${task.id} is ${row.capsule || '(empty)'}, expected ${expectedCapsule}.`,
-            path: relativePath
+            path: relativePath,
+            heading: 'TASK_BOARD',
+            fixHint: `Update the Task Board capsule cell for ${task.id} to ${expectedCapsule}.`,
+            example: `| ${task.id} | ${row.title} | ${row.status} | ${expectedCapsule} | ${row.notes} |`,
+            remediationHint: {
+                path: relativePath,
+                heading: 'TASK_BOARD',
+                requiredChange: `Set the Task Board capsule cell for ${task.id} to ${expectedCapsule}.`,
+                example: `| ${task.id} | ${row.title} | ${row.status} | ${expectedCapsule} | ${row.notes} |`,
+                blocking: true
+            }
         });
     }
 }
@@ -634,6 +810,43 @@ function isMetadataPlaceholder(value) {
 function isIsoDate(value) {
     return /^\d{4}-\d{2}-\d{2}$/.test(value.trim());
 }
+function scaffoldHeadingForFile(fileName) {
+    const headings = {
+        'TASK.md': 'Goal / Scope / Out of Scope',
+        'PLAN.md': 'Plan',
+        'CONTEXT.md': 'Context',
+        'FILES.md': 'Files',
+        'ACCEPTANCE.md': 'Acceptance Criteria',
+        'TESTS.md': 'Tests',
+        'RISKS.md': 'Risks',
+        'DECISIONS.md': 'Decisions',
+        'EVIDENCE.md': 'Evidence'
+    };
+    return headings[fileName];
+}
+function scaffoldRequiredChange(fileName) {
+    const heading = scaffoldHeadingForFile(fileName);
+    return heading
+        ? `Replace scaffold placeholder content in ${fileName} under ${heading} with task-specific content.`
+        : `Replace scaffold placeholder content in ${fileName} with task-specific content.`;
+}
+function scaffoldFixHint(fileName) {
+    return `${scaffoldRequiredChange(fileName)} Mark rows Done only after the work and evidence are real.`;
+}
+function scaffoldExample(fileName) {
+    const examples = {
+        'TASK.md': '| Preserve Task Board notes. | `task finish` must not erase human-authored cells. |',
+        'PLAN.md': '| 1 | Implement focused fix. | Done | evidence id or summary |',
+        'CONTEXT.md': '| docs/TASK_BOARD.md | Task Board source of truth. | Read |',
+        'FILES.md': '| src/task/task-close.ts | Modify | Add hints. | Done |',
+        'ACCEPTANCE.md': '| AC-1 | Scope is implemented. | Done | evidence id or summary |',
+        'TESTS.md': '| npm run test:focused -- tests/unit/task-ready.test.ts | Validate hints. | Yes | Passed | evidence id |',
+        'RISKS.md': '| Consumer rejects additive fields. | Medium | Low | Keep fields optional. | Mitigated |',
+        'DECISIONS.md': '| D-1 | Add additive hints only. | Accepted | Preserve issue-code compatibility. | Tests. |',
+        'EVIDENCE.md': '| 2026-06-12T00:00:00.000Z | command-log | Focused tests passed. | passed | public | evidence.jsonl |'
+    };
+    return examples[fileName] ?? 'Replace TBD rows with task-specific content.';
+}
 function toPortablePath(value) {
     return value.split(node_path_1.default.sep).join('/');
 }

package/dist/schemas/docs-required-reading.schema.json

@@ -35,6 +35,7 @@
                     "type": "array",
                     "items": { "type": "string", "minLength": 1 }
                 },
+                "tier": { "$ref": "#/$defs/tier" },
                 "reason": { "type": "string", "minLength": 1 }
             }
         },
@@ -45,9 +46,14 @@
             "properties": {
                 "path": { "type": "string", "minLength": 1 },
                 "status": { "type": "string", "enum": ["historical", "superseded", "archived"] },
+                "tier": { "$ref": "#/$defs/tier" },
                 "reason": { "type": "string", "minLength": 1 }
             }
         },
+        "tier": {
+            "type": "string",
+            "enum": ["current-state", "task-work", "conditional-reference", "historical", "excluded"]
+        },
         "issue": {
             "type": "object",
             "additionalProperties": true,

package/dist/schemas/harness-validate.schema.json

@@ -0,0 +1,58 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.harness.validate.v1",
+    "x-hadara-schema-id": "hadara.harness.validate.v1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "level", "task", "checkedFiles", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.harness.validate.v1" },
+        "command": { "const": "harness.validate" },
+        "ok": { "type": "boolean" },
+        "level": { "enum": ["draft", "done"] },
+        "task": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "title", "capsule"],
+            "properties": {
+                "id": { "type": "string" },
+                "title": { "type": "string" },
+                "capsule": { "type": "string" }
+            }
+        },
+        "checkedFiles": { "type": "array", "items": { "type": "string" } },
+        "issues": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/issue" }
+        }
+    },
+    "$defs": {
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "enum": ["error", "warning"] },
+                "code": { "type": "string" },
+                "message": { "type": "string" },
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "fixHint": { "type": "string" },
+                "example": { "type": "string" },
+                "remediationHint": { "$ref": "#/$defs/remediationHint" }
+            }
+        },
+        "remediationHint": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["path", "requiredChange", "blocking"],
+            "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "requiredChange": { "type": "string" },
+                "example": { "type": "string" },
+                "blocking": { "type": "boolean" }
+            }
+        }
+    }
+}

package/dist/schemas/schema-index.json

@@ -344,6 +344,13 @@
             "owner": "feature-smoke/runner",
             "notes": "Documents reduced read-only major feature smoke reports for core service/read-model validation; installed binary and launcher checks are deferred."
         },
+        {
+            "id": "hadara.harness.validate.v1",
+            "path": "src/schemas/harness-validate.schema.json",
+            "status": "fixture",
+            "owner": "harness/validate",
+            "notes": "Documents Task Capsule draft/done validation reports with additive remediation hints."
+        },
         {
             "id": "hadara.cleanCheckoutSmoke.v1",
             "path": "src/schemas/clean-checkout-smoke.schema.json",

package/dist/schemas/task-close.schema.json

@@ -133,9 +133,27 @@
                     "severity": { "enum": ["error", "warning", "info"] },
                     "code": { "type": "string" },
                     "message": { "type": "string" },
-                    "path": { "type": "string" }
+                    "path": { "type": "string" },
+                    "heading": { "type": "string" },
+                    "fixHint": { "type": "string" },
+                    "example": { "type": "string" },
+                    "remediationHint": { "$ref": "#/$defs/remediationHint" }
                 }
             }
         }
+    },
+    "$defs": {
+        "remediationHint": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["path", "requiredChange", "blocking"],
+            "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "requiredChange": { "type": "string" },
+                "example": { "type": "string" },
+                "blocking": { "type": "boolean" }
+            }
+        }
     }
 }

package/dist/schemas/task-ready.schema.json

@@ -45,6 +45,35 @@
         },
         "nextActions": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
         "primaryNextAction": { "type": "object", "additionalProperties": true },
-        "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } }
+    },
+    "$defs": {
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "enum": ["error", "warning", "info"] },
+                "code": { "type": "string" },
+                "message": { "type": "string" },
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "fixHint": { "type": "string" },
+                "example": { "type": "string" },
+                "remediationHint": { "$ref": "#/$defs/remediationHint" }
+            }
+        },
+        "remediationHint": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["path", "requiredChange", "blocking"],
+            "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "requiredChange": { "type": "string" },
+                "example": { "type": "string" },
+                "blocking": { "type": "boolean" }
+            }
+        }
     }
 }

package/dist/services/docs-cleanup.js

@@ -9,6 +9,7 @@ exports.createDocsRequiredReadingReport = createDocsRequiredReadingReport;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../core/fs");
 const docs_registry_1 = require("./docs-registry");
 const EXCLUDED_REQUIRED_READING_STATUSES = new Set(['historical', 'superseded', 'archived']);
 const ARCHIVE_STATUSES = new Set(['historical', 'superseded']);
@@ -34,13 +35,19 @@ function createDocsMarkReport(projectRoot, options) {
     if (options.mode === 'execute' && options.beforeHash && options.beforeHash !== state.beforeHash) {
         issues.push({ severity: 'error', code: 'DOC_CLEANUP_BEFORE_HASH_MISMATCH', path: docs_registry_1.DOCS_REGISTRY_PATH, message: `Registry hash ${state.beforeHash} does not match reviewed hash ${options.beforeHash}.` });
     }
-    const ok = issues.every((issue) => issue.severity !== 'error');
+    let ok = issues.every((issue) => issue.severity !== 'error');
     if (options.mode === 'execute' && ok && state.registry && entry && afterStatus) {
         entry.status = afterStatus;
         entry.notes = options.reason ? `${entry.notes ? `${entry.notes} ` : ''}Cleanup reason: ${options.reason}` : entry.notes;
         if (afterStatus === 'superseded')
             entry.supersededBy = normalizePath(options.by ?? '');
-        node_fs_1.default.writeFileSync(node_path_1.default.join(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH), (0, docs_registry_1.registryJson)(state.registry), 'utf8');
+        try {
+            (0, fs_1.atomicWriteTextFile)(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH, (0, docs_registry_1.registryJson)(state.registry));
+        }
+        catch (error) {
+            ok = false;
+            issues.push({ severity: 'error', code: 'DOC_CLEANUP_ATOMIC_WRITE_FAILED', path: docs_registry_1.DOCS_REGISTRY_PATH, message: `Could not write docs registry atomically: ${error instanceof Error ? error.message : String(error)}` });
+        }
     }
     return {
         schemaVersion: 'hadara.docs.mark.v1',
@@ -91,11 +98,12 @@ function createDocsRequiredReadingReport(projectRoot) {
     for (const doc of state.registry?.documents ?? []) {
         if (!doc.requiredReading)
             continue;
+        const tier = requiredReadingTier(doc);
         if (EXCLUDED_REQUIRED_READING_STATUSES.has(doc.status)) {
-            excluded.push({ path: doc.path, status: doc.status, reason: `${doc.status} docs are not default required reading` });
+            excluded.push({ path: doc.path, status: doc.status, tier, reason: `${doc.status} docs are not default required reading` });
         }
         else {
-            documents.push({ path: doc.path, status: doc.status, readWhen: doc.readWhen, reason: `${doc.status} ${doc.kind} doc` });
+            documents.push({ path: doc.path, status: doc.status, readWhen: doc.readWhen, tier, reason: `${doc.status} ${doc.kind} doc` });
         }
     }
     return {
@@ -107,6 +115,19 @@ function createDocsRequiredReadingReport(projectRoot) {
         issues
     };
 }
+function requiredReadingTier(doc) {
+    if (doc.status === 'superseded' || doc.status === 'archived')
+        return 'excluded';
+    if (doc.status === 'historical')
+        return 'historical';
+    if (doc.kind === 'workflow-guide' || doc.kind === 'task-board' || doc.kind === 'task-capsule' || doc.readWhen.some((readWhen) => readWhen === 'task-start' || readWhen === 'task-close')) {
+        return 'task-work';
+    }
+    if (doc.kind === 'project-context' || doc.kind === 'project-state' || doc.kind === 'handoff' || doc.kind === 'protocol' || doc.readWhen.includes('session-start')) {
+        return 'current-state';
+    }
+    return 'conditional-reference';
+}
 function validateTransition(entry, afterStatus, options) {
     const issues = [];
     const reasonRequired = afterStatus === 'historical' || afterStatus === 'superseded';