agentera 3.0.0-dev.22 → 3.0.0-dev.25

package/README.md

@@ -12,9 +12,13 @@ npx -y agentera@next prime --format json
 npx -y agentera@next doctor --format json
 ```
 
-`prime` returns a bounded project and four-runtime lifecycle summary. `doctor`
-returns detailed read-only evidence and exact user actions. The status and
-project-integration projections consume the same lifecycle snapshot.
+`prime --format json` returns a bounded decision brief (at most 12000 UTF-8
+bytes); use `prime --dashboard --format json` for the full orientation payload.
+Status startup is one call: `prime --context status --format json` returns
+`capability_context.instructions` and bounded
+`capability_context.context.status_context` together (at most 25000 UTF-8
+bytes). Omitted detail names its authoritative recovery command. `doctor`
+returns detailed read-only evidence and exact user actions.
 
 ## Runtime lifecycle
 
@@ -56,10 +60,10 @@ and is projected by `agentera schema --format json`.
 
 ```bash
 agentera state plan list --format json
-agentera state plan get --plan PLAN_ID --format json
+agentera state plan get --id PLAN_ID --format json
 agentera state plan tasks list --limit 20 --format json
 agentera state experiments list --objective OBJECTIVE_ID --format json
-agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+agentera state experiments get --objective OBJECTIVE_ID --id EXPERIMENT_ID --format json
 ```
 
 Pages use opaque snapshot cursors, explicit omission fields, whole-entry output

package/bundle/.cursor/agents/agentera.md

@@ -4,4 +4,4 @@ description: Turn your coding agent into an engineering team.
 
 <!-- agentera: managed -->
 
-Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `capability_context.instructions` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/.opencode/agents/agentera.md

@@ -9,4 +9,4 @@ permission:
 
 <!-- agentera: managed -->
 
-Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `capability_context.instructions` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Changed
 
+- Changed the v2-to-v3 development upgrade to one full Git-backed command that requires every migration input to match tracked `HEAD`, activates entity authority last, and validates state and `prime` startup automatically. The optional dry-run is read-only; cross-major apply is one-way and has no rollback, restore, non-Git, or partial workflow.
+- Cut ordinary project state over to one canonical writer-owned file per entity. Public records now use only bare `id` and `artifact` identity, bounded `list` and exact `get --id` reads, and typed writers discovered through `agentera state <artifact> explain`; aggregate state files and ordinal selectors remain migration or historical evidence only.
+- Split lifecycle validation orchestration from the public validation facade while preserving its import surface and validation behavior.
 - Eliminated the monolithic `corpus.json` publication output from the extract CLI; report dry-run diagnostics now reference tier files and the `privacy.corpus_write` field is renamed to `privacy.tier_write`.
 - Changed `agentera check lint` verbosity checks to consume schema-owned full-file and per-entry word limits, skip no-limit and token-only dimensions, and report authority failures without fallback budgets.
 - Corrected packaged experiment-publication authority to declare validated objective-scoped archive-before-projection ownership and reject contradictory structured scope metadata.
@@ -11,6 +14,11 @@
 
 ### Added
 
+- Added post-cutover entity-backed default state views, bare-ID durability diagnostics, and read-only migration-manifest target validation while preserving legacy numbered behavior before cutover.
+- Added a Git-backed entity cutover owned by the full development-channel `upgrade --yes` command, with deterministic projection, marker-last authority activation, and bounded forward-only interruption recovery.
+- Added post-cutover decision entities for immutable bases and content revisions, replaceable satisfaction ownership, bare-ID exact and bounded reads, deterministic effective provenance, stale-base and transition validation, and explicit same-decision conflict detection; marker-absent projects retain the legacy numbered authority without dual writes.
+- Added the post-cutover progress entity writer and `state progress get|list` reads with bare IDs, one canonical file per cycle, atomic replay-safe publication, full provenance, bounded snapshot pagination, and no legacy projection or archive writes; legacy projects remain unchanged until the durable cutover marker exists.
+- Added authority-driven, one-file-per-entity storage primitives with secure project-wide IDs, symlink-safe discovery, conflict-safe publication, relationship validation, and `agentera check validate state` diagnostics.
 - Added an authoritative evidence-tier contract (`references/analysis/evidence-tier-authority.yaml`) and contract-model loader (`packages/cli/src/registries/evidenceTierContract.ts`) fixing the bounded full-evidence and signal tiers, supported Codex, Cursor, OpenCode, Copilot, and historical Claude source coverage, the consumer field-supply map including the latent startup-analysis reader, reserved signal semantics for the deferred glossary, and deterministic recovery outcomes for oversized, legacy, missing, corrupt, and incomplete state.
 - Added bounded tier publication and direct retrieval (`packages/cli/src/analytics/extractCorpus/evidenceTiers.ts`): complete local evidence is retained as independently bounded, source-family shards that split when exceeding the reader cap; a derived, content-addressable bounded signal tier carries only contract-required fields plus a resolvable `evidence_anchor`; generations are staged and revealed by an atomic current-pointer swap so no consumer observes a partial publication; and direct retrieval resolves a signal identity to its full record. The monolithic `corpus.json` write is eliminated; tiers are the only canonical publication output.
 - Added bounded tier-aware reads for usage analytics, report status, prime corpus coverage, startup analysis, and profile synthesis so every analytics consumer reads from bounded evidence shards one at a time instead of loading the monolithic `corpus.json`. A new `tierReader.ts` module projects contract compatibility states and recovery guidance, streams full-evidence records, and reads signal-tier metadata. A new `profileSignals.ts` module reads the bounded signal tier, assesses per-family retention sufficiency against the contract threshold, and resolves synthesized claims' evidence anchors to retained full-evidence shards. Legacy `corpus.json` remains a fallback when no tiers are published; oversized legacy state is never loaded whole.
@@ -23,6 +31,7 @@
 - Added `agentera state plan list` and `agentera state plan get --plan PLAN_ID` for deterministic, cursor-paginated active and archived plan retrieval, full-plan exact reads, lifecycle provenance, and explicit legacy, invalid, missing, and ambiguous archive outcomes.
 - 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 --number N [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes a record-local revision under `.agentera/revisions/decisions.yaml` that composes over the immutable numbered archive at read time. Apply never rewrites the decisions projection, preserves unrelated decisions' bytes (including comments, block scalars, quoting, and inherited legacy confidence labels), refuses a broken revision document or unsafe record-local boundary without side effects, retries converge on a stable revision identity, and an identical re-submission is an idempotent replay. Append, satisfaction update, and amend tolerate untouched inherited confidence labels as explicit legacy caveats while requiring current vocabulary for new or amended content.
 
 - 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 a canonical runtime lifecycle projection with deterministic snapshot identity, applicability, ownership, action classes, counts, and command eligibility for OpenCode, Codex, Cursor, and Copilot.
@@ -49,11 +58,11 @@
 - Changed `agentera state backfill` to remain optional local-Git enrichment: direct
   `--apply --force` revalidates the project, `HEAD`, candidate, reachability, and
   immutable target, while bounded history and no-remote behavior remain explicit.
-- Changed `agentera upgrade --only artifacts` to preview and apply deterministic
-  plan lifecycle migration for docs-mapped current plans and archives. Legacy
-  `active` and `completed` plan statuses become `open` and `complete` without
-  rewriting retained task evidence; archive recency now uses persisted creation
-  dates instead of file modification times.
+- Changed deterministic plan lifecycle migration to run inside the full
+  development-channel v2-to-v3 upgrade. Legacy `active` and `completed` plan
+  statuses become `open` and `complete` without rewriting retained task
+  evidence; archive recency uses persisted creation dates instead of file
+  modification times.
 - Changed plan reads to normalize legacy `active` and `completed` statuses within
   the current-plan and archive boundary, with structured diagnostics for
   malformed current plans and archives.
@@ -80,6 +89,7 @@
 
 ### Fixed
 
+- Fixed post-cutover routine query aliases, canonical-boundary Git recovery, migration-marker evidence binding, entity page byte caps, plan recovery guidance, and nested entity identity metadata.
 - Fixed the npm shim to diagnose a configured `AGENTERA_HOME` whose managed script is missing or not runnable before continuing through repository and `uvx` fallback resolution.
 - Fixed `agentera check lint` to report findings without failing by default, fail the same findings with `--strict`, and keep invalid input, authority failures, and validated plan publication nonzero.
 - Fixed schema/runtime alias parity: introspection now advertises exactly the six Phase 3 transitional aliases, Build startup and compaction guidance use canonical `agentera check compact`, check/fix output reports `command: "check compact"`, top-level `compact` remains behavior-compatible, and removed names such as `gate` return structured runnable corrections.

package/bundle/README.md

@@ -99,10 +99,10 @@ explicit omissions, and exact detail commands. The runtime contract is
 
 ```bash
 agentera state plan list --format json
-agentera state plan get --plan PLAN_ID --format json
+agentera state plan get --id PLAN_ID --format json
 agentera state plan tasks list --limit 20 --format json
 agentera state experiments list --objective OBJECTIVE_ID --format json
-agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+agentera state experiments get --objective OBJECTIVE_ID --id EXPERIMENT_ID --format json
 ```
 
 Plan list/get spans the active plan and immutable plan archives. Plan task
@@ -110,14 +110,15 @@ list/get is active-plan-only. Experiment retrieval merges its bounded projection
 with objective-owned immutable archives and reports detail as full, summary-only,
 or unavailable.
 
-The standard project state is:
+Ordinary mutable state uses one canonical file per entity. Every public record
+has only `id` and `artifact` identity, and is accessed through bounded `list`,
+exact `get --id`, and typed `agentera state <artifact> explain` write contracts.
+Do not edit files under `.agentera/entities/` directly.
+
+The intentional singleton project state is:
 
 - `.agentera/vision.yaml` — product direction
-- `.agentera/plan.yaml` — active and archived plans
-- `.agentera/progress.yaml` — shipped work and verification
-- `.agentera/decisions.yaml` — durable reasoning
-- `.agentera/health.yaml` — architecture and project health
-- `.agentera/docs.yaml` — documentation inventory and path/version mappings
+- `.agentera/docs.yaml` — documentation policy and path/version mappings
 - `TODO.md`, `CHANGELOG.md`, and `DESIGN.md` — human-facing project artifacts
 
 ## Capabilities

package/bundle/UPGRADE.md

@@ -169,27 +169,15 @@ npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
 npx -y agentera@next upgrade --channel development --project "$PWD" --yes
 ```
 
-The preview reports artifact migration, app migration, legacy cleanup, and any
-explicitly selected runtime work as separate phases. It does not cross the
-major boundary or mutate the project without `--yes`.
+The dry-run is optional and read-only. Before applying, commit or restore the
+complete v2 migration source: every input must be a regular file tracked by Git
+and unchanged at `HEAD`. The apply command performs the full runtime and entity
+state upgrade, then validates state and representative `prime` startup.
 
-Forward migration to v3 is one-way. Returning to the prior Python 2.x support
-line is permanently unsupported; review the development-channel preview before
-applying it.
-
-Useful phase filters are repeatable:
-
-```bash
-npx -y agentera@next upgrade --only artifacts --dry-run
-npx -y agentera@next upgrade --only runtime --dry-run
-npx -y agentera@next upgrade --only cleanup --dry-run
-```
-
-`--only runtime` filters the v2-to-v3 project-migration runtime phase. It does
-not select an Agentera runtime identity or limit lifecycle diagnosis. Use
-`--runtime all|opencode|codex|cursor|copilot` for lifecycle work; it cannot be
-combined with `--only`. Development-channel dry-runs without `--runtime` still
-observe all active lifecycle runtimes.
+Forward migration to v3 is one-way. Returning to the Python 2.x line is not
+supported, and cross-major apply has no rollback, restore, non-Git, or partial
+workflow. If an apply is interrupted, rerun the same full apply command to
+continue forward.
 
 ## Legacy state and optional Git enrichment
 
@@ -241,10 +229,8 @@ npx -y agentera@next prime --format json
 `upgrade --verify` without `--yes` is a read-only doctor and capability-context
 verification. With `--yes`, it runs those checks after the approved upgrade
 apply. Lifecycle selections with `--verify` require `--yes`.
-`upgrade --restore` restores the latest supported app-migration snapshot; it
-does not bypass lifecycle ownership or trust checks. For lifecycle partial
-failure, rerun the same preview and apply selection. Do not delete or hand-edit
-the ownership journal to force adoption.
+For lifecycle partial failure, rerun the same preview and apply selection. Do
+not delete or hand-edit the ownership journal to force adoption.
 
 `--force` applies only where the owning migration contract explicitly permits
 replacement. It does not convert user-owned resources into Agentera-owned

package/bundle/agents/openai.yaml

@@ -1,5 +1,5 @@
 display_name: Agentera
-description: Portable Agentera suite for Codex: one bundled skill with exact bare `/agentera` routing and twelve routed capabilities.
+description: "Portable Agentera suite for Codex: one bundled skill with exact bare `/agentera` routing and twelve routed capabilities."
 icon: AG
 brand_color: "#111827"
 default_prompt: Use $agentera to inspect project state and route to the right capability; exact bare `/agentera` uses the agentera prime dashboard path.

package/bundle/references/adapters/package-manifest-interface-model.yaml

@@ -64,11 +64,13 @@ record:
       owns:
         - bundled directories
         - bundled files
+        - generated-only bundled files
         - bundle skip rules
         - bundle mismatch standardization target
       required_fields:
         directories: list[repo_relative_path]
         files: list[repo_relative_path]
+        generated_files: list[generated_bundle_file]
         skip_parts: list[string]
         skip_suffixes: list[string]
     package_commands:

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

@@ -135,6 +135,15 @@ records:
           path: .opencode/package.json
         - id: cursor-hooks
           path: .cursor/hooks.json
+      generated_files:
+        - id: npx-bundle-marker
+          path: .agentera-npx-bundle.json
+          format: json
+          classification: active
+        - id: extract-corpus-parity
+          path: extract-corpus-parity.json
+          format: json
+          classification: active
       skip_parts:
         - __pycache__
         - .pytest_cache