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

package/dist/cli/commands/prime/collectEntityOrientation.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { listProgressEntities } from "../../../state/progressEntities.js";
 import { listDecisionEntities } from "../../../state/decisionEntities.js";
 import { listHealthEntities } from "../../../state/healthEntities.js";
-import { listPlanEntities, listPlanTaskEntities } from "../../../state/planEntities.js";
+import { listPlanEntities, listPlanTaskEntities, openPlanConflictDiagnostic } from "../../../state/planEntities.js";
 import { listObjectiveEntities, listExperimentEntities } from "../../../state/objectiveExperimentEntities.js";
 import { assertTodoReconciliationReadable, listTodoDocsEntities, projectTodoReadEntities } from "../../../state/todoDocsEntities.js";
 import { inspectTodoReconciliationState } from "../../../state/todoReconciliationInspection.js";
@@ -105,22 +105,31 @@ function projectedHistory(list, artifact, fullCount, summaryCount, degraded) {
         source_contract: list.source_contract,
     };
 }
-function selected(entries, artifact) {
-    if (entries.length < 2)
+function entityPlanStatus(entry) {
+    const plan = entry.record ?? {};
+    const planHeader = plan.header && typeof plan.header === "object" && !Array.isArray(plan.header)
+        ? plan.header
+        : {};
+    return String(planHeader.status ?? plan.status ?? "");
+}
+function selected(entries, artifact, candidateIds = entries.map((entry) => String(entry.id)), sourceRoot) {
+    if (candidateIds.length < 2)
         return entries[0];
-    const ids = entries.map((entry) => String(entry.id)).sort().join(", ");
+    const ids = candidateIds.slice().sort();
     const noun = artifact === "plan" ? "open plans" : "active objectives";
     const list = preCutoverCommand(`state ${artifact} list --format json`);
+    const planConflict = artifact === "plan" ? openPlanConflictDiagnostic(ids, sourceRoot) : undefined;
     throw new StateRetrievalFailure({
         schemaVersion: "agentera.stateFailure.v1",
         status: "fail",
         error: {
             class: "ambiguous",
             artifact,
-            message: `multiple ${noun} require explicit selection: ${ids}`,
+            message: planConflict?.message ?? `multiple ${noun} require explicit selection: ${ids.join(", ")}`,
             syntax: preCutoverCommand(`state ${artifact} get --id ID --format json`),
             example: preCutoverCommand(`state ${artifact} get --id ${String(entries[0]?.id)} --format json`),
-            recovery: `Run ${list}, resolve the competing ${noun}, and retry prime.`,
+            recovery: planConflict?.recovery ?? `Run ${list}, resolve the competing ${noun}, and retry prime.`,
+            ...(planConflict ? { details: planConflict.details } : {}),
         },
     }, 1);
 }
@@ -163,7 +172,13 @@ export function collectEntityOrientation(projectRoot, sourceRoot) {
     const objectiveEntries = entries(objectiveList);
     const todoEntries = entries(todoList);
     const docsEntries = entries(docsList);
-    const selectedPlan = selected(planEntries, "plan");
+    // Startup detail is bounded to two plans, but ambiguous diagnostics must use
+    // the complete canonical candidate set so their ID sample and omission count
+    // match direct plan selection without creating another selector.
+    const openPlanCandidateIds = discovery.entities
+        .filter((entry) => entry.boundary === "plan" && entry.classification === "valid" && entry.id && ["open", "active"].includes(entityPlanStatus(entry)))
+        .map((entry) => entry.id);
+    const selectedPlan = selected(planEntries, "plan", openPlanCandidateIds, sourceRoot);
     const taskPage = selectedPlan
         ? listPlanTaskEntities(projectRoot, String(selectedPlan.id), 100, undefined, { sourceRoot, format: "json", discovery })
         : null;

package/dist/cli/commands/prime/collectOrientationState.js

@@ -99,10 +99,10 @@ export function collectOrientationState(opts) {
     const readiness = selectStatusReadiness(plan, health, objective, todoItems, decision, savedContext, entity.todoReadiness);
     const reconciliationReadiness = entity.todoReconciliation?.status === "action_required"
         ? withRecommended(readiness, {
-            object: entity.todoReconciliation.state === "inactive" ? "Activate TODO reconciliation" : "Repair TODO reconciliation",
-            capability: "build",
+            object: entity.todoReconciliation.state === "unsafe_inactive" ? "Replan unsafe TODO activation correction" : entity.todoReconciliation.state === "inactive" ? "Activate TODO reconciliation" : "Repair TODO reconciliation",
+            capability: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : "build",
             reason: entity.todoReconciliation.recovery_command,
-            phase: entity.todoReconciliation.state === "invalid_lifecycle" ? "audit" : "build",
+            phase: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : entity.todoReconciliation.state === "invalid_lifecycle" ? "audit" : "build",
         })
         : readiness;
     const nextAction = cutover.status !== "complete"

package/dist/cli/commands/prime/orientationOutput.js

@@ -214,6 +214,8 @@ export function buildStatusContextState(state, _command = "prime", _options = {}
         plan: {
             exists: plan.exists,
             active: plan.active ?? false,
+            id: plan.id ?? null,
+            artifact: plan.exists ? plan.artifact ?? "plan" : null,
             status: plan.status,
             title: plan.title ?? null,
             complete: plan.complete ?? 0,

package/dist/cli/commands/state/write.js

@@ -272,7 +272,7 @@ function parseWrite(artifactRaw, argv) {
             message: `${artifact} ${verb} accepts field flags, not --input`,
             example: exampleFor(artifact, verb),
         });
-    if (spec.inputRoot && !inputSource)
+    if (spec.inputRoot && !inputSource && !spec.inputOptional)
         invalid({
             class: "missing_argument",
             message: `--input is required for ${artifact} ${verb}`,
@@ -311,11 +311,7 @@ function parseWrite(artifactRaw, argv) {
         const id = mappingPath(values, "id");
         if (taskVerb && id === undefined)
             invalid({ class: "missing_argument", message: `--id is required for plan ${verb} in entity mode` });
-        if (force)
-            invalid({ class: "unrecognized_argument", message: "--force is unavailable for entity plans; incomplete plans remain canonical history" });
     }
-    if (artifact === "plan" && verb === "create" && force)
-        invalid({ class: "unrecognized_argument", message: "--force is unavailable for entity plan create because multiple open plans coexist" });
     return { artifact, spec, format, projectRoot, dryRun, force, values, callerPayload, inputSource };
 }
 function mappingPath(entry, field) {

package/dist/cli/commands/validate.js

@@ -457,7 +457,7 @@ export function cmdValidateState(args, io) {
     return payload.valid ? 0 : 1;
 }
 function todoReconciliationValidationIssue(diagnosis) {
-    const label = diagnosis.state === "inactive" ? "inactive" : diagnosis.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+    const label = diagnosis.state === "inactive" ? "inactive" : diagnosis.state === "unsafe_inactive" ? "unsafe inactive" : diagnosis.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
     return {
         code: `todo_reconciliation_${diagnosis.state}`,
         path: "TODO.md",

package/dist/cli/help.js

@@ -146,6 +146,10 @@ export function printStateHelp(sub) {
             "Invalid historical archives remain non-fatal compatibility diagnostics unless selected.",
             "Task list accepts an optional bare plan ID and otherwise defaults to the sole open plan; task get requires --id.",
             "Only the displayed bare-ID selectors are accepted.",
+            "Plan create rejects an open predecessor unless --force can archive exactly one unchanged; create --force records that predecessor's bare ID in successor.previous_plan_archived.",
+            "Targeted replacement is explicit: state plan replace --predecessor ID --successor ID, or --predecessor ID --input PLAN.yaml to create the successor. It changes only the named predecessor lifecycle and derived successor lineage.",
+            "Competing open-plan diagnostics retain bounded bare IDs and require explicit roles: state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json. They never infer a role from list order.",
+            "Archive completed plans normally. Archive an unfinished selected plan with --force; an implicit archive with multiple open plans rejects without effects.",
             "List limits are 1 through 100; structured pages are at most 32,768 UTF-8 bytes and omit whole entries only.",
             "Legacy plan identity collisions return a structured ambiguous error.",
             "",

package/dist/cli/orientation/attention.js

@@ -6,8 +6,10 @@ export function buildOrientationAttention(state) {
     const { v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, glossary_caveat_attention: glossaryCaveatAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, todo_reconciliation: todoReconciliation, } = state;
     const attention = [];
     if (todoReconciliation?.status === "action_required") {
-        const label = todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
-        attention.push(`action-required: TODO reconciliation is ${label}; preview \`${todoReconciliation.preview_command ?? "n/a"}\`; apply \`${todoReconciliation.apply_command ?? "n/a"}\``);
+        const label = todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_inactive" ? "unsafe inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+        attention.push(todoReconciliation.state === "unsafe_inactive"
+            ? `action-required: TODO reconciliation is ${label}; ${todoReconciliation.recovery_command}`
+            : `action-required: TODO reconciliation is ${label}; preview \`${todoReconciliation.preview_command ?? "n/a"}\`; apply \`${todoReconciliation.apply_command ?? "n/a"}\``);
     }
     const skillDivergenceSignals = (state.app.signals ?? []).filter((s) => s.kind === "skill_root_divergence");
     for (const signal of skillDivergenceSignals) {

package/dist/core/developmentInvocation.js

@@ -284,7 +284,7 @@ function validateOperationExample(spec, template) {
     }
     if (!format)
         invalid(`${spec.artifact}.${spec.verb} example omits --format`);
-    if (spec.inputMode === "structured" && !input)
+    if (spec.inputMode === "structured" && !spec.inputOptional && !input)
         invalid(`${spec.artifact}.${spec.verb} example omits --input`);
     for (const field of spec.fields) {
         if (field.required && !seen.has(field.flag))

package/dist/registries/activationTuples.js

@@ -74,6 +74,7 @@ const decodedCatalog = gunzipSync(Buffer.from(CATALOG, "base64")).toString("utf8
 const emittedReasons = JSON.parse(gunzipSync(Buffer.from(EMITTED_REASON_CATALOG, "base64")).toString("utf8"));
 const rawTuples = JSON.parse(decodedCatalog.slice(decodedCatalog.indexOf("[", 2)).replace(/,\s*]$/, "]"));
 const addedTuples = [
+    { class: "state", surface_id: "write:plan.replace", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "plan.replace", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "state", surface_id: "write:todo.activate", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "todo.activate", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "state", surface_id: "write:todo.repair", owner_path: "packages/cli/src/state/write/runtimeOperations.ts", owner_symbol_or_selector: "runtimeOperationSpecs", owner_selector: "todo.repair", semantic_selector_if_any: null, canonical_correction: "node packages/cli/dist/bin/agentera.js check validate state --format json" },
     { class: "package", surface_id: "emitted:packages/cli/src/cli/commands/doctor.ts", owner_path: "packages/cli/src/registries/packageRegistry.ts", owner_symbol_or_selector: "loadRegistry", owner_selector: "packages/cli/src/cli/commands/doctor.ts", semantic_selector_if_any: JSON.stringify({ path: "packages/cli/src/cli/commands/doctor.ts", selector: null, format: null, classification: null, reason: "Doctor project-state signals publish bounded reconciliation preview and apply guidance." }), canonical_correction: "pnpm -C packages/cli run verify:package" },
@@ -94,11 +95,11 @@ export const ACTIVATION_TUPLE_AUTHORITY = Object.freeze({
         capability: { count: 12, sha256: "892e6e5e2a57b41064bc44fa2946453225f1b1195aff77aad05365fd0a1071c2" },
         runtime: { count: 81, sha256: "99b2abff3ebff889b54b1781c563ab4b32609a479c4e90d6aad854f48fba7edc" },
         reference: { count: 22, sha256: "243fd3c317553f8924c56a52c61af90ccf2793b7b0018af1373b73c69b6c3afb" },
-        state: { count: 36, sha256: "c3366cd6d538a47b5554f2e142eb255ac371bfc77e89128aceb59dfd8376c20a" },
+        state: { count: 37, sha256: "210bd831c5d62beac149efd888ee4a99af49a9469cf373031f8db9893904d0c1" },
         package: { count: 66, sha256: "83e6971af7f7564e42369aaccc445b32a0793bfffade843d149b6abd4fd3dbbc" },
         bootstrap: { count: 34, sha256: "9a7dd7e27110d85cf5c08835fdd8f08119e75579858e63bc6d396c733961d0bc" },
     },
-    total: { count: 278, sha256: "52a349aa3901626cba0bef4e06d380067722d73d3039fea95f2d806a8018fe54" },
+    total: { count: 279, sha256: "c2d7a66bc9af04a5511348825995317a5968357c6cacbfd87eb2cc4fbe77156c" },
 });
 export function canonicalTupleJson(value) { return JSON.stringify(value); }
 export function digestCanonicalTuples(values) {

package/dist/registries/packagePublication.js

@@ -53,11 +53,11 @@ export const ACTIVATION_CENSUS_AUTHORITY = deepFreeze({
         capability: { count: 12, sha256: "007e1157a892fec54182b1803aeaa442cf8e2e332e6a055c3bd020e2b0731867" },
         runtime: { count: 81, sha256: "03fe600a3a27f05daf0d1b59c16b00bedc354a13c70ea60be0b457175fdf743c" },
         reference: { count: 22, sha256: "2b48c82bb7ee10388d9ebb4fa7ea3743ea82a7e9aaedfcd5a858eeedb9d891ae" },
-        state: { count: 36, sha256: "a9f371e2f6d49e7cb890767d7dfe26edee11d4a7d28ee35ab6c491c0abafbbf0" },
+        state: { count: 37, sha256: "ca87acdb0fda04ba46a52163fc30ec6578c077e61fcb64597f861a36fdce1dc4" },
         package: { count: 66, sha256: "3548af7e84151c90690a6eb3d1cb6c7847f39b290161ecab599d8cb1bf0d2cb0" },
         bootstrap: { count: 34, sha256: "71c2038744e2518a6adb722acbb5f9352bddfb5d1c92eeb0e347297ef2ca2f1e" },
     },
-    total: { count: 278, sha256: "5767645b4d78d8716e7ea1a283125bcfd43e13634311b33b62bc0a307d1abdb3" },
+    total: { count: 279, sha256: "b92cd469f858e9584682d05b4d9bb03c2fc4b905f3485475723786c0a978c138" },
 });
 /** Each dimension names the production contract it observes independently. */
 export const ACTIVATION_EVIDENCE_SOURCES = deepFreeze({

package/dist/state/entityStorage.js

@@ -13,6 +13,7 @@ import { summaryMigrationProvenanceDeclaration, summaryMigrationProvenanceViolat
 import { validateCompactedSummarySourceRowAuthority } from "./summarySourceRowAuthority.js";
 import { acquireWriterLock } from "./write/lock.js";
 import { planTaskRecordViolations } from "./write/planEvaluation.js";
+import { planLineageIssues } from "./planLineageValidation.js";
 import { todoDocsRecordViolations } from "./todoDocsEntityValidation.js";
 import { applyGlossaryCaveatLifecycleValidation, validateProgressGlossaryCaveat } from "./progressGlossaryCaveat.js";
 import { progressPublicationOrderViolations } from "./progressPublicationOrder.js";
@@ -63,8 +64,8 @@ function canonicalEntityEnvelopeAgainstModel(bytes, expected, model, sourceRoot,
         violations.push(...healthEntityViolations(record));
     if (expected.boundary === "plan") {
         const header = mapping(record.header) ? record.header : {};
-        if (!mapping(record.header) || typeof header.title !== "string" || typeof header.created !== "string" || !["open", "complete", "archived"].includes(String(header.status)))
-            violations.push("invalid plan lifecycle fields");
+        if (!mapping(record.header) || typeof header.title !== "string" || typeof header.created !== "string" || !["open", "complete", "archived"].includes(String(header.status)) || (record.replacement_input_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(String(record.replacement_input_sha256))))
+            violations.push("invalid plan lifecycle or replacement identity fields");
     }
     if (expected.boundary === "plan_task")
         violations.push(...planTaskRecordViolations(record));
@@ -430,9 +431,9 @@ function discoverFile(projectRoot, file, pathArtifact, boundary, model, issues,
     }
     if (!malformed && boundary === "plan" && record) {
         const header = mapping(record.header) ? record.header : {};
-        if (!mapping(record.header) || typeof header.title !== "string" || typeof header.created !== "string" || !["open", "complete", "archived"].includes(String(header.status))) {
+        if (!mapping(record.header) || typeof header.title !== "string" || typeof header.created !== "string" || !["open", "complete", "archived"].includes(String(header.status)) || (record.replacement_input_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(String(record.replacement_input_sha256)))) {
             malformed = true;
-            issues.push({ code: "malformed_entity", path: relativePath, id, artifact, boundary, message: `entity '${relativePath}' has invalid plan lifecycle fields`, recovery: recovery(projectRoot, `repair '${relativePath}' using the current plan header schema and open|complete|archived lifecycle`) });
+            issues.push({ code: "malformed_entity", path: relativePath, id, artifact, boundary, message: `entity '${relativePath}' has invalid plan lifecycle or replacement identity fields`, recovery: recovery(projectRoot, `repair '${relativePath}' using the current plan header schema, open|complete|archived lifecycle, and lowercase SHA-256 replacement identity`) });
         }
     }
     if (!malformed && boundary === "plan_task" && record) {
@@ -550,8 +551,8 @@ export function assertEntityDiscoveryOrigin(projectRoot, sourceRoot, discovery)
 }
 function relationTargets(entity, relation) {
     const value = entity.record?.[relation.field];
-    if (relation.cardinality === "exactly_one")
-        return typeof value === "string" ? [value] : null;
+    if (relation.cardinality === "exactly_one" || relation.cardinality === "zero_or_one")
+        return typeof value === "string" ? [value] : relation.cardinality === "zero_or_one" && (value === undefined || value === null) ? [] : null;
     if (value === undefined || value === null)
         return [];
     return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
@@ -649,6 +650,8 @@ export function validateEntityDiscovery(projectRoot, sourceRoot, discovery, boun
                 });
         }
     }
+    const canonicalPlans = discovery.entities.filter((entity) => entity.boundary === "plan" && entity.classification === "valid" && entity.id && entity.record);
+    issues.push(...planLineageIssues(canonicalPlans, (action) => recovery(projectRoot, action)));
     for (const definition of model.entities) {
         if (!definition.ownership || definition.ownership.cardinality !== "zero_or_one")
             continue;