agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/hooks/compaction/status.js

@@ -1,5 +1,5 @@
 /**
- * Compaction status reporting (read-only).
+ * Compaction status reporting and projection repair.
  *
  * Walks each tracked artifact path, counts active/archive entries, and
  * builds a `CompactionStatus` per artifact plus a per-status operation
@@ -11,13 +11,19 @@ import path from "node:path";
 import { DEFAULT_ARTIFACT_PATHS, parseDocsYamlMapping } from "../common.js";
 import { loadYamlMapping } from "../../core/yaml.js";
 import { COMPACTABLE_YAML_ARTIFACTS, NON_COMPACTABLE_ARTIFACTS } from "./dryRun.js";
-import { decisionProtectedOverflowCount, overLimitCount, yamlArchiveEntries, } from "./retention.js";
-import { compactFile, compactYamlFile } from "./apply.js";
-import { countTodoResolvedEntries } from "./parse.js";
+import { detectStateMode } from "../../state/stateMode.js";
+import { discoverEntities } from "../../state/entityStorage.js";
+import { decisionProtectedOverflowCount, decisionSatisfiedActiveCount, overLimitCount, yamlArchiveEntries, } from "./retention.js";
+import { compactFile, compactYamlBytes, compactYamlFile } from "./apply.js";
+import { countTodoResolvedEntries, countTodoResolvedSectionHeadings, countTodoPendingSummarization, TODO_DROPPED_RECOVERY_GUIDANCE, } from "./parse.js";
 import { YAML_SPEC_BY_ARTIFACT } from "./dryRun.js";
+import { InjectedMutationFailure, withStateMutation, } from "../../state/write/mutation.js";
+import { hydrateDecisionRecords } from "../../state/decisionOverlay.js";
+import { loadProjectionPolicy } from "../../state/projectionPolicy.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "../../registries/artifactProtocolIds.js";
 function artifactPaths(projectRoot) {
     const paths = { ...DEFAULT_ARTIFACT_PATHS };
-    const docsPath = path.join(projectRoot, ".agentera", "docs.yaml");
+    const docsPath = path.join(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs);
     if (fs.existsSync(docsPath)) {
         Object.assign(paths, parseDocsYamlMapping(fs.readFileSync(docsPath, "utf8")));
     }
@@ -71,8 +77,9 @@ function yamlLists(p, activeKey, archiveKey) {
     const archive = data[archiveKey] || [];
     return [Array.isArray(active) ? active : [], Array.isArray(archive) ? archive : []];
 }
-function countStatus(artifact, p, activeCount, archiveCount, protectedOverflowCount = 0) {
+function countStatus(artifact, p, activeCount, archiveCount, protectedOverflowCount = 0, budgetActiveCount, projectionRecovery, projectionState) {
     const totalCount = activeCount + archiveCount;
+    const budgetActive = budgetActiveCount ?? activeCount;
     return {
         artifact,
         path: p,
@@ -80,19 +87,100 @@ function countStatus(artifact, p, activeCount, archiveCount, protectedOverflowCo
         active_count: activeCount,
         archive_count: archiveCount,
         total_count: totalCount,
-        over_limit_count: overLimitCount(activeCount, archiveCount),
-        reason: protectedOverflowCount ? "protected-overflow review pressure" : "uniform_10_40_50",
+        over_limit_count: projectionState ? 0 : overLimitCount(budgetActive, archiveCount),
+        reason: projectionState
+            ? projectionState === "over_defaults"
+                ? "lossless projection exceeds display defaults; numbered archives remain authoritative"
+                : "lossless projection is within display defaults"
+            : protectedOverflowCount
+                ? "protected-overflow review pressure"
+                : "uniform_10_40_50",
         protected_overflow_count: protectedOverflowCount,
         exists: true,
+        ...(projectionState ? { projection_state: projectionState } : {}),
+        ...(projectionRecovery ? { projection_recovery: projectionRecovery } : {}),
     };
 }
+function projectionRecoveryFor(projectRoot, artifact, p) {
+    try {
+        return compactYamlBytes(fs.readFileSync(p, "utf8"), artifact, projectRoot).result.recovery;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function computeCompactionStatus(projectRoot) {
+    if (detectStateMode(projectRoot) === "entities") {
+        const discovered = discoverEntities(projectRoot);
+        const issueCount = discovered.issues.length;
+        return [{
+                artifact: "entity_state",
+                path: path.join(projectRoot, ".agentera", "entities"),
+                classification: issueCount ? "error" : "canonical_entities",
+                active_count: discovered.entities.length,
+                archive_count: 0,
+                total_count: discovered.entities.length,
+                over_limit_count: 0,
+                reason: issueCount
+                    ? `${issueCount} canonical entity validation issue(s); run agentera check validate state --format json`
+                    : "canonical entity state is independently stored and is not compacted",
+                protected_overflow_count: 0,
+                exists: true,
+            }];
+    }
     const paths = artifactPaths(projectRoot);
+    const projectionPolicy = loadProjectionPolicy();
     const statuses = [];
     const todoPath = paths.todo;
     if (fs.existsSync(todoPath)) {
-        const counts = countTodoResolvedEntries(fs.readFileSync(todoPath, "utf8"));
-        statuses.push(countStatus("todo#Resolved", todoPath, counts.full, counts.oneline));
+        const todoText = fs.readFileSync(todoPath, "utf8");
+        const headingCount = countTodoResolvedSectionHeadings(todoText);
+        if (headingCount > 1) {
+            // Refuse rather than silently process only the first `## ✓ Resolved`
+            // section: duplicates hide the trailing entries from the budget and
+            // from fix-mode migration. TODO has no lossless numbered archive, so
+            // recovery once entries are dropped is Git-only.
+            statuses.push({
+                artifact: "todo#Resolved",
+                path: todoPath,
+                classification: "error",
+                active_count: null,
+                archive_count: null,
+                total_count: null,
+                over_limit_count: null,
+                reason: `TODO.md has ${headingCount} '## ✓ Resolved' sections; merge into exactly one before compacting. ` +
+                    `Compaction drops oldest resolved entries and is destructive (no lossless archive); ` +
+                    TODO_DROPPED_RECOVERY_GUIDANCE,
+                protected_overflow_count: 0,
+                exists: true,
+            });
+        }
+        else if (headingCount === 0) {
+            statuses.push({
+                artifact: "todo#Resolved",
+                path: todoPath,
+                classification: "error",
+                active_count: null,
+                archive_count: null,
+                total_count: null,
+                over_limit_count: null,
+                reason: "TODO.md has no required '## ✓ Resolved' section; add exactly one before compacting.",
+                protected_overflow_count: 0,
+                exists: true,
+            });
+        }
+        else {
+            const counts = countTodoResolvedEntries(todoText);
+            const status = countStatus("todo#Resolved", todoPath, counts.full, counts.oneline);
+            // Detect in-budget (≤50) TODOs that still need a formatting rewrite:
+            // rows 11-50 that are long verbatim headers instead of ≤15-word
+            // summaries. This triggers `--mode fix` before entries overflow.
+            const pendingSummarization = countTodoPendingSummarization(todoText);
+            if (pendingSummarization > 0) {
+                status.pending_summarization_count = pendingSummarization;
+            }
+            statuses.push(status);
+        }
     }
     else {
         statuses.push(missingStatus("todo#Resolved", todoPath, "compactable"));
@@ -109,8 +197,17 @@ export function computeCompactionStatus(projectRoot) {
                 statuses.push(yamlErrorStatus(artifact, p, exc.message));
                 continue;
             }
-            const protectedOverflowCount = artifact === "decisions" ? decisionProtectedOverflowCount(active, archive) : 0;
-            statuses.push(countStatus(artifact, p, active.length, archive.length, protectedOverflowCount));
+            const protectedOverflowCount = artifact === "decisions"
+                ? decisionProtectedOverflowCount(hydrateDecisionRecords(active, projectRoot), hydrateDecisionRecords(archive, projectRoot))
+                : 0;
+            const budgetActiveCount = artifact === "decisions"
+                ? decisionSatisfiedActiveCount(hydrateDecisionRecords(active, projectRoot))
+                : undefined;
+            statuses.push(countStatus(artifact, p, active.length, archive.length, protectedOverflowCount, budgetActiveCount, projectionRecoveryFor(projectRoot, artifact, p), active.length > projectionPolicy.activeEntries ||
+                archive.length > projectionPolicy.summaryEntries ||
+                active.length + archive.length > projectionPolicy.totalEntries
+                ? "over_defaults"
+                : "within_defaults"));
         }
         else {
             statuses.push(missingStatus(artifact, p, "compactable"));
@@ -182,21 +279,35 @@ function operationForStatus(status, mode) {
         return base("error", status.reason);
     if (status.classification !== "compactable")
         return base("skipped", status.reason);
-    if (status.protected_overflow_count) {
-        return base("protected_overflow", `protected-overflow review pressure by ${status.protected_overflow_count}`);
+    if (status.projection_recovery?.refused_count) {
+        return base("refused", `projection retained ${status.projection_recovery.retained_full} full entr${status.projection_recovery.retained_full === 1 ? "y" : "ies"}; archive recovery is required before summarization`);
     }
-    if (!status.over_limit_count)
-        return base("ok", "within uniform_10_40_50 limits");
-    return base(mode === "check" ? "over_limit" : "pending_fix", `over uniform_10_40_50 limit by ${status.over_limit_count}`);
+    if (status.projection_state === "over_defaults") {
+        return base(mode === "fix" ? "pending_projection" : "projection", "projection exceeds display defaults; archive history remains lossless");
+    }
+    if (!status.over_limit_count && !status.pending_summarization_count) {
+        return base("ok", status.projection_state === "within_defaults"
+            ? "within configured lossless projection defaults"
+            : "within uniform_10_40_50 limits");
+    }
+    if (status.over_limit_count) {
+        return base(mode === "check" ? "over_limit" : "pending_fix", `over uniform_10_40_50 limit by ${status.over_limit_count}`);
+    }
+    // pending_summarization_count > 0 but within budget: rows 11-50 need
+    // ≤15-word summary formatting, not entry removal.
+    const n = status.pending_summarization_count;
+    return base(mode === "check" ? "formatting" : "pending_formatting", `${n} resolved entr${n === 1 ? "y" : "ies"} in summary tier need ≤15-word summarization`);
 }
 export function checkCompaction(projectRoot) {
     return computeCompactionStatus(projectRoot).map((status) => operationForStatus(status, "check"));
 }
-export function fixCompaction(projectRoot) {
+function fixCompactionUnlocked(projectRoot, transaction) {
     const operations = [];
     for (const status of computeCompactionStatus(projectRoot)) {
         const baseline = operationForStatus(status, "fix");
-        if (baseline.action !== "pending_fix") {
+        if (baseline.action !== "pending_fix" &&
+            baseline.action !== "pending_projection" &&
+            baseline.action !== "pending_formatting") {
             operations.push(baseline);
             continue;
         }
@@ -204,10 +315,10 @@ export function fixCompaction(projectRoot) {
         let result;
         try {
             if (status.artifact === "todo#Resolved") {
-                result = compactFile(p, "todo-resolved");
+                result = transaction.mutateProjection(p, (stage) => compactFile(stage, "todo-resolved"));
             }
             else if (status.artifact in YAML_SPEC_BY_ARTIFACT) {
-                result = compactYamlFile(p, status.artifact);
+                result = transaction.mutateProjection(p, (stage) => compactYamlFile(stage, status.artifact, projectRoot));
             }
             else {
                 operations.push({ status, mode: "fix", action: "skipped", changed: false, result: null, message: `no fixer registered for ${status.artifact}` });
@@ -215,6 +326,8 @@ export function fixCompaction(projectRoot) {
             }
         }
         catch (exc) {
+            if (exc instanceof InjectedMutationFailure)
+                throw exc;
             operations.push({ status, mode: "fix", action: "error", changed: false, result: null, message: exc.message });
             continue;
         }
@@ -226,16 +339,22 @@ export function fixCompaction(projectRoot) {
             result,
             message: `full ${result.full_before}->${result.full_after}; ` +
                 `archive ${result.oneline_before}->${result.oneline_after}; ` +
-                `dropped ${result.dropped}`,
+                `omitted ${result.omitted_count ?? 0}; dropped ${result.dropped}`,
         });
     }
     return operations;
 }
-export function runCompaction(projectRoot, mode = "check") {
+export function fixCompaction(projectRoot, options = {}) {
+    return withStateMutation(projectRoot, (transaction) => fixCompactionUnlocked(projectRoot, transaction), options);
+}
+export function runCompaction(projectRoot, mode = "check", options = {}) {
     if (mode === "check")
         return checkCompaction(projectRoot);
-    if (mode === "fix")
-        return fixCompaction(projectRoot);
+    if (mode === "fix") {
+        if (detectStateMode(projectRoot) === "entities") {
+            return computeCompactionStatus(projectRoot).map((status) => operationForStatus(status, "fix"));
+        }
+        return fixCompaction(projectRoot, options);
+    }
     throw new Error(`unknown compaction mode: ${mode}`);
 }
-//# sourceMappingURL=status.js.map

package/dist/hooks/compaction/types.js

@@ -3,4 +3,3 @@
  * status reporting, the apply writers, and the CLI consumers.
  */
 export {};
-//# sourceMappingURL=types.js.map

package/dist/hooks/validateArtifact/agentFacing.js

@@ -7,4 +7,3 @@
 import { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS } from "../../registries/artifactProtocolIds.js";
 export { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS };
 export const AGENT_FACING_ARTIFACT_IDS = new Set(Object.keys(ARTIFACT_PROTOCOL_PATHS).filter((id) => !HUMAN_FACING_ARTIFACT_IDS.has(id)));
-//# sourceMappingURL=agentFacing.js.map

package/dist/hooks/validateArtifact/index.js

@@ -1,9 +1,6 @@
 /**
- * Public surface for the validate-artifact hook. The CLI command
- * (`packages/cli/src/cli/commands/validate.ts`), the smoke checks, and
- * the dispatch entry all import the public classes from this barrel
- * to keep import paths stable as the file is split across the
- * per-responsibility submodules.
+ * Artifact validation used by the explicit `agentera check validate artifact`
+ * command and state publication.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -11,10 +8,8 @@ import { loadYamlMapping } from "../../core/yaml.js";
 import { resolvePath } from "../../core/paths.js";
 import { normalizeArtifactProtocolId } from "../../registries/artifactProtocolIds.js";
 import { DEFAULT_ARTIFACT_PATHS } from "../common.js";
-import { ArtifactWrite, RuntimeEventParser } from "./runtime.js";
-import { isMapping } from "./schema.js";
 import { validateMd } from "./markdown.js";
-import { artifactForWrite, defaultArtifactPath, readIfNeeded, compactAfterValidWrite, } from "./traversal.js";
+import { defaultArtifactPath, readIfNeeded, } from "./traversal.js";
 import { schemasDirDefault, validateYamlContent } from "./violations.js";
 import { AGENT_FACING_ARTIFACT_IDS, HUMAN_FACING_ARTIFACT_IDS } from "./agentFacing.js";
 export class ArtifactSchemaValidator {
@@ -43,37 +38,6 @@ export class ArtifactSchemaValidator {
     validateMarkdown(content, name, schema = null) {
         return validateMd(content, name, schema);
     }
-    validateWrite(write, cwd) {
-        const absPath = path.isAbsolute(write.file_path) ? write.file_path : path.join(cwd, write.file_path);
-        const rel = path.relative(cwd, absPath).replace(/\\/g, "/");
-        const basename = path.basename(absPath);
-        const artifact = artifactForWrite(absPath, rel, basename, cwd);
-        if (artifact && AGENT_FACING_ARTIFACT_IDS.has(artifact)) {
-            const schema = this.loadSchema(artifact);
-            if (schema === null)
-                return [];
-            if (Object.keys(schema).length === 0)
-                return [`${artifact}: schema file is empty or contains no valid definitions`];
-            const content = readIfNeeded(write.content, absPath);
-            if (content === null)
-                return [];
-            let violations = this.validateYaml(content, schema, artifact);
-            if (violations.length > 0)
-                return violations;
-            return compactAfterValidWrite(artifact, absPath);
-        }
-        if (artifact && HUMAN_FACING_ARTIFACT_IDS.has(artifact)) {
-            const content = readIfNeeded(write.content, absPath);
-            if (content === null)
-                return [];
-            const schema = this.loadSchema(artifact);
-            const violations = this.validateMarkdown(content, artifact, schema);
-            if (violations.length > 0)
-                return violations;
-            return compactAfterValidWrite(artifact, absPath);
-        }
-        return [];
-    }
     validateExplicit(artifact, filePath, cwd) {
         const content = readIfNeeded(null, filePath);
         if (content === null)
@@ -103,33 +67,11 @@ export class ArtifactSchemaValidator {
 export function loadSchema(name) {
     return new ArtifactSchemaValidator().loadSchema(name);
 }
-export class HookCliAdapter {
-    parser;
+export class ArtifactValidationAdapter {
     validator;
-    constructor(parser, validator) {
-        this.parser = parser ?? new RuntimeEventParser();
+    constructor(validator) {
         this.validator = validator ?? new ArtifactSchemaValidator();
     }
-    run(raw, defaultCwd = null) {
-        let data;
-        try {
-            if (!raw.trim())
-                return [0, []];
-            data = JSON.parse(raw);
-        }
-        catch {
-            return [0, []];
-        }
-        if (!isMapping(data))
-            return [0, []];
-        const write = this.parser.parse(data);
-        if (write === null)
-            return [0, []];
-        // cast: cwd read from the runtime hook's JSON stdin payload
-        const cwd = (data.cwd ?? defaultCwd ?? process.cwd());
-        const violations = this.validator.validateWrite(write, cwd);
-        return violations.length > 0 ? [2, violations] : [0, []];
-    }
     runExplicit(artifact, filePath, cwd) {
         artifact = artifact.trim();
         const defaultPath = defaultArtifactPath(artifact, cwd);
@@ -147,5 +89,4 @@ export class HookCliAdapter {
         return violations.length > 0 ? [2, payload] : [0, payload];
     }
 }
-export { ArtifactWrite, RuntimeEventParser, resolvePath };
-//# sourceMappingURL=index.js.map
+export { resolvePath };

package/dist/hooks/validateArtifact/markdown.js

@@ -5,18 +5,14 @@
  * section check (ITEM, RELEASE, TOKEN).
  */
 import { parseTodoMarkdownListItem } from "../../cli/todoMarkdown.js";
-import { classifyTodoSectionHeading, isLegacyStrikethroughTodoLine, } from "../compaction/parse.js";
+import { classifyTodoSectionHeading, countTodoResolvedSectionHeadings, isLegacyStrikethroughTodoLine, } from "../compaction/parse.js";
 import { isMapping } from "./schema.js";
-const TODO_RESOLVED_HEADING_RE = /^##\s*(?:✓\s+)?Resolved\s*$/im;
 function validateTodoResolvedPlacement(content, name) {
     const violations = [];
     let section = "other";
-    let hasResolvedHeading = TODO_RESOLVED_HEADING_RE.test(content);
-    let hasResolvedItems = false;
     for (const line of content.split(/\r\n|\r|\n/)) {
         const kind = classifyTodoSectionHeading(line);
         if (kind === "resolved") {
-            hasResolvedHeading = true;
             section = "resolved";
             continue;
         }
@@ -33,20 +29,24 @@ function validateTodoResolvedPlacement(content, name) {
             continue;
         const parsed = parseTodoMarkdownListItem(trimmed);
         if (parsed?.status === "resolved") {
-            hasResolvedItems = true;
             if (section === "severity") {
                 violations.push(`${name}: resolved checkbox item must live under '## ✓ Resolved', not in severity bands`);
                 break;
             }
         }
         if (isLegacyStrikethroughTodoLine(trimmed)) {
-            hasResolvedItems = true;
             violations.push(`${name}: legacy strikethrough resolved items are not allowed; use '- [x]' under '## ✓ Resolved'`);
             break;
         }
     }
-    if (hasResolvedItems && !hasResolvedHeading) {
-        violations.push(`${name}: missing '## ✓ Resolved' section for resolved items`);
+    // Exactly one section keeps parsing and compaction unambiguous, including
+    // before the first item is resolved. See todo.yaml TC8.
+    const resolvedHeadingCount = countTodoResolvedSectionHeadings(content);
+    if (resolvedHeadingCount === 0) {
+        violations.push(`${name}: missing required '## ✓ Resolved' section`);
+    }
+    else if (resolvedHeadingCount > 1) {
+        violations.push(`${name}: ${resolvedHeadingCount} '## ✓ Resolved' sections found; merge into exactly one (duplicate sections hide entries from the compaction gate and parsing processes only the first).`);
     }
     return violations;
 }
@@ -143,4 +143,3 @@ export function validateMdTokens(content, name, violations) {
         violations.push(`${name}: missing YAML code block with token definitions (expected '\`\`\`yaml')`);
     }
 }
-//# sourceMappingURL=markdown.js.map

package/dist/hooks/validateArtifact/schema.js

@@ -28,18 +28,28 @@ export function pyTypeName(v) {
 export function wordCount(text) {
     return (text.match(/\S+/g) ?? []).length;
 }
-const SKIP_META = new Set(["meta", "GROUP_PREFIXES", "BUDGET", "COMPACTION", "VALIDATION", "CONVENTION"]);
+const SKIP_META = new Set([
+    "meta",
+    "GROUP_PREFIXES",
+    "BUDGET",
+    "COMPACTION",
+    "VALIDATION",
+    "CONVENTION",
+]);
 const LIST_INDICATORS = new Set(["number", "entry", "summary"]);
 const SEQUENCE_KEYS_BY_ARTIFACT = {
     decisions: { DECISION: "decisions", ARCHIVE: "archive" },
     docs: { MAPPING: "mapping", INDEX: "index", AUDIT_LOG: "audit_log" },
     experiments: { EXPERIMENT: "experiments", ARCHIVE: "archive" },
-    plan: { TASK: "tasks" },
+    health: { AUDIT: "audits", ARCHIVE: "archive" },
+    plan: { TASK: "tasks", UNKNOWN: "unknowns", REJECTED: "rejected" },
     progress: { CYCLE: "cycles", ARCHIVE: "archive" },
     session: { BOOKMARK: "bookmarks" },
     vision: { PERSONA: "personas", PRINCIPLE: "principles" },
 };
-const NESTED_SEQUENCE_KEYS = [[["DECISION", "ALTERNATIVE"], "alternatives"]];
+const NESTED_SEQUENCE_KEYS = [
+    [["DECISION", "ALTERNATIVE"], "alternatives"],
+];
 const SEQUENCE_ORDER_BY_ARTIFACT = { "progress\0cycles": "descending" };
 export function collectSingletonGroups(schema) {
     const result = [];
@@ -98,7 +108,10 @@ export function allowedValues(entry) {
     // cast: schema `validation` rules parsed from a YAML artifact schema file
     for (const rule of entry.validation ?? []) {
         if (typeof rule === "string" && rule.startsWith("Must be one of: ")) {
-            return rule.slice("Must be one of: ".length).split(",").map((v) => v.trim());
+            return rule
+                .slice("Must be one of: ".length)
+                .split(",")
+                .map((v) => v.trim());
         }
     }
     return [];
@@ -147,6 +160,12 @@ export function validateFieldType(violations, name, scope, entry, p) {
             isValid = false;
         }
     }
+    else if (expectedType === "list[integer|string]") {
+        if (!Array.isArray(value) || !value.every((x) => typeof x === "string" || (typeof x === "number" && Number.isInteger(x)))) {
+            violations.push(`${name}: '${fullPath}' must be a list of integers or strings`);
+            isValid = false;
+        }
+    }
     else if (expectedType === "list[map]") {
         if (!Array.isArray(value) || !value.every((x) => isMapping(x))) {
             violations.push(`${name}: '${fullPath}' must be a list of mappings`);
@@ -165,7 +184,9 @@ export function validateFieldConstraints(violations, name, scope, entry, p) {
         if (typeof rule !== "string")
             continue;
         if (rule === "Must be a positive integer") {
-            if (typeof value === "boolean" || !(typeof value === "number" && Number.isInteger(value)) || value <= 0) {
+            if (typeof value === "boolean" ||
+                !(typeof value === "number" && Number.isInteger(value)) ||
+                value <= 0) {
                 const fullPath = p ? `${p}.${field}` : field;
                 violations.push(`${name}: '${fullPath}' must be a positive integer`);
             }
@@ -260,6 +281,10 @@ export function validateFullPlanContract(data, violations) {
         validateField(violations, "plan", header, field, "header");
     }
     validateField(violations, "plan", data, "design", "");
+    const unknowns = data.unknowns;
+    if (!Array.isArray(unknowns) || unknowns.length === 0) {
+        violations.push("plan: full plans require at least one 'unknowns' entry");
+    }
     const criticIssues = header.critic_issues;
     if (!isEmptyRequired(criticIssues)) {
         const match = /^\s*(\d+)\s+found,\s*(\d+)\s+addressed,\s*(\d+)\s+dismissed\s*$/.exec(String(criticIssues));
@@ -304,7 +329,9 @@ export function parentRequirements(schema, parentGroup) {
                 entry.required &&
                 entry.field) {
                 const parentField = parent.slice(prefix.length);
-                (requirements[parentField] ??= []).push(String(entry.field));
+                const fields = requirements[parentField] ?? [];
+                fields.push(String(entry.field));
+                requirements[parentField] = fields;
             }
         }
     }
@@ -335,6 +362,8 @@ export function validateSequences(data, schema, name, violations) {
         const childRequirements = parentRequirements(schema, group);
         seq.forEach((item, index) => {
             const p = `${key}[${index}]`;
+            if (name === "health" && group === "ARCHIVE" && typeof item === "string")
+                return;
             if (!isMapping(item)) {
                 violations.push(`${name}: '${p}' must be a mapping`);
                 return;
@@ -373,6 +402,59 @@ export function validateSequences(data, schema, name, violations) {
         });
     }
 }
+export function validatePlanDependencies(data, violations) {
+    if (!Array.isArray(data.tasks))
+        return;
+    const tasks = data.tasks.filter((task) => isMapping(task));
+    const byRef = new Map();
+    tasks.forEach((task, index) => {
+        if (task.number !== null && task.number !== undefined)
+            byRef.set(String(task.number), index);
+        const name = String(task.name ?? "").trim();
+        if (name && !byRef.has(name))
+            byRef.set(name, index);
+    });
+    const edges = tasks.map(() => []);
+    tasks.forEach((task, index) => {
+        if (!Array.isArray(task.depends_on))
+            return;
+        for (const dependency of task.depends_on) {
+            const dependencyRef = String(dependency);
+            const target = byRef.get(dependencyRef);
+            if (target === undefined) {
+                violations.push(`plan: 'tasks[${index}].depends_on' references unknown task '${dependencyRef}' (PV4)`);
+            }
+            else {
+                edges[index].push(target);
+            }
+        }
+    });
+    const state = tasks.map(() => 0);
+    const stack = [];
+    const visit = (index) => {
+        state[index] = 1;
+        stack.push(index);
+        for (const target of edges[index]) {
+            if (state[target] === 0 && visit(target))
+                return true;
+            if (state[target] === 1) {
+                const cycleStart = stack.indexOf(target);
+                const cycle = [...stack.slice(cycleStart), target]
+                    .map((taskIndex) => String(tasks[taskIndex]?.number ?? taskIndex + 1))
+                    .join(" -> ");
+                violations.push(`plan: circular dependency chain ${cycle} (PV4)`);
+                return true;
+            }
+        }
+        stack.pop();
+        state[index] = 2;
+        return false;
+    };
+    for (let index = 0; index < tasks.length; index += 1) {
+        if (state[index] === 0 && visit(index))
+            break;
+    }
+}
 export function validateDecisionAlternatives(data, name) {
     const violations = [];
     // cast: `decisions` read from a parsed YAML artifact mapping
@@ -393,8 +475,14 @@ export function validateDecisionSatisfaction(data, name) {
     const violations = [];
     const allowedStates = new Set(["open", "provisionally_satisfied", "user_confirmed_satisfied"]);
     const entries = [
-        ...(data.decisions ?? []).map((d, i) => [`decisions[${i}]`, d]),
-        ...(data.archive ?? []).map((d, i) => [`archive[${i}]`, d]),
+        ...(data.decisions ?? []).map((d, i) => [
+            `decisions[${i}]`,
+            d,
+        ]),
+        ...(data.archive ?? []).map((d, i) => [
+            `archive[${i}]`,
+            d,
+        ]),
     ];
     for (const [entryPath, decision] of entries) {
         if (!isMapping(decision) || !("satisfaction" in decision))
@@ -456,4 +544,3 @@ export function sequenceInOrder(nums, direction) {
     const sorted = [...nums].sort((a, b) => (reverse ? b - a : a - b));
     return nums.length === sorted.length && nums.every((n, i) => n === sorted[i]);
 }
-//# sourceMappingURL=schema.js.map

package/dist/hooks/validateArtifact/traversal.js

@@ -12,13 +12,14 @@ import { loadYamlMapping } from "../../core/yaml.js";
 import { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS, normalizeArtifactProtocolId, } from "../../registries/artifactProtocolIds.js";
 import { DEFAULT_ARTIFACT_PATHS } from "../common.js";
 import { COMPACTABLE_YAML_ARTIFACTS, compactFile, compactYamlFile } from "../compaction/index.js";
+import { withStateMutation } from "../../state/write/mutation.js";
 import { isMapping } from "./schema.js";
 const AGENT_YAML_RE = /\.agentera\/([a-z_]+)\.yaml$/;
 function resolvePathRel(fp, cwd) {
     return path.isAbsolute(fp) ? fp : path.join(cwd, fp);
 }
 function docsPathOverrides(cwd) {
-    const docsPath = path.join(cwd, ".agentera", "docs.yaml");
+    const docsPath = path.join(cwd, ARTIFACT_PROTOCOL_PATHS.docs);
     if (!fs.existsSync(docsPath) || !fs.statSync(docsPath).isFile())
         return {};
     let data;
@@ -83,19 +84,20 @@ function readIfNeeded(content, absPath) {
         return null;
     }
 }
-function compactAfterValidWrite(artifact, absPath) {
+function compactAfterValidWrite(artifact, absPath, projectRoot) {
     if (!fs.existsSync(absPath))
         return [];
     try {
-        if (artifact === "todo") {
-            compactFile(absPath, "todo-resolved");
-        }
-        else if (artifact in COMPACTABLE_YAML_ARTIFACTS) {
-            compactYamlFile(absPath, artifact);
-        }
-        else {
+        if (artifact !== "todo" && !(artifact in COMPACTABLE_YAML_ARTIFACTS))
             return [];
-        }
+        withStateMutation(projectRoot, (transaction) => {
+            if (artifact === "todo") {
+                transaction.mutateProjection(absPath, (stage) => compactFile(stage, "todo-resolved"));
+            }
+            else {
+                transaction.mutateProjection(absPath, (stage) => compactYamlFile(stage, artifact, projectRoot));
+            }
+        });
     }
     catch (exc) {
         return [`${artifact}: compaction failed: ${exc.message}`];
@@ -103,4 +105,3 @@ function compactAfterValidWrite(artifact, absPath) {
     return [];
 }
 export { readIfNeeded, compactAfterValidWrite };
-//# sourceMappingURL=traversal.js.map