agentera 3.0.0-dev.47 → 3.0.0-dev.51

package/dist/state/todoDocsEntities.js

@@ -18,9 +18,10 @@ import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMa
 import { evaluateTodoReadinessQueue } from "../cli/todoReadinessSelection.js";
 import { artifactSchemasDir, loadArtifactRecord, registryModelPath, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { inspectTodoReconciliation, publishTodoReconciliation, recoverTodoReconciliation, todoCreateRequestSha256 } from "./todoReconciliationTransaction.js";
-import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, todoActivationEffect, todoRepairEffect, unchangedTodoActivationEffect, } from "./todoReconciliationActivation.js";
+import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_ACTIVATION_RISK_LIMIT, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, todoActivationEffect, todoRepairEffect, unchangedTodoActivationEffect, } from "./todoReconciliationActivation.js";
 import { planTodoRepair } from "./todoReconciliationRepair.js";
 import { readTodoMarkdown, renderManagedMarkdown } from "./todoMarkdownProjection.js";
+import { inactiveTodoActivationSafety, rejectUnsafeInactiveTodoActivation, unsafeInactiveDuplicateDiagnosis } from "./todoActivationSafety.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" };
@@ -194,11 +195,20 @@ export function managedRows(markdown, activation, entities) {
         if (ambiguous)
             reject({
                 class: "conflict",
-                message: `pre-activation TODO contains identical ID-less managed rows at lines ${ambiguous.map((row) => row.line + 1).join(", ")}`,
+                message: `pre-activation TODO contains identical ID-less managed rows at lines ${ambiguous.slice(0, TODO_ACTIVATION_RISK_LIMIT).map((row) => row.line + 1).join(", ")}${ambiguous.length > TODO_ACTIVATION_RISK_LIMIT ? `; ${ambiguous.length - TODO_ACTIVATION_RISK_LIMIT} additional lines omitted` : ""}`,
+                diagnosis: unsafeInactiveDuplicateDiagnosis(),
                 recovery: "Give each identical row its distinct canonical '[id:abcdefghij]' tag or remove the duplicate, then retry once; no state was changed.",
             });
         const claimed = new Set(result.keys());
         for (const row of legacy) {
+            const duplicate = entities.find((entity) => entity.boundary === TODO.boundary && entity.id && entity.record && claimed.has(entity.id) && samePublic(publicSnapshot(entity.record), rowSnapshot({ ...row, id: entity.id }, entity.record), false));
+            if (duplicate)
+                reject({
+                    class: "conflict",
+                    message: `pre-activation TODO row at line ${row.line + 1} duplicates canonical public work`,
+                    diagnosis: unsafeInactiveDuplicateDiagnosis(),
+                    recovery: "Restore exactly one public row for each canonical entity before activation, then retry once; no state was changed.",
+                });
             const matches = entities.filter((entity) => {
                 if (entity.boundary !== TODO.boundary || !entity.id || !entity.record || claimed.has(entity.id))
                     return false;
@@ -208,6 +218,7 @@ export function managedRows(markdown, activation, entities) {
                 reject({
                     class: "conflict",
                     message: `pre-activation TODO row at line ${row.line + 1} matches multiple canonical entities`,
+                    diagnosis: unsafeInactiveDuplicateDiagnosis(matches.length),
                     recovery: `Add one exact '[id:abcdefghij]' tag to TODO.md line ${row.line + 1} and retry once; no state was changed.`,
                 });
             const matched = matches[0];
@@ -222,6 +233,7 @@ export function managedRows(markdown, activation, entities) {
                 reject({
                     class: "conflict",
                     message: `pre-activation TODO contains duplicate unmatched legacy rows at line ${row.line + 1}`,
+                    diagnosis: unsafeInactiveDuplicateDiagnosis(),
                     recovery: `Give each duplicate row a distinct canonical '[id:abcdefghij]' tag or move it outside managed sections, then retry once; no state was changed.`,
                 });
             retainedLegacyRows.push(fingerprint);
@@ -379,13 +391,8 @@ export function projectTodoReadEntities(root, sourceRoot = resolveSourceRoot(),
         };
     });
 }
-function publicReadRecord(record, row) {
-    return row ? importMarkdown(record, row) : record;
-}
-function publicReadMetadata(record, row) {
-    const value = row ? rowSnapshot(row, record) : { present: false };
-    return { ...value, owner: "markdown", source: "TODO.md" };
-}
+function publicReadRecord(record, row) { return row ? importMarkdown(record, row) : record; }
+function publicReadMetadata(record, row) { const value = row ? rowSnapshot(row, record) : { present: false }; return { ...value, owner: "markdown", source: "TODO.md" }; }
 function importMarkdown(record, row) {
     const result = structuredClone(record);
     const description = row.item.public_description ?? row.item.description;
@@ -401,16 +408,11 @@ function importMarkdown(record, row) {
     result.status = row.item.status;
     return result;
 }
-function withBaseline(record, value) {
-    const publicValue = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
-    return { ...record, reconciliation: { schema_version: RECONCILIATION_VERSION, public: publicValue } };
-}
+function withBaseline(record, value) { const publicValue = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined)); return { ...record, reconciliation: { schema_version: RECONCILIATION_VERSION, public: publicValue } }; }
 function inactiveTodoMutation() { reject({ class: "conflict", message: "TODO reconciliation is inactive; ordinary TODO mutations cannot activate it implicitly", syntax: TODO_ACTIVATION_PREVIEW_COMMAND, example: TODO_ACTIVATION_APPLY_COMMAND, recovery: `Run exactly '${TODO_ACTIVATION_PREVIEW_COMMAND}', review every reported effect, then run exactly '${TODO_ACTIVATION_APPLY_COMMAND}'; no state was changed.` }); }
 function activationEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo activate", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "activate", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, activation: effect, apply_command: TODO_ACTIVATION_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
 function repairEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo repair", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "repair", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, repair: effect, apply_command: TODO_REPAIR_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
-function envelope(command, entity, artifact, record, dryRun) {
-    return { schemaVersion: "agentera.stateWrite.v1", command, status: "pass", path: entity.path, id: entity.id, artifact, record, operation: { verb: command.split(" ").at(-1), dry_run: dryRun, idempotent_replay: entity.replay }, validation: { status: "pass", violations: [] } };
-}
+function envelope(command, entity, artifact, record, dryRun) { return { schemaVersion: "agentera.stateWrite.v1", command, status: "pass", path: entity.path, id: entity.id, artifact, record, operation: { verb: command.split(" ").at(-1), dry_run: dryRun, idempotent_replay: entity.replay }, validation: { status: "pass", violations: [] } }; }
 function targetPath(root, sourceRoot, artifact, id) {
     const model = definition(artifact);
     return path.join(root, contract(model.boundary, sourceRoot).entityRoot, artifact, model.boundary, `${id}.yaml`);
@@ -718,6 +720,9 @@ export function mutateTodoDocsEntity(req, options = {}) {
                 }
                 const scan = managedRows(markdown, null, todoEntities);
                 const rows = scan.rows;
+                const safety = inactiveTodoActivationSafety(scan, todoEntities);
+                if (!safety.safe)
+                    rejectUnsafeInactiveTodoActivation(safety);
                 const reconciled = reconcileTodoRecords(todoEntities, rows, true);
                 for (const [todoId, record] of reconciled.records) {
                     const violations = recordViolations("todo", record, sourceRoot);
@@ -738,7 +743,7 @@ export function mutateTodoDocsEntity(req, options = {}) {
                 const targets = todoEntities.map((entity) => ({ path: entity.relativePath, before: exactDiscoveredEntityBytes(entity), after: canonicalEntityEnvelopeBytes({ id: entity.id, artifact: "todo", record: reconciled.records.get(entity.id), migrationProvenance: entity.migrationProvenance ?? undefined }) }));
                 targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: activationBytesAfter });
                 targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: rendered });
-                const resurrectedIds = [...reconciled.visible].filter((todoId) => { const row = rows.get(todoId); return !row || (reconciled.records.get(todoId)?.status === "resolved" && !row.item.id); }).sort();
+                const resurrectedIds = safety.resurrectedIds;
                 const preliminaryEffect = todoActivationEffect(scan, targets, publicRelative, markdownBefore, rendered, resurrectedIds);
                 activationBytesAfter = todoReconciliationActivationBytes(scan.retainedLegacyRows, String(preliminaryEffect.effect_sha256));
                 targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH).after = activationBytesAfter;

package/dist/state/todoReconciliationActivation.js

@@ -13,7 +13,8 @@ export const TODO_ACTIVATION_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} sta
 export const TODO_ACTIVATION_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json`;
 export const TODO_REPAIR_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --dry-run --format json`;
 export const TODO_REPAIR_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json`;
-const CHANGE_LIMIT = 20;
+export const TODO_UNSAFE_INACTIVE_RECOVERY = "Owner correction required: restore Markdown-owned public rows and Agentera-owned entity status to exact one-to-one pre-activation evidence. Do not activate or repair. If a correction needs a mutation, stop and request replanning; no state was changed.";
+export const TODO_ACTIVATION_RISK_LIMIT = 20;
 function activationFailure(message) {
     reject({
         class: "conflict",
@@ -74,6 +75,13 @@ export function loadTodoReconciliationActivation(root) {
     return { record: record, bytes };
 }
 function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+export function todoActivationRisks(resurrectedIds) {
+    return {
+        resurrected_count: resurrectedIds.length,
+        resurrected_ids: resurrectedIds.slice(0, TODO_ACTIVATION_RISK_LIMIT),
+        omitted_count: Math.max(0, resurrectedIds.length - TODO_ACTIVATION_RISK_LIMIT),
+    };
+}
 function boundedPublicChanges(before, after) {
     const beforeLines = before.split(/\r?\n/);
     const afterLines = after.split(/\r?\n/);
@@ -83,7 +91,7 @@ function boundedPublicChanges(before, after) {
         if (beforeLines[index] === afterLines[index])
             continue;
         count += 1;
-        if (changes.length < CHANGE_LIMIT)
+        if (changes.length < TODO_ACTIVATION_RISK_LIMIT)
             changes.push({ line: index + 1, before: (beforeLines[index] ?? "").slice(0, 240), after: (afterLines[index] ?? "").slice(0, 240) });
     }
     return { count, items: changes, omitted_count: count - changes.length };
@@ -93,13 +101,13 @@ export function todoActivationEffect(scan, targets, publicPath, markdownBefore,
     const evidence = {
         counts: { matched: scan.matchedRows, converted: scan.convertedRows, retained: scan.retainedLegacyRows.length, conflicting: 0 }, targets: changedTargets,
         public_document: { path: publicPath, changed: !markdownBefore.equals(Buffer.from(rendered)), before_bytes: markdownBefore.length, after_bytes: Buffer.byteLength(rendered), before_sha256: sha256(markdownBefore), after_sha256: sha256(rendered), changed_lines: boundedPublicChanges(markdownBefore.toString("utf8"), rendered) },
-        risks: { resurrected_count: resurrectedIds.length, resurrected_ids: resurrectedIds.slice(0, CHANGE_LIMIT), omitted_count: Math.max(0, resurrectedIds.length - CHANGE_LIMIT) },
+        risks: todoActivationRisks(resurrectedIds),
     };
     const authorizedTargets = changedTargets.map((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH ? { ...target, after_sha256: "activation_effect_authorization" } : target);
     return { ...evidence, effect_sha256: sha256(canonicalRecordJson({ ...evidence, targets: authorizedTargets })) };
 }
 export function unchangedTodoActivationEffect(publicPath, markdown, retained, authorizedEffectSha256) {
-    const evidence = { counts: { matched: 0, converted: 0, retained, conflicting: 0 }, targets: [], public_document: { path: publicPath, changed: false, before_bytes: markdown.length, after_bytes: markdown.length, before_sha256: sha256(markdown), after_sha256: sha256(markdown), changed_lines: { count: 0, items: [], omitted_count: 0 } }, risks: { resurrected_count: 0, resurrected_ids: [], omitted_count: 0 } };
+    const evidence = { counts: { matched: 0, converted: 0, retained, conflicting: 0 }, targets: [], public_document: { path: publicPath, changed: false, before_bytes: markdown.length, after_bytes: markdown.length, before_sha256: sha256(markdown), after_sha256: sha256(markdown), changed_lines: { count: 0, items: [], omitted_count: 0 } }, risks: todoActivationRisks([]) };
     return { ...evidence, effect_sha256: authorizedEffectSha256 ?? sha256(canonicalRecordJson(evidence)) };
 }
 export function todoRepairEffect(diagnosis, targets, publicPath, markdownBefore, rendered) {

package/dist/state/todoReconciliationInspection.js

@@ -5,9 +5,10 @@ import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { detectStateMode } from "./stateMode.js";
 import { StateWriteInputError } from "./write/errors.js";
-import { TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
+import { TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, TODO_UNSAFE_INACTIVE_RECOVERY, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
 import { planTodoRepair } from "./todoReconciliationRepair.js";
 import { readTodoMarkdown } from "./todoMarkdownProjection.js";
+import { inactiveTodoActivationSafety } from "./todoActivationSafety.js";
 import { managedRows, relevant, todoPublicPath } from "./todoDocsEntities.js";
 const DIAGNOSTIC_LIMIT = 20;
 function mapping(value) {
@@ -43,7 +44,7 @@ function invalidLifecycle() {
         recovery_command: "Restore the valid committed TODO reconciliation lifecycle metadata, then rerun `npx -y agentera@next check validate state --format json`; no state was changed.",
     };
 }
-function inspection(state, rawCounts) {
+function inspection(state, rawCounts, risks) {
     const bounded = boundedCounts(rawCounts);
     const active = state === "healthy_active" || state === "unsafe_active";
     const preview = state === "inactive" ? TODO_ACTIVATION_PREVIEW_COMMAND : active ? TODO_REPAIR_PREVIEW_COMMAND : null;
@@ -60,9 +61,10 @@ function inspection(state, rawCounts) {
             conflicting: bounded.conflicting,
         },
         omitted_count: bounded.omitted,
+        ...(risks === undefined ? {} : { risks }),
         preview_command: preview,
         apply_command: apply,
-        recovery_command: preview && apply ? recovery(preview, apply) : "",
+        recovery_command: state === "unsafe_inactive" ? TODO_UNSAFE_INACTIVE_RECOVERY : preview && apply ? recovery(preview, apply) : "",
     };
 }
 function errorCounts(error) {
@@ -104,17 +106,11 @@ export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceR
     if (!activation) {
         try {
             const scan = managedRows(readTodoMarkdown(todoPublicPath(root, sourceRoot)).text, null, entities);
-            const entityIds = new Set(entities.map(({ id }) => id));
-            const orphaned = [...scan.rows.keys()].filter((id) => !entityIds.has(id)).length;
-            return inspection("inactive", {
-                matched: scan.matchedRows,
-                converted: scan.convertedRows,
-                retained: scan.retainedLegacyRows.length,
-                conflicting: orphaned,
-            });
+            const safety = inactiveTodoActivationSafety(scan, entities);
+            return inspection(safety.safe ? "inactive" : "unsafe_inactive", safety.counts, safety.safe ? undefined : safety.risks);
         }
         catch (error) {
-            return inspection("inactive", errorCounts(error));
+            return inspection("unsafe_inactive", errorCounts(error));
         }
     }
     try {

package/dist/state/write/explain.js

@@ -70,6 +70,7 @@ function inputProjection(spec) {
     return {
         mode: spec.inputMode,
         ...(spec.inputRoot ? { root: spec.inputRoot } : {}),
+        ...(spec.inputOptional ? { optional: true } : {}),
         sources: spec.inputSources,
         structured_sources: spec.structuredInputSources,
         cli_owned_fields: spec.cliOwnedFields,
@@ -112,6 +113,14 @@ export function buildExplain(artifact, projectRoot, requestedVerb) {
         recovery: declaration.recovery,
         examples: declaration.examples,
         bounds: declaration.bounds,
+        allow_force: spec.allowForce,
+        ...(spec.allowForce ? {
+            force_semantics: artifact === "plan" && verb === "create"
+                ? "With exactly one canonical open predecessor, --force archives it unchanged and publishes a successor whose previous_plan_archived field contains the predecessor's bare ID. Multiple open predecessors are rejected."
+                : artifact === "plan" && verb === "archive"
+                    ? "--force archives an open selected plan without changing task, evaluation, or completion history. An implicit archive rejects multiple open candidates."
+                    : "--force is accepted only where the operation's locked canonical-state decision permits it.",
+        } : {}),
         next: {},
         budget: schemaBudget(artifact, validator),
         fields: exposedFields(artifact, verb, spec, validator),
@@ -227,7 +236,14 @@ function decisionsGuidance(artifact, verb, _entityHealth = false, entityArtifact
             ...base,
         ];
     if (entityArtifact && artifact === "plan" && verb === "create")
-        return ["the CLI assigns bare ten-letter envelope IDs to the plan and each task and publishes one canonical file per entity", "task numbers and dependency values in this atomic input are create-local symbolic ordinals; the writer removes them and resolves dependencies to bare task IDs", "legacy composite header.id values are migration-only and never public selectors", ...base];
+        return [
+            "the CLI assigns bare ten-letter envelope IDs to the plan and each task and publishes one canonical file per entity",
+            "task numbers and dependency values in this atomic input are create-local symbolic ordinals; the writer removes them and resolves dependencies to bare task IDs",
+            "legacy composite header.id values are migration-only and never public selectors",
+            "without --force, an open plan blocks creation; with exactly one open predecessor, --force archives it unchanged and writes its bare ID to successor.previous_plan_archived",
+            "multiple open predecessors reject before effects; preview and apply derive the same lifecycle decision under the writer lock",
+            ...base,
+        ];
     if (entityArtifact && artifact === "plan" && verb === "record-evaluation")
         return [
             "select one task entity with its bare ten-letter --id; numeric and composite selectors are unavailable",
@@ -250,6 +266,19 @@ function decisionsGuidance(artifact, verb, _entityHealth = false, entityArtifact
         return ["select one task entity with its bare ten-letter --id; lifecycle status is a flag-only transition", ...base];
     if (entityArtifact && artifact === "plan" && verb === "append")
         return ["the CLI assigns a bare ten-letter ID to the new task entity", "supply one complete YAML/JSON task record through --input; dependencies must be bare ten-letter IDs in the selected plan", ...base];
+    if (entityArtifact && artifact === "plan" && verb === "archive")
+        return [
+            "archive a complete plan normally; --force archives an unfinished selected plan without changing task, evaluation, or completion history",
+            "an implicit archive rejects multiple open candidates; select an exact historical plan with its bare --plan ID",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "plan" && verb === "replace")
+        return [
+            "name the predecessor and successor with bare IDs from canonical evidence; never infer roles from list order",
+            "when competing open plans block selection, use npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json only after the complete recovery pair is known",
+            "pending plan replacement journals block plan reads until the exact retry completes or restores the operation",
+            ...base,
+        ];
     if (entityArtifact && artifact === "plan")
         return [
             "the active plan entity is selected by lifecycle state",
@@ -327,6 +356,8 @@ export function renderExplainText(explain) {
     const input = explain.input;
     if (input?.mode === "structured")
         lines.push("", "Required:", "  --input PATH             YAML/JSON document; use - for stdin");
+    if (explain.allow_force === true)
+        lines.push("", "Optional:", `  --force                  ${String(explain.force_semantics ?? "Apply the operation's force contract.")}`);
     lines.push("", "Recovery:", `  ${String(explain.recovery ?? "Correct the input and retry; no state was changed.")}`, "", "Example:", `  ${String(explain.example ?? "")}`);
     return lines.join("\n") + "\n";
 }

package/dist/state/write/grammar.js

@@ -99,12 +99,15 @@ function parseOperation(raw, index) {
     const input = {
         mode: inputMode,
         ...(raw.input.root === undefined ? {} : { root: requiredString(raw.input.root, `${p}.input.root`) }),
+        ...(raw.input.optional === true ? { optional: true } : {}),
         sources: strings(raw.input.sources, `${p}.input.sources`),
         ...(raw.input.structured_sources === undefined
             ? (inputMode === "structured" ? { structuredSources: strings(raw.input.sources, `${p}.input.sources`) } : {})
             : { structuredSources: strings(raw.input.structured_sources, `${p}.input.structured_sources`) }),
         cliOwnedFields: strings(raw.input.cli_owned_fields, `${p}.input.cli_owned_fields`),
     };
+    if (raw.input.optional !== undefined && raw.input.optional !== true)
+        throw new Error(`invalid mutation grammar: ${p}.input.optional must be true when present`);
     if (inputMode === "structured" && (!input.root || input.sources.length === 0))
         throw new Error(`invalid mutation grammar: ${p} structured input needs a root and source`);
     if (inputMode === "none" && (input.sources.length > 0 || input.root !== undefined))
@@ -159,6 +162,7 @@ function operationParityProjection(operation) {
         input: {
             mode: operation.input.mode,
             ...(operation.input.root ? { root: operation.input.root } : {}),
+            ...(operation.input.optional ? { optional: true } : {}),
             sources: operation.input.sources,
             structured_sources: operation.input.structuredSources ?? [],
             cli_owned_fields: operation.input.cliOwnedFields,
@@ -183,6 +187,7 @@ function runtimeParityProjection(operation) {
         input: {
             mode: operation.inputMode,
             ...(operation.inputRoot ? { root: operation.inputRoot } : {}),
+            ...(operation.inputOptional ? { optional: true } : {}),
             sources: operation.inputSources,
             structured_sources: operation.structuredInputSources,
             cli_owned_fields: operation.cliOwnedFields,

package/dist/state/write/operations.js

@@ -53,6 +53,7 @@ function operationProjection(operation) {
         input: {
             mode: operation.input.mode,
             ...(operation.input.root ? { root: operation.input.root } : {}),
+            ...(operation.input.optional ? { optional: true } : {}),
             sources: operation.input.sources,
             structured_sources: operation.input.structuredSources ?? [],
             cli_owned_fields: operation.input.cliOwnedFields,

package/dist/state/write/runtimeOperations.js

@@ -5,7 +5,7 @@ export const RUNTIME_WRITABLE_ARTIFACTS = [
 ];
 export const RUNTIME_WRITE_VERBS = [
     "append", "update", "amend", "set-status", "supersede", "set-plan-status",
-    "record-evaluation", "archive", "create", "publish", "activate", "repair", "set-severity", "resolve", "reopen", "explain",
+    "record-evaluation", "archive", "create", "replace", "publish", "activate", "repair", "set-severity", "resolve", "reopen", "explain",
 ];
 const readiness = loadTodoReadinessContract();
 const f = (flag, field, kind, options = {}) => ({ flag, field, kind, required: false, ...options });
@@ -43,6 +43,7 @@ const RUNTIME_OPERATION_CORES = [
     op("plan", "record-evaluation", planEvaluationFields, { selectors: ["--id", "--plan"], ownedFields: ["id", "artifact", "plan", "evaluation"] }),
     op("plan", "archive", [f("--plan", "plan", "string")], { selectors: ["--plan"], ownedFields: ["id", "artifact", "plan", "header.status"], allowForce: true }),
     op("plan", "create", [], { ownedFields: ["id", "artifact", "header.id", "previous_plan_archived", "task_ids"], inputMode: "structured", inputRoot: "complete plan document", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "header.id", "previous_plan_archived", "task_ids"], inputMaxBytes: 32768, allowForce: true }),
+    op("plan", "replace", [f("--predecessor", "predecessor", "string", { required: true, description: "Bare plan ID to archive as the explicit predecessor." }), f("--successor", "successor", "string", { description: "Existing bare open plan ID to retain as the explicit successor." })], { selectors: ["--predecessor", "--successor"], ownedFields: ["id", "artifact", "header.status", "header.id", "previous_plan_archived", "replacement_input_sha256", "task_ids"], inputMode: "structured", inputRoot: "complete plan document when creating a successor", inputOptional: true, inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "header.id", "previous_plan_archived", "replacement_input_sha256", "task_ids"], inputMaxBytes: 32768 }),
     op("health", "append", [], { ownedFields: ["id", "artifact", "appended_at"], inputMode: "structured", inputRoot: "one audit entry", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "appended_at"], inputMaxBytes: 32768, compacts: true, recoveryCommand: ["check", "validate", "state", "--format", "json"] }),
     op("objective", "create", [], { ownedFields: ["id", "artifact", "header.id"], inputMode: "structured", inputRoot: "one objective document", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "header.id"], inputMaxBytes: 32768 }),
     op("objective", "update", [f("--id", "id", "string", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "header.id"], inputMode: "structured", inputRoot: "one objective document", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "header.id"], inputMaxBytes: 32768 }),
@@ -87,13 +88,14 @@ const RUNTIME_OPERATION_PROJECTIONS = {
     "plan.supersede": projection("Complete and evaluate each replacement task with latest PASS evidence, then retry with the returned bare IDs.", developmentCommand('state plan supersede --id qjtrmnpvka --by zqtrmnpvka --reason "Replacement task" --format json')),
     "plan.set-plan-status": projection("Keep the plan open or resolve every incomplete task and replacement evaluation before retrying completion.", developmentCommand("state plan set-plan-status --status complete --format json")),
     "plan.record-evaluation": projection("Use the task's bare ID, a stable attempt ID, and evaluator provenance, then retry without changing published evidence.", developmentCommand('state plan record-evaluation --id qjtrmnpvka --attempt-id audit-1 --verdict pass --provenance "audit report" --format json')),
-    "plan.archive": projection("Complete or preserve the selected plan, then retry archive with no content flags; no state was changed.", developmentCommand("state plan archive --dry-run --format json")),
-    "plan.create": projection(`Run ${developmentCommand("state plan explain --verb create --format json")}, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and correct the first schema or dependency violation.`, developmentCommand("state plan create --input plan.yaml --format json")),
+    "plan.archive": projection("Archive a complete plan normally. With --force, archive the selected open plan unchanged only after the locked canonical snapshot identifies it; multiple implicit open-plan candidates are rejected without effects.", developmentCommand("state plan archive --dry-run --format json"), developmentCommand("state plan archive --force --dry-run --format json")),
+    "plan.create": projection(`Run ${developmentCommand("state plan explain --verb create --format json")}, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and use --force only when the locked canonical snapshot has exactly one open predecessor to archive unchanged.`, developmentCommand("state plan create --input plan.yaml --format json"), developmentCommand("state plan create --force --input plan.yaml --format json")),
+    "plan.replace": projection("Name one bare predecessor and either one existing bare successor or one complete successor plan input. The operation archives only the named predecessor, derives reverse lineage from the successor, and rejects divergent retries before effects. Competing-open diagnostics retain bounded bare IDs without assigning roles and recover through npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json.", developmentCommand("state plan replace --predecessor abcdefghij --successor klmnopqrst --format json"), developmentCommand("state plan replace --predecessor abcdefghij --input plan.yaml --format json")),
     "health.append": projection(`Run ${developmentCommand("check validate state --format json")}, preserve audit evidence, and retry with one schema-valid audit entry.`, developmentCommand("state health append --input audit.yaml --format json")),
     "objective.create": projection("Remove identity fields assigned by the CLI and retry with one schema-valid objective document.", developmentCommand("state objective create --input objective.yaml --format json")),
     "objective.update": projection("Reread the objective, copy its bare ID to --id, remove CLI-owned fields, and retry.", developmentCommand("state objective update --id qjtrmnpvka --input objective.yaml --format json")),
     "experiments.publish": projection("Use a bare objective ID, omit numeric legacy selectors, and retry the exact input; divergent immutable identities remain untouched.", developmentCommand("state experiments publish --objective qjtrmnpvka --input experiment.yaml --format json")),
-    "todo.activate": projection("Preview and review every reported activation effect before explicit confirmed apply; use the returned examples without modification.", developmentCommand("state todo activate --dry-run --format json"), developmentCommand("state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json")),
+    "todo.activate": projection("Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires non-mutating owner correction and replanning.", developmentCommand("state todo activate --dry-run --format json"), developmentCommand("state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json")),
     "todo.repair": projection("Preview and review every diagnosed repair decision before explicit confirmed apply; ambiguous evidence is rejected without effects.", developmentCommand("state todo repair --dry-run --format json"), developmentCommand("state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json")),
     "todo.create": projection(`Run ${developmentCommand("state todo explain --verb create --format json")}, remove CLI-owned fields, provide the full typed TODO record, and retry.`, developmentCommand("state todo create --input todo.yaml --format json")),
     "todo.update": projection("Reread the TODO item, use its bare ID, supply only typed patch fields, and use null or an empty list only for declared clearable fields.", developmentCommand("state todo update --id qjtrmnpvka --input todo-patch.yaml --format json")),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentera",
-  "version": "3.0.0-dev.47",
+  "version": "3.0.0-dev.51",
   "description": "One CLI, many capabilities: project state, artifact validation, and capability routing for AI coding agents",
   "keywords": [
     "agentera",
@@ -77,6 +77,6 @@
   },
   "agentera": {
     "suiteVersion": "3.0.0",
-    "gitRef": "91b25910acca8676d0442e874ceff713c44fae0c"
+    "gitRef": "a70ed56a72d633f3f11e94cede11fe4aadba2d2e"
   }
 }