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

package/README.md

@@ -38,18 +38,29 @@ bytes). Status startup returns
 bytes). Omitted detail names its authoritative recovery command. `doctor`
 returns detailed read-only evidence and exact user actions. Entity-mode projects
 with an absent or unsafe TODO reconciliation marker return `action_required`
-instead of `ok` or `up_to_date`; use the reported preview command, then the
-preview's exact effect-bound apply command:
+instead of `ok` or `up_to_date`. A safe inactive project reports an activation
+preview and its exact effect-bound apply command:
 
 ```bash
 npx -y agentera@next state todo activate --dry-run --format json
 npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json
+```
+
+An unsafe active project with an existing marker reports the separate repair
+preview and effect-bound apply path:
+
+```bash
 npx -y agentera@next state todo repair --dry-run --format json
 npx -y agentera@next state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json
 ```
 
-`check validate state` reports the same bounded, read-only diagnosis. Healthy
-active TODO projections keep the existing output.
+Unsafe inactive evidence (unmatched projections, duplicate public work, stale
+entity status, or prospective resurrection) reports a bounded, content-private
+diagnosis but no effect digest or apply command. It has no repair path before
+activation. Correct the Markdown-owned public rows and Agentera-owned entity
+state, then replan any required mutation. `check validate state` reports the
+same read-only diagnosis. Healthy active TODO projections keep the existing
+output.
 
 ## Shared-skill integration
 

package/bundle/CHANGELOG.md

@@ -146,9 +146,9 @@
   outside the contract. One bounded activation transaction rejects duplicate
   ID-less rows before requiring canonical IDs for all newly managed rows.
 - Fixed TODO cutover and activation to require a complete one-to-one inventory,
-  preserve Markdown-owned status and order, and block implicit mutation. The
-  effect-complete `agentera state todo activate --dry-run` preview now binds
-  its confirmed apply to the exact reported targets and effect digest.
+  preserve Markdown-owned status and order, and block implicit mutation. Unsafe inactive
+  `agentera state todo activate --dry-run` and confirmed activation reject
+  resurrection or duplicate effects before an effect digest, apply command, or project mutation.
 - Fixed unsafe TODO reconciliation recovery and reporting. `agentera state todo
   repair` collapses only proven duplicate or stale projections without reopening
   completed work, while `agentera prime`, `agentera doctor`, and `agentera check
@@ -213,7 +213,7 @@
 - Added persisted plan identity across active-to-archive transitions, deterministic read-only identity for legacy plans, explicit lifecycle provenance, mirrored-path reporting, and structured ambiguity failures for identity collisions.
 - Added `agentera state plan tasks list` and `agentera state plan tasks get --task N` for bounded active-plan task retrieval with declared task-number order, opaque snapshot cursors, structured not-found and compatibility errors, and exact omission recovery in text and JSON plan output.
 - Added `agentera state decisions amend --id ID --base-sha256 HASH [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes one immutable decision revision entity. Effective reads compose the base, ordered revisions, and current satisfaction entity; stale-base and same-base conflicts fail before publication, and identical retries converge.
-
+- Added `agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json` for targeted recovery of competing open plans; it atomically selects the named successor, rejects invalid requests without effects, and recovers interruptions without partial state.
 - Added an executable bounded-retrieval authority and reserved CLI grammar for plan tasks, plans, and objective-scoped experiments, including stable and legacy identity rules, experiment `0`, opaque cursors, explicit omissions, and structured compatibility errors; retrieval execution remains staged for subsequent tasks.
 - Added one shared skill at `~/.agents/skills/agentera` plus the CLI and entity-backed project state as the active integration contract; host-native plugin, hook, agent, and package surfaces are not shipped.
 - Defined native-resource cleanup evidence for supported hosts and explicit `agentera upgrade --legacy-cleanup RESOURCE_ID --dry-run|--yes` selection. Cleanup retains only ledger-proven whole resources; Codex descriptor reports preserve shared configuration keys as report-only action-required items without durable key-level ownership.

package/bundle/references/adapters/package-publication.json

@@ -284,8 +284,8 @@
               "sha256": "2b48c82bb7ee10388d9ebb4fa7ea3743ea82a7e9aaedfcd5a858eeedb9d891ae"
             },
             "state": {
-              "count": 36,
-              "sha256": "a9f371e2f6d49e7cb890767d7dfe26edee11d4a7d28ee35ab6c491c0abafbbf0"
+              "count": 37,
+              "sha256": "ca87acdb0fda04ba46a52163fc30ec6578c077e61fcb64597f861a36fdce1dc4"
             },
             "package": {
               "count": 66,
@@ -297,8 +297,8 @@
             }
           },
           "total": {
-            "count": 278,
-            "sha256": "5767645b4d78d8716e7ea1a283125bcfd43e13634311b33b62bc0a307d1abdb3"
+            "count": 279,
+            "sha256": "b92cd469f858e9584682d05b4d9bb03c2fc4b905f3485475723786c0a978c138"
           }
         }
       },

package/bundle/references/adapters/package-registry.yaml

@@ -130,6 +130,7 @@ records:
         - {"path":"CHANGELOG.md","region":"line:212","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"35f2268ae3281a70b7c584c23e4e57a07fc9ee6625eed48ae252d167e8ba83ea","reason":"Changelog line:212 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:214","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"67d177100a3c9892643202a255523b9a84f57aa4c28b8c5dd21973c13cc06c7d","reason":"Changelog line:214 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:215","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"39f085892a7b3c6e14905d90ab0c3f4cc58c66e0b5ffc2ab6ce0f88e8182cf98","reason":"Changelog line:215 records exact release history for that scalar; it does not direct current execution."}
+        - {"path":"CHANGELOG.md","region":"line:216","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"a2f0254ae0226ce04de0917832fd1911cf27b1b69a832abcfbfe34c01c8d0d41","reason":"Changelog line:216 records targeted plan-replacement behavior in release history; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:219","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"6093e60d6c57f5bee694523c7fe380cd6a2ebaaff36d13e7ef153f1439789e99","reason":"Changelog line:219 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:220","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"3dc02d2ca69c6d89705932cf557ffaa2bc089a294b518c0eef1a449dfb3d5173","reason":"Changelog line:220 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:224","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"2aac4a56f628aaca71f8003fd0678fed24771a7b10141759f7192808af70215c","reason":"Changelog line:224 records exact release history for that scalar; it does not direct current execution."}
@@ -247,7 +248,7 @@ records:
         - {"path":"CHANGELOG.md","region":"line:1058","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"79e767fd2e4baa00cdfc763c6814870dbefe20b6745d181f82bdba5139c0272f","reason":"Changelog line:1058 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:1065","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"d57016b29585bb34604fc36cfce740c4e6b83a2c0fa753467730d6840ecebd34","reason":"Changelog line:1065 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:1084","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"42cbb848be0de98624a2d008843e13c40efc7c77a02d7c4f489348d0e73b5b60","reason":"Changelog line:1084 records exact release history for that scalar; it does not direct current execution."}
-        - {"path":"CHANGELOG.md","region":"line:150","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"8b012fbbc2511af33d73365a893896571ef9f22fcfc47eb981549ce2a34635aa","reason":"Changelog line:150 records exact release history for that scalar; it does not direct current execution."}
+        - {"path":"CHANGELOG.md","region":"line:150","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"273d7dae87662352c49e5723aaa528efa89c9a7dbc7d43d3cbc54c1a1b9771da","reason":"Changelog line:150 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:152","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"6d02d187f8e271cc6acc4b6966344a841615326891969dbec67815e40a51fe81","reason":"Changelog line:152 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"CHANGELOG.md","region":"line:154","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"a5dd4c79ebfefc03bd1c6e3d159f362fd2c5f584d6ff8de7928edf88414133a9","reason":"Changelog line:154 records exact release history for that scalar; it does not direct current execution."}
         - {"path":"DESIGN.md","region":"line:41","category":"argument_bearing","classification":"exact_exemption","normalized_sha256":"650f6966f3048b7a15748d4ff652fff31c696e5c2b29e2268a0d60889251ebf1","reason":"Suite-design authority table names the exact prime context label as a source role; it is vocabulary, not an execution step."}

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -620,13 +620,18 @@ entity_target:
     - boundary: plan
       artifact: plan
       independently_mutable: true
-      relationships: []
+      relationships: [previous_plan_archived]
       implementation: implemented
-      publication: replace_owned_entity
+      publication: replace_owned_entity_with_targeted_replacement_journal
+      targeted_replacement_journal:
+        path: .agentera/.entity-recovery/plan-replacement/<content-digest>.json
+        identity: canonical_operation_identity_and_complete_target_before_after_bytes
+        visibility: pending_journal_blocks_plan_reads_until_exact_retry_recovers_or_finishes
+        replay: exact_existing_roles_or_create_input_sha256_only
       record:
         required_fields: [header, what, why, scope]
         required_paths: [header.title, header.created, header.status]
-        forbidden_fields: [id, artifact, stable_id, plan_id, tasks, previous_plan_archived]
+        forbidden_fields: [id, artifact, stable_id, plan_id, tasks]
         identity: >-
           The canonical plan identity is the bare ten-letter entity envelope id.
           A composite header.id belongs only to legacy migration source and is
@@ -775,6 +780,16 @@ entity_target:
             canonical ten-letter ID; each retained legacy exemption admits at
             most one exact row occurrence per reconciliation and cannot
             authorize a changed or duplicate row.
+          unsafe_inactive: >-
+            One read-only pre-publication decision gates both activation preview
+            and confirmed apply. Every canonical entity must have one exact
+            public projection. Unmatched projections, duplicate public work,
+            stale entity public fields, or a prospective resurrection reject
+            before effects with bounded, content-private risk. Unsafe inactive
+            state emits neither an effect digest nor an apply command. Repair
+            requires an activation marker and is not pre-activation recovery;
+            owners must correct their source data, and any required mutation
+            must be replanned.
         managed_row_identity: every_activated_managed_checkbox_row_has_one_ten_letter_id
         unmanaged_regions: checkbox_rows_outside_managed_headings_remain_ordinary_markdown
         public_path_binding: exact_docs_mapped_relative_path_plus_docs_yaml_snapshot_sha256
@@ -877,6 +892,7 @@ entity_target:
   relationships:
     representation: bare target entity ID in the named record field
     integrity: every non-null target must resolve to exactly one entity with the declared target boundary
+    plan_lineage: An optional plan.previous_plan_archived points to one distinct archived predecessor, and that predecessor has at most one successor; reverse lineage is derived from the canonical source record rather than stored in a second mutable field.
     unresolved_behavior: whole-state validation and migration cutover fail without creating a target
     declarations:
       - source: decision_satisfaction
@@ -891,6 +907,10 @@ entity_target:
         field: plan
         target: plan
         cardinality: exactly_one
+      - source: plan
+        field: previous_plan_archived
+        target: plan
+        cardinality: zero_or_one
       - source: plan_task
         field: depends_on
         target: plan_task
@@ -2713,11 +2733,11 @@ mutation_grammar:
       verb: archive
       class: simple_transition
       selectors: [--plan]
-      preconditions: [entity_mode_marker_is_valid, selected_plan_is_not_open]
+      preconditions: [entity_mode_marker_is_valid, lifecycle_effects_are_derived_from_locked_canonical_entities, selected_plan_is_complete_or_archived_or_force_archivable]
       owned_fields: [id, artifact, plan, header.status]
       input: { mode: none, sources: [], cli_owned_fields: [] }
-      recovery: Complete or preserve the selected plan, then retry archive with no content flags; no state was changed.
-      examples: ['npx -y agentera@next state plan archive --dry-run --format json']
+      recovery: 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.
+      examples: ['npx -y agentera@next state plan archive --dry-run --format json', 'npx -y agentera@next state plan archive --force --dry-run --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
       allow_force: true
       fields: [{ flag: --plan, field: plan, kind: string }]
@@ -2726,19 +2746,39 @@ mutation_grammar:
       verb: create
       class: batch_transaction
       selectors: []
-      preconditions: [entity_mode_marker_is_valid, input_is_one_complete_plan_document, create_local_task_ordinals_are_sequential, dependency_graph_is_valid]
+      preconditions: [entity_mode_marker_is_valid, lifecycle_effects_are_derived_from_locked_canonical_entities, input_is_one_complete_plan_document, create_local_task_ordinals_are_sequential, dependency_graph_is_valid]
       owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
       input:
         mode: structured
         root: complete plan document
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
-      recovery: Run npx -y agentera@next 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.
-      examples: ['npx -y agentera@next state plan create --input plan.yaml --format json']
+      recovery: Run npx -y agentera@next 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.
+      examples: ['npx -y agentera@next state plan create --input plan.yaml --format json', 'npx -y agentera@next state plan create --force --input plan.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       allow_force: true
       fields: []
 
+    - artifact: plan
+      verb: replace
+      class: batch_transaction
+      selectors: [--predecessor, --successor]
+      preconditions: [entity_mode_marker_is_valid, lifecycle_effects_are_derived_from_locked_canonical_entities, predecessor_and_existing_successor_are_explicit_or_one_complete_successor_input_is_supplied, named_roles_are_distinct_bare_plan_ids, replacement_leaves_no_unnamed_open_plan, exact_lineage_or_logical_create_input_replay_matches]
+      owned_fields: [id, artifact, header.status, header.id, previous_plan_archived, replacement_input_sha256, task_ids]
+      input:
+        mode: structured
+        root: complete plan document when creating a successor
+        optional: true
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id, previous_plan_archived, replacement_input_sha256, task_ids]
+      recovery: 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.
+      examples: ['npx -y agentera@next state plan replace --predecessor abcdefghij --successor klmnopqrst --format json', 'npx -y agentera@next state plan replace --predecessor abcdefghij --input plan.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields:
+        - { flag: --predecessor, field: predecessor, kind: string, required: true, description: Bare plan ID to archive as the explicit predecessor. }
+        - { flag: --successor, field: successor, kind: string, description: Existing bare open plan ID to retain as the explicit successor. }
+
     - artifact: health
       verb: append
       class: record_payload
@@ -2811,10 +2851,10 @@ mutation_grammar:
       verb: activate
       class: batch_transaction
       selectors: []
-      preconditions: [entity_mode_marker_is_valid, activation_is_absent_or_replay, todo_reconciliation_is_valid, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
+      preconditions: [entity_mode_marker_is_valid, activation_is_absent_or_replay, todo_reconciliation_is_valid, inactive_projection_is_complete_one_to_one_and_safe, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
       owned_fields: [reconciliation, public_document, activation]
       input: { mode: none, sources: [], cli_owned_fields: [] }
-      recovery: Preview and review every reported activation effect before explicit confirmed apply; use the returned examples without modification.
+      recovery: Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires non-mutating owner correction and replanning.
       examples: ['npx -y agentera@next state todo activate --dry-run --format json', 'npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
       compacts: true

package/bundle/skills/agentera/SKILL.md

@@ -229,12 +229,13 @@ Common mutations:
 - `npx -y agentera@next state decisions append --input <path|-> --format json`
 - `npx -y agentera@next state decisions amend --id ID --base-sha256 HASH --input <path|-> --format json`
 - `npx -y agentera@next state decisions update --id ID ... --format json`
-- `npx -y agentera@next state plan create --input plan.yaml --format json`
+- `npx -y agentera@next state plan create [--force] --input plan.yaml --format json`
 - `npx -y agentera@next state plan append [--plan PLAN_ID] --input task.yaml --format json`
 - `npx -y agentera@next state plan update --id TASK_ID [--plan PLAN_ID] --input task-patch.yaml --format json`
 - `npx -y agentera@next state plan set-status --id TASK_ID --status STATUS --format json`
 - `npx -y agentera@next state plan set-plan-status [--plan PLAN_ID] --status complete --format json`
-- `npx -y agentera@next state plan archive --format json`
+- `npx -y agentera@next state plan archive [--plan ID] [--force] --format json`
+- `npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json`
 - `npx -y agentera@next state health append --input audit.yaml --format json`
 - `npx -y agentera@next state todo create --input todo.yaml --format json`
 - `npx -y agentera@next state todo update --id ID --input todo-patch.yaml --format json`
@@ -255,6 +256,14 @@ ordinals inside one atomic input document; the writer removes them before
 publishing bare ten-letter plan and task envelope IDs. A legacy composite
 `header.id` is migration-only and is never a public selector. Post-publication
 task append/update payloads use only mutable task content and bare task IDs.
+Without `--force`, an open plan blocks creation. With exactly one canonical open
+predecessor, forced create archives that plan without changing task, evaluation,
+or completion history, then records its bare ID in the successor's
+writer-owned `previous_plan_archived` field. Forced archive preserves the same
+history. Multiple implicit open candidates reject before effects. When they
+block a reader or implicit writer, use the targeted replacement command only
+after canonical evidence names both roles; list order never assigns predecessor
+or successor roles.
 
 Add `--dry-run` to preview any mutation without publishing it. Artifacts not
 listed above are outside the typed writer contract and remain governed by their

package/bundle/skills/agentera/schemas/artifacts/plan.yaml

@@ -260,11 +260,22 @@ PLAN:
   7:
     id: PL22
     field: previous_plan_archived
-    type: string
+    type: bare_ten_letter_id
+    required: false
+    description: >-
+      Writer-owned bare ID of the predecessor archived when this successor was
+       created. The predecessor's archived lifecycle and this successor reference
+       provide bidirectional lineage without changing task, evaluation, or
+       completion history.
+  8:
+    id: PL23
+    field: replacement_input_sha256
+    type: lowercase_sha256_hex
     required: false
     description: >-
-      Path to the previous active plan archived when this plan was created.
-      Preserves plan lineage without changing lifecycle status.
+      Writer-owned immutable logical identity for a targeted replacement
+      successor. It excludes mutable task lifecycle and evaluation fields, so an
+      exact replacement input can replay after task execution changes.
 
 UNKNOWN:
   1:
@@ -545,9 +556,31 @@ LIFECYCLE_CONTRACT:
     execution:
       eligible: Only a plan at the current-plan path can supply executable work.
       archived: An archived plan is historical and non-executable regardless of status.
+    lineage:
+      field: previous_plan_archived
+      representation: bare predecessor plan entity ID
+      publication: The writer assigns the field only while atomically archiving a predecessor and publishing its successor.
+      reverse: A predecessor's successor is derived from the unique canonical plan record that names its ID in previous_plan_archived; no second mutable lineage field exists.
+      replacement_input_identity:
+        field: replacement_input_sha256
+        representation: lowercase SHA-256 of the normalized logical replacement input
+        ownership: Writer-owned at targeted replacement publication and immutable afterward.
+        exclusions: [task.status, task.evaluation, task.superseded_by, task.superseded_reason]
     forced_archive:
       unfinished_status: archived
-      effect: Move the plan to immutable history without claiming completion or changing tasks.
+      effect: Change the plan lifecycle to archived without claiming completion or changing tasks, evaluations, or completion history.
+    forced_create:
+      no_open_predecessor: Publish the successor normally.
+      one_open_predecessor: --force archives the predecessor unchanged and publishes the successor with previous_plan_archived set to the predecessor bare ID.
+      multiple_open_predecessors: Reject before effects because implicit creation cannot choose a predecessor.
+    targeted_replacement:
+      command: state plan replace --predecessor PREDECESSOR (--successor SUCCESSOR | --input PLAN.yaml)
+      existing_successor: Names both bare plan IDs, archives only the named predecessor, and assigns previous_plan_archived on the named open successor.
+      create_successor: Names the bare predecessor and supplies one complete plan document when no successor exists.
+      selection: Reject before effects if an unnamed open plan would remain, roles are invalid, or the requested successor conflicts with canonical lineage.
+      diagnostics: Competing-open readers and implicit writers expose bounded bare candidate IDs and the state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID recovery grammar. Canonical state never infers predecessor or successor roles from list order.
+      replay: The archived predecessor and unique derived successor identify an existing-successor replay; create retries compare the exact input identity retained on the successor rather than mutable task state.
+      atomicity: The complete predecessor, successor, and created-task target set is durable under the private entity recovery authority before any target is visible. Pending journals block plan reads until the exact retry finishes or restores the operation.
     replacement_evidence_transition:
       predicate: A replacement is complete and its latest persisted evaluation.last_verdict is pass.
       supersession: Every superseded_by replacement must satisfy the predicate before a new supersession is published.
@@ -720,6 +753,7 @@ LIFECYCLE_CONTRACT:
     documented_external_commitments:
       - packages/cli/src/capabilities/*/instructions.ts
       - packages/cli/README.md
+      - .opencode/skills/*/SKILL.md
       - skills/agentera/SKILL.md
       - skills/agentera/references/*
       - references/**/*.md

package/dist/capabilities/orchestrate/instructions.js

@@ -8,6 +8,8 @@ Plans, tasks, progress cycles, health audits, and decisions use entity authority
 
 Advance tasks with \`agentera state plan set-status --id ID\` and persist evaluator outcomes with \`agentera state plan record-evaluation --id ID\`. A superseded task is terminal, satisfies dependencies, and stays out of ready and blocked queues; record it only through \`agentera state plan supersede --id ID --by COMPLETED_ID --reason "..." --format json\`. Every replacement must be complete with latest persisted PASS before supersession.
 
+When competing open plans block startup, do not infer predecessor or successor roles from list order. Use \`agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json\` only after canonical evidence establishes the complete recovery pair.
+
 ## The orchestration loop`)
     .replaceAll("--number N", "--id ID")
     .replaceAll("--task N", "--id ID")

package/dist/capabilities/plan/instructions.js

@@ -28,5 +28,6 @@ Advice, clarification, tension, and handoff intent are transient and never write
 ## Workflow phases`)
     .replaceAll("--number N", "--id ID")
     .replaceAll("--task N", "--id ID")
+    .replace("Archive completed plan entities with `agentera state plan archive --format json`.", "Archive completed plan entities with `agentera state plan archive --format json`. With exactly one unfinished canonical predecessor, `agentera state plan create --force --input PATH --format json` archives it unchanged, publishes the successor, and records its bare ID in the writer-owned `previous_plan_archived` field. `agentera state plan archive --force` likewise preserves unfinished task, evaluation, and completion history; multiple implicit open candidates reject before effects. When competing open plans block selection, do not infer roles from list order: use `agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json` only after canonical evidence establishes the complete recovery pair.")
     .replace("served via `planning_context.profile.path` — read directly when `status: loaded`; if missing or stale, proceed without persona grounding", "served through `agentera report profile-grounding --format json` — use only returned `content` when shared validity is `valid`; if absent or repair_needed, proceed without persona grounding and preserve exact recovery")
     .replaceAll("planning_context.profile.path", "the shared profile validity summary");

package/dist/capabilities/status/instructions.js

@@ -8,4 +8,8 @@ export default `${instructions
 
 ### Profile validity
 
-Render the shared profile validity exactly as \`valid\`, \`absent\`, or \`repair_needed\`. Freshness is separate and may be \`current\`, \`stale\`, or \`unknown\`; only valid stale input may carry stale guidance. Repair-needed input preserves its repair recovery and MUST NOT receive refresh advice. Never render profile path or content.`;
+Render the shared profile validity exactly as \`valid\`, \`absent\`, or \`repair_needed\`. Freshness is separate and may be \`current\`, \`stale\`, or \`unknown\`; only valid stale input may carry stale guidance. Repair-needed input preserves its repair recovery and MUST NOT receive refresh advice. Never render profile path or content.
+
+### Plan selection
+
+Render \`status_context.plan.id\` as the canonical selected plan identity. If competing open plans block startup, preserve the failure and its recovery verbatim. Do not infer predecessor or successor roles from a title or list order; only run \`agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json\` after canonical evidence establishes both roles.`;

package/dist/cli/commands/compact.js

@@ -1,7 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML, { isMap, isScalar, isSeq } from "yaml";
 import { resolvePath } from "../../core/paths.js";
 import { runCompaction } from "../../hooks/compaction/index.js";
 import { emitStructured } from "../structured.js";
 import { boundStructuredProjection } from "../../state/projectionPolicy.js";
+const TODO_REFERENCE_DIAGNOSTIC_LIMIT = 20;
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isDirectory(directory) {
+    try {
+        const stat = fs.lstatSync(directory);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function yamlFilesBelow(directory) {
+    if (!isDirectory(directory))
+        return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+        .sort((left, right) => compareText(left.name, right.name))
+        .flatMap((entry) => {
+        const candidate = path.join(directory, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink())
+            return yamlFilesBelow(candidate);
+        return entry.isFile() && path.extname(entry.name) === ".yaml" ? [candidate] : [];
+    });
+}
+function activeStateYamlFiles(project) {
+    const stateRoot = path.join(project, ".agentera");
+    if (!isDirectory(stateRoot))
+        return [];
+    const topLevel = fs.readdirSync(stateRoot, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && path.extname(entry.name) === ".yaml")
+        .map((entry) => path.join(stateRoot, entry.name));
+    return [...topLevel, ...yamlFilesBelow(path.join(stateRoot, "entities"))]
+        .sort(compareText);
+}
+function stringScalarValues(node) {
+    if (isScalar(node))
+        return typeof node.value === "string" ? [node.value] : [];
+    if (isMap(node))
+        return node.items.flatMap((pair) => stringScalarValues(pair.value));
+    if (isSeq(node))
+        return node.items.flatMap(stringScalarValues);
+    return [];
+}
+function volatileTodoReferenceDiagnostics(project) {
+    const matches = [];
+    for (const file of activeStateYamlFiles(project)) {
+        const relativePath = path.relative(project, file).split(path.sep).join("/");
+        const contents = fs.readFileSync(file, "utf8");
+        let order = 0;
+        for (const document of YAML.parseAllDocuments(contents)) {
+            for (const value of stringScalarValues(document.contents)) {
+                for (const match of value.matchAll(/TODO line \d+|TODO\.md:\d+/g)) {
+                    matches.push({ path: relativePath, reference: match[0], order: order++ });
+                }
+            }
+        }
+    }
+    matches.sort((left, right) => compareText(left.path, right.path) || left.order - right.order);
+    return {
+        diagnostics: matches.slice(0, TODO_REFERENCE_DIAGNOSTIC_LIMIT).map(({ path, reference }) => ({ path, reference })),
+        omitted_count: Math.max(0, matches.length - TODO_REFERENCE_DIAGNOSTIC_LIMIT),
+    };
+}
+function volatileTodoReferenceGate(project, mode) {
+    const { diagnostics, omitted_count } = volatileTodoReferenceDiagnostics(project);
+    if (!diagnostics.length)
+        return null;
+    const count = diagnostics.length + omitted_count;
+    return {
+        status: {
+            artifact: "state_todo_references",
+            path: path.join(project, ".agentera"),
+            classification: "hygiene",
+            active_count: count,
+            archive_count: 0,
+            total_count: count,
+            over_limit_count: 0,
+            protected_overflow_count: 0,
+            exists: true,
+            reason: `${count} active state TODO reference${count === 1 ? "" : "s"} use volatile line syntax`,
+        },
+        mode,
+        action: "volatile_todo_reference",
+        changed: false,
+        result: null,
+        message: "replace TODO line references with stable TODO anchors",
+        diagnostics,
+        omitted_count,
+    };
+}
+function gatedCompactionOperations(project, mode) {
+    const hygiene = volatileTodoReferenceGate(project, mode);
+    if (mode === "fix" && hygiene)
+        return [hygiene];
+    const operations = runCompaction(project, mode);
+    return hygiene ? [...operations, hygiene] : operations;
+}
 function pyStr(value) {
     if (value === null || value === undefined)
         return "None";
@@ -33,6 +134,12 @@ function compactionOperationPayload(op) {
         message: op.message,
         reason: status.reason,
         ...(status.projection_recovery ? { recovery: status.projection_recovery } : {}),
+        ...(op.diagnostics
+            ? {
+                diagnostics: op.diagnostics.map(({ path, reference }) => ({ path, reference })),
+                omitted_count: op.omitted_count ?? 0,
+            }
+            : {}),
     };
     if (op.result !== null) {
         const recovery = op.result.recovery;
@@ -57,11 +164,15 @@ function compactionGuidance(mode, operations) {
     const protectedOps = operations.filter((op) => op.action === "protected_overflow");
     const errors = operations.filter((op) => op.action === "error");
     const refused = operations.filter((op) => op.action === "refused");
+    const volatileTodoReferences = operations.filter((op) => op.action === "volatile_todo_reference");
     const checkCommand = "npx -y agentera check compact --mode check --format json";
     const fixCommand = "npx -y agentera check compact --mode fix --format json";
     if (errors.length > 0) {
         return `Inspect the reported errors, repair invalid artifacts, then rerun \`${checkCommand}\`.`;
     }
+    if (volatileTodoReferences.length > 0) {
+        return `Replace volatile TODO line references in active state with stable anchors, then rerun \`${checkCommand}\`.`;
+    }
     if (refused.length > 0) {
         return "Projection changes were safely refused until each full entry has a verified numbered archive; inspect recovery metadata and retry after recovery.";
     }
@@ -97,8 +208,9 @@ function compactionSummary(mode, operations) {
     const formatting = operations.filter((op) => op.action === "formatting" || op.action === "pending_formatting").length;
     const protectedOverflow = operations.filter((op) => op.action === "protected_overflow").length;
     const errors = operations.filter((op) => op.action === "error").length;
+    const volatileTodoReferences = operations.filter((op) => op.action === "volatile_todo_reference").length;
     const changed = operations.filter((op) => op.changed).length;
-    const status = errors || (mode === "check" && (overLimit || formatting)) ? "fail" : "pass";
+    const status = errors || volatileTodoReferences || (mode === "check" && (overLimit || formatting)) ? "fail" : "pass";
     return {
         status,
         mode,
@@ -116,6 +228,8 @@ function compactionSummary(mode, operations) {
 function compactionExitCode(mode, operations) {
     if (operations.some((op) => op.action === "error"))
         return 2;
+    if (operations.some((op) => op.action === "volatile_todo_reference"))
+        return 1;
     if (mode === "check" &&
         operations.some((op) => op.action === "over_limit" || op.action === "formatting"))
         return 1;
@@ -154,6 +268,14 @@ function emitCompactionPayload(payload, mode, format, out) {
             `pending_summarization=${pyStr(item.pending_summarization_count)} | ` +
             `protected_overflow=${item.protected_overflow_count} | ` +
             `message=${item.message}\n`);
+        if (Array.isArray(item.diagnostics)) {
+            for (const diagnostic of item.diagnostics) {
+                if (!diagnostic || typeof diagnostic !== "object" || Array.isArray(diagnostic))
+                    continue;
+                out(`  diagnostic=${String(diagnostic.path)}: ${String(diagnostic.reference)}\n`);
+            }
+            out(`  omitted_count=${pyStr(item.omitted_count)}\n`);
+        }
     }
     out(`guidance=${summary.guidance}\n`);
 }
@@ -161,7 +283,7 @@ export function cmdCompact(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const mode = args.mode ?? "check";
     const project = resolvePath(args.project ?? process.cwd());
-    const operations = runCompaction(project, mode);
+    const operations = gatedCompactionOperations(project, mode);
     const payload = compactionPayload("check compact", project, mode, operations);
     emitCompactionPayload(payload, mode, args.format ?? "text", out);
     return compactionExitCode(mode, operations);
@@ -169,7 +291,7 @@ export function cmdCompact(args, io = {}) {
 export function cmdGate(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const project = resolvePath(args.project ?? process.cwd());
-    const operations = runCompaction(project, "check");
+    const operations = gatedCompactionOperations(project, "check");
     const payload = compactionPayload("check compact", project, "check", operations);
     emitCompactionPayload(payload, "check", args.format ?? "text", out);
     return compactionExitCode("check", operations);

package/dist/cli/commands/doctor.js

@@ -87,11 +87,14 @@ export function renderDoctorStatus(status, retiredResources) {
                     lines.push(`    Preview: ${signal.previewCommand}`);
                 if (signal.applyCommand)
                     lines.push(`    Apply: ${signal.applyCommand}`);
+                if (signal.reconciliationState === "unsafe_inactive" && signal.recoveryCommand)
+                    lines.push(`    Recovery: ${signal.recoveryCommand}`);
             }
         }
     }
     const resources = Array.isArray(retiredResources?.resources) ? retiredResources.resources : [];
     const todoReconciliation = status.signals?.some((signal) => signal.kind === "todo_reconciliation") ?? false;
+    const unsafeInactiveTodo = status.signals?.some((signal) => signal.kind === "todo_reconciliation" && signal.reconciliationState === "unsafe_inactive") ?? false;
     if (resources.length > 0) {
         lines.push("");
         lines.push("Retired native resources:");
@@ -116,6 +119,10 @@ export function renderDoctorStatus(status, retiredResources) {
             lines.push("  3. Then retry Agentera once a retry command is available.");
         }
     }
+    else if (unsafeInactiveTodo) {
+        lines.push("");
+        lines.push("Next: complete the owner correction and replan before any TODO mutation.");
+    }
     else if (todoReconciliation) {
         lines.push("");
         lines.push("Next: run the reported TODO reconciliation preview, review its bounded effect, then use its exact apply_command.");
@@ -170,7 +177,7 @@ export function cmdDoctor(args, io = {}) {
         status.signals.push({
             status: APP_MANUAL_REVIEW_NEEDED,
             kind: "todo_reconciliation",
-            message: `action-required: TODO reconciliation is ${todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "in an invalid lifecycle state"}`,
+            message: `action-required: TODO reconciliation is ${todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_inactive" ? "unsafe inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "in an invalid lifecycle state"}`,
             reconciliationState: todoReconciliation.state,
             reconciliationCounts: todoReconciliation.counts,
             reconciliationOmittedCount: todoReconciliation.omitted_count,