agentera 3.0.0-dev.75 → 3.0.0-dev.76

package/bundle/.agentera-build-source.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "agentera.generatedBuildSource.v1",
-  "commit": "01a0c460f2310bae5805a637973021af30960ee5",
-  "tree": "998eef2c833de05d61612ce021a02ecb28a0b2b5",
-  "files": 6748,
-  "workingTreeSha256": "3c780bac24a26ed1c40735614d2e9313eb30114901d6b71beb427a74e144bb22",
-  "identitySha256": "04d4e2a388eb6420f37ce0ee4c7052d3a85035d2e0e23e4eaaa980b96e36bf58"
+  "commit": "70aed21badb985087fd79371fabb61b1ec31ddde",
+  "tree": "3baa4c8145944638cad38ae98346f98518d01884",
+  "files": 6750,
+  "workingTreeSha256": "57aa3b7d804724356e7a3bf9adf7ea9a54e29312cd19b0abcd23f4f9699dfe54",
+  "identitySha256": "f4acdd4621fd8110b1277f88be7f093929a887c6b4db6c3269e3a1af98a63b36"
 }

package/bundle/CHANGELOG.md

@@ -92,6 +92,11 @@
 
 ### Fixed
 
+- Fixed TODO reconciliation so typed writes use canonical severity headings and
+  insert missing bands before later sections. Duplicate, mismatched, or
+  out-of-order headings now return one bounded actionable diagnosis through
+  TODO reads, Prime, Doctor, and state validation, and block writes before effects.
+  Recognized v2 `## Resolved` headings normalize during entity cutover.
 - Fixed large unsafe inactive TODO status startup to fit its 22,500-byte JSON limit with bounded recovery details.
 - Fixed fresh projects so they can initialize Plan entity state without a legacy upgrade route.
 - Fixed `agentera doctor --format json` to report bounded, read-only retirement

package/dist/.agentera-build-source.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "agentera.generatedBuildSource.v1",
-  "commit": "01a0c460f2310bae5805a637973021af30960ee5",
-  "tree": "998eef2c833de05d61612ce021a02ecb28a0b2b5",
-  "files": 6748,
-  "workingTreeSha256": "3c780bac24a26ed1c40735614d2e9313eb30114901d6b71beb427a74e144bb22",
-  "identitySha256": "04d4e2a388eb6420f37ce0ee4c7052d3a85035d2e0e23e4eaaa980b96e36bf58"
+  "commit": "70aed21badb985087fd79371fabb61b1ec31ddde",
+  "tree": "3baa4c8145944638cad38ae98346f98518d01884",
+  "files": 6750,
+  "workingTreeSha256": "57aa3b7d804724356e7a3bf9adf7ea9a54e29312cd19b0abcd23f4f9699dfe54",
+  "identitySha256": "f4acdd4621fd8110b1277f88be7f093929a887c6b4db6c3269e3a1af98a63b36"
 }

package/dist/cli/commands/doctor.js

@@ -181,6 +181,7 @@ export function cmdDoctor(args, io = {}) {
             reconciliationState: todoReconciliation.state,
             reconciliationCounts: todoReconciliation.counts,
             reconciliationOmittedCount: todoReconciliation.omitted_count,
+            ...(todoReconciliation.risks ? { reconciliationRisks: todoReconciliation.risks } : {}),
             previewCommand: todoReconciliation.preview_command,
             applyCommand: todoReconciliation.apply_command,
             recoveryCommand: todoReconciliation.recovery_command,

package/dist/state/entityMigrationTodo.js

@@ -110,7 +110,7 @@ export function todoReconciliationMigrationPlan(todoPath, files, entries) {
     }));
     if (byLine.size !== rows.length)
         return undefined;
-    const lines = todo.bytes.toString("utf8").split(/\r?\n/);
+    const lines = todo.bytes.toString("utf8").split(/\r?\n/).map((line) => line === "## Resolved" ? "## ✓ Resolved" : line);
     for (const row of rows) {
         const entry = byLine.get(row.index);
         if (!entry?.proposed_target)

package/dist/state/todoDocsEntities.js

@@ -22,6 +22,7 @@ import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconci
 import { normalizeTodoOwnerCorrectionEvidence, planTodoOwnerCorrection, planTodoRepair } from "./todoReconciliationRepair.js";
 import { readTodoMarkdown, renderManagedMarkdown } from "./todoMarkdownProjection.js";
 import { inactiveTodoActivationSafety, rejectUnsafeInactiveTodoActivation, unsafeInactiveDuplicateDiagnosis } from "./todoActivationSafety.js";
+import { assertTodoSeverityHeadingStructure, todoSeveritySectionForHeading } from "./todoSeverityHeadings.js";
 const ID = /^[a-z]{10}$/;
 const SHA256 = /^[a-f0-9]{64}$/;
 const TODO = { artifact: "todo", boundary: "todo_item", order: "severity_then_status_then_markdown_order_then_id" };
@@ -139,6 +140,7 @@ function todoAuthority() {
     };
 }
 export function managedRows(markdown, activation, entities) {
+    assertTodoSeverityHeadingStructure(markdown);
     const result = new Map();
     const order = new Map();
     const legacy = [];
@@ -146,7 +148,7 @@ export function managedRows(markdown, activation, entities) {
     markdown.split(/\r?\n/).forEach((line, index) => {
         const heading = line.trim().match(/^##\s+(.+)$/)?.[1]?.toLowerCase();
         if (heading)
-            section = heading.includes("critical") ? "critical" : heading.includes("degraded") ? "degraded" : heading.includes("annoying") ? "annoying" : heading.includes("resolved") ? "resolved" : heading.includes("normal") ? "normal" : heading === "notes" ? null : section;
+            section = todoSeveritySectionForHeading(line) ?? (heading === "notes" ? null : section);
         const item = parseTodoMarkdownListItem(line.trim());
         if (!item)
             return;
@@ -291,16 +293,17 @@ function inspectTodoReadView(root, sourceRoot, entities) {
     catch (error) {
         if (error instanceof StateWriteInputError && /Markdown/i.test(error.body.message))
             throw error;
+        const diagnosis = error instanceof StateWriteInputError && mapping(error.body.diagnosis) ? error.body.diagnosis : undefined;
         return {
             rows: new Map(),
             drift: {
                 schema_version: RECONCILIATION_VERSION,
-                status: "unsafe",
+                status: "conflict", action_required: true,
                 read_effect: "none",
                 next_write_boundary: "atomic_reconciliation",
                 authority: todoAuthority(),
                 counts: { managed: 0, drifted: 0, conflicts: 1 },
-                items: [],
+                items: [], ...(diagnosis ? { diagnosis } : {}),
             },
         };
     }
@@ -669,6 +672,8 @@ export function mutateTodoDocsEntity(req, options = {}) {
         const correctingOwners = artifact === "todo" && req.spec.verb === "correct-owners";
         const ownerEvidence = correctingOwners ? normalizeTodoOwnerCorrectionEvidence(req.input ?? {}) : null;
         const pending = todoBinding ? inspectTodoReconciliation(pinnedRoot, todoBinding) : [];
+        if (artifact === "todo")
+            assertTodoSeverityHeadingStructure(readTodoMarkdown(todoPublicPath(pinnedRoot, sourceRoot)).text);
         const initialActivation = artifact === "todo" ? loadTodoReconciliationActivation(pinnedRoot) : null;
         if (artifact === "todo" && ["activate", "repair", "correct-owners"].includes(req.spec.verb)) {
             const repairing = req.spec.verb === "repair";

package/dist/state/todoMarkdownProjection.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
 import { reject } from "./write/errors.js";
+import { TODO_SEVERITY_HEADINGS, todoSeveritySectionForHeading } from "./todoSeverityHeadings.js";
 const TODO_MARKDOWN_MAX_BYTES = 1024 * 1024;
 export function readTodoMarkdown(target) {
     if (!fs.existsSync(target))
@@ -21,7 +22,7 @@ export function readTodoMarkdown(target) {
     return { bytes, text: text };
 }
 function sectionFor(record) { return record.status === "resolved" ? "resolved" : String(record.severity); }
-function headingFor(section) { return section === "resolved" ? "## ✓ Resolved" : `## → ${section[0].toUpperCase()}${section.slice(1)}`; }
+function headingFor(section) { return TODO_SEVERITY_HEADINGS.find((entry) => entry.section === section).heading; }
 function rowFor(id, record) { return `- [${record.status === "resolved" ? "x" : " "}] [id:${id}] ${renderTodoPublicRecord(record)}`; }
 export function renderManagedMarkdown(markdown, records, existing) {
     const byLine = new Map([...existing.values()].map((row) => [row.line, row]));
@@ -29,16 +30,27 @@ export function renderManagedMarkdown(markdown, records, existing) {
     const lines = markdown.split(/\r?\n/).flatMap((line, index) => { const row = byLine.get(index); if (!row)
         return [line]; const record = records.get(row.id); if (!record || sectionFor(record) !== row.section)
         return []; retained.add(row.id); return [rowFor(row.id, record)]; });
-    for (const section of ["critical", "degraded", "normal", "annoying", "resolved"]) {
+    for (const { section } of TODO_SEVERITY_HEADINGS) {
         const ids = [...records.entries()].filter(([id, record]) => !retained.has(id) && sectionFor(record) === section).sort(([left], [right]) => { const a = existing.get(left); const b = existing.get(right); return (a?.section === section ? a.snapshot.order : Number.MAX_SAFE_INTEGER) - (b?.section === section ? b.snapshot.order : Number.MAX_SAFE_INTEGER) || left.localeCompare(right); }).map(([id]) => id);
         if (!ids.length)
             continue;
         let heading = lines.findIndex((line) => line.trim().toLowerCase() === headingFor(section).toLowerCase());
         if (heading < 0) {
-            if (lines.at(-1)?.trim())
-                lines.push("");
-            lines.push(headingFor(section));
-            heading = lines.length - 1;
+            const order = TODO_SEVERITY_HEADINGS.findIndex((entry) => entry.section === section);
+            const later = lines.findIndex((line) => {
+                const found = todoSeveritySectionForHeading(line);
+                return found !== null && TODO_SEVERITY_HEADINGS.findIndex((entry) => entry.section === found) > order;
+            });
+            if (later >= 0) {
+                lines.splice(later, 0, headingFor(section), "");
+                heading = later;
+            }
+            else {
+                if (lines.at(-1)?.trim())
+                    lines.push("");
+                lines.push(headingFor(section));
+                heading = lines.length - 1;
+            }
         }
         let insert = heading + 1;
         while (insert < lines.length && !/^##\s+/.test(lines[insert].trim()))

package/dist/state/todoReconciliationInspection.js

@@ -76,6 +76,19 @@ function errorCounts(error) {
         ...(diagnosis.omitted_count !== undefined ? { omitted_count: diagnosis.omitted_count } : {}),
     };
 }
+function errorRisks(error) {
+    return error instanceof StateWriteInputError && mapping(error.body.diagnosis) ? error.body.diagnosis : undefined;
+}
+function errorInspection(state, error) {
+    const risks = errorRisks(error);
+    const result = inspection(state, errorCounts(error), risks);
+    if (risks?.classification === "todo_severity_heading_structure" && error instanceof StateWriteInputError) {
+        result.preview_command = null;
+        result.apply_command = null;
+        result.recovery_command = error.body.recovery ?? result.recovery_command;
+    }
+    return result;
+}
 /** Read-only classification shared by prime, doctor, and whole-state validation. */
 export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceRoot(), discovery) {
     try {
@@ -112,7 +125,7 @@ export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceR
             return inspection(safety.safe ? "inactive" : "unsafe_inactive", safety.counts, safety.safe ? undefined : safety.risks);
         }
         catch (error) {
-            return inspection("unsafe_inactive", errorCounts(error));
+            return errorInspection("unsafe_inactive", error);
         }
     }
     try {
@@ -122,7 +135,7 @@ export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceR
         return inspection(unsafe ? "unsafe_active" : "healthy_active", counts);
     }
     catch (error) {
-        return inspection("unsafe_active", errorCounts(error));
+        return errorInspection("unsafe_active", error);
     }
 }
 function publicSnapshot(record, order) {

package/dist/state/todoReconciliationRepair.js

@@ -3,6 +3,7 @@ import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMa
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { reject } from "./write/errors.js";
 import { todoLegacyRowFingerprint, TODO_OWNER_CORRECTION_INPUT_VERSION, TODO_OWNER_CORRECTION_PREVIEW_COMMAND, TODO_REPAIR_PREVIEW_COMMAND } from "./todoReconciliationActivation.js";
+import { assertTodoSeverityHeadingStructure, todoSeveritySectionForHeading } from "./todoSeverityHeadings.js";
 const RECONCILIATION_VERSION = "agentera.todoReconciliation.v1";
 const DIAGNOSTIC_LIMIT = 20;
 function mapping(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
@@ -91,6 +92,7 @@ export function normalizeTodoOwnerCorrectionEvidence(input) {
     };
 }
 function scanRows(markdown) {
+    assertTodoSeverityHeadingStructure(markdown);
     const managed = new Map();
     const legacy = [];
     const order = new Map();
@@ -98,7 +100,7 @@ function scanRows(markdown) {
     markdown.split(/\r?\n/).forEach((line, index) => {
         const heading = line.trim().match(/^##\s+(.+)$/)?.[1]?.toLowerCase();
         if (heading)
-            section = heading.includes("critical") ? "critical" : heading.includes("degraded") ? "degraded" : heading.includes("annoying") ? "annoying" : heading.includes("resolved") ? "resolved" : heading.includes("normal") ? "normal" : heading === "notes" ? null : section;
+            section = todoSeveritySectionForHeading(line) ?? (heading === "notes" ? null : section);
         const item = parseTodoMarkdownListItem(line.trim());
         if (!item)
             return;

package/dist/state/todoSeverityHeadings.js

@@ -0,0 +1,71 @@
+import { reject } from "./write/errors.js";
+export const TODO_SEVERITY_HEADINGS = [
+    { section: "critical", name: "Critical", heading: "## ⇶ Critical" },
+    { section: "degraded", name: "Degraded", heading: "## ⇉ Degraded" },
+    { section: "normal", name: "Normal", heading: "## → Normal" },
+    { section: "annoying", name: "Annoying", heading: "## ⇢ Annoying" },
+    { section: "resolved", name: "Resolved", heading: "## ✓ Resolved" },
+];
+const DIAGNOSTIC_LIMIT = 20;
+const byName = new Map(TODO_SEVERITY_HEADINGS.map((entry) => [entry.name.toLowerCase(), entry]));
+function candidate(line) {
+    const content = line.trim().match(/^##\s+(.+?)\s*$/)?.[1];
+    if (!content)
+        return null;
+    const name = content.match(/^(?:[^\p{L}\p{N}\s]+\s+)?(Critical|Degraded|Normal|Annoying|Resolved)$/iu)?.[1];
+    return name ? byName.get(name.toLowerCase()) ?? null : null;
+}
+export function todoSeveritySectionForHeading(line) {
+    const entry = candidate(line);
+    return entry && line.trim() === entry.heading ? entry.section : null;
+}
+export function inspectTodoSeverityHeadings(markdown) {
+    const diagnostics = [];
+    const seen = new Set();
+    let greatestOrder = -1;
+    for (const [index, line] of markdown.split(/\r?\n/).entries()) {
+        const entry = candidate(line);
+        if (!entry)
+            continue;
+        const order = TODO_SEVERITY_HEADINGS.indexOf(entry);
+        const add = (diagnostic) => { diagnostics.push(diagnostic); };
+        if (line.trim() !== entry.heading)
+            add({
+                code: "todo_severity_heading_mismatch",
+                classification: "glyph_name_mismatch",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: `Replace TODO.md line ${index + 1} with '${entry.heading}'.`,
+            });
+        if (seen.has(entry.section))
+            add({
+                code: "todo_severity_heading_duplicate",
+                classification: "duplicate",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: `Keep exactly one '${entry.heading}' section and move its rows there.`,
+            });
+        if (order < greatestOrder)
+            add({
+                code: "todo_severity_heading_out_of_order",
+                classification: "out_of_order",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: "Order managed TODO sections as Critical, Degraded, Normal, Annoying, then Resolved; missing sections are allowed.",
+            });
+        seen.add(entry.section);
+        greatestOrder = Math.max(greatestOrder, order);
+    }
+    return { diagnostics: diagnostics.slice(0, DIAGNOSTIC_LIMIT), omitted_count: Math.max(0, diagnostics.length - DIAGNOSTIC_LIMIT) };
+}
+export function assertTodoSeverityHeadingStructure(markdown) {
+    const diagnosis = inspectTodoSeverityHeadings(markdown);
+    if (!diagnosis.diagnostics.length)
+        return;
+    reject({
+        class: "conflict",
+        message: "TODO.md managed severity section structure is malformed",
+        diagnosis: { classification: "todo_severity_heading_structure", ...diagnosis },
+        recovery: "Apply every bounded TODO.md heading correction exactly as reported, then retry; no state was changed.",
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentera",
-  "version": "3.0.0-dev.75",
+  "version": "3.0.0-dev.76",
   "description": "One CLI, many capabilities: project state, artifact validation, and capability routing for AI coding agents",
   "keywords": [
     "agentera",
@@ -80,6 +80,6 @@
   },
   "agentera": {
     "suiteVersion": "3.0.0",
-    "gitRef": "01a0c460f2310bae5805a637973021af30960ee5"
+    "gitRef": "70aed21badb985087fd79371fabb61b1ec31ddde"
   }
 }