agentera 3.0.0-dev.22 → 3.0.0-dev.23

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
 

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,7 @@
 
 ### Changed
 
+- 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.
@@ -23,6 +24,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.

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

@@ -13,7 +13,8 @@ authority:
     Runtime readers, writers, validators, tests, help, and capability source
     contracts may project this authority but must not create a second map of
     archive paths, API verbs, compatibility classes, mutable overlay fields,
-    failure classes, or byte limits.
+    amendment revision paths, legacy label coexistence rules, failure classes,
+    or byte limits.
   implementation_boundary: >-
     This contract does not migrate legacy state or change existing plan and
     vision archive behavior. The maintenance-only Git backfill surface declared
@@ -716,6 +717,67 @@ overlays:
     inference: forbidden from commits, downstream references, summaries, or Git history
     protected_review: unresolved decisions remain visible and never block archive storage
 
+revisions:
+  location: .agentera/revisions/decisions.yaml
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionRevision.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    A mapping keyed by stable decision ID. Each value is an ordered list of
+    immutable revision records carrying only authority-declared amendable
+    content paths plus revision provenance. A revision never replaces the
+    immutable numbered archive record and never replaces the satisfaction
+    overlay; it is additional immutable evidence composed at read time.
+  amendable_paths:
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  identity_paths:
+    - number
+  temporal_paths:
+    - date
+  separation_from_overlay: >-
+    Amendments never touch satisfaction overlay paths. Satisfaction updates
+    remain under overlays; content amendments remain under revisions. Each
+    authority composes its own evidence and neither rewrites the other.
+  immutability: >-
+    Original numbered archive records remain immutable historical evidence.
+    Revisions are additional immutable evidence appended in declared order;
+    no revision overwrites, reorders, or deletes a prior revision. A revision
+    is byte-stable after publication and an identical revision is an
+    idempotent replay.
+  provenance: >-
+    Revision evidence carries revision provenance only. It is never labeled
+    as historical archive provenance. A revision bootstrapped from a complete
+    legacy projection record may carry degraded_projection provenance and
+    never historical_archive provenance.
+  publication_order:
+    - validate_target_identity
+    - validate_amendment_vocabulary
+    - stage_revision
+    - publish_revision
+    - update_effective_projection
+  apply_state: implemented
+  apply_state_note: >-
+    The revision authority and amend command publish record-local amendments
+    with recovery. A valid dry-run reports the exact revision, effective record,
+    and projection effect without writing any file. Apply writes a
+    record-local override to the revision document only (preserving unrelated
+    entries' bytes), retries converge on a stable revision identity, and an
+    identical re-submission is an idempotent replay. The decisions projection
+    is never rewritten by an amendment; effective detail composes
+    base→revisions→overlay. Amend execution still refuses before side effects
+    for an unsafe target-only change, a duplicate-revision conflict, a stale
+    base hash, or an unsafe target identity, returning an actionable retry or
+    repair action. Discover the contract with
+    `agentera state decisions explain --verb amend --format json`.
+
 projections:
   archive:
     role: complete immutable historical detail
@@ -1369,6 +1431,26 @@ compatibility:
     Compatibility reports provenance and availability only. It does not
     reconstruct missing decision fields, promote summaries to full records, or
     use Git history to satisfy a current source contract.
+  legacy_label_coexistence:
+    dimensions:
+      - confidence
+    current_vocabulary: [firm, provisional, exploratory]
+    current_vocabulary_ref: protocol.yaml DECISION_LABELS (DL1-DL3)
+    known_legacy_examples: [high, medium, low]
+    classification_rule: >-
+      A label value is unsupported when it is not in current_vocabulary. An
+      unsupported inherited label on a record the caller did not touch is
+      explicit legacy state: it is preserved byte- and value-semantically,
+      reported as a legacy caveat, never coerced to the current vocabulary,
+      and never blocks an append, satisfaction update, or amend on a
+      different target. A confidence label supplied by append or amend is new
+      or amended content and must be a current_vocabulary value; otherwise the
+      operation rejects before side effects.
+    no_silent_normalization: >-
+      Unsupported inherited labels are never rewritten to current values
+      without explicit user migration consent. Reads classify them as legacy
+      and never silently promote them to current vocabulary or claim stronger
+      provenance than exists.
 
 budgets:
   schema_version: agentera.stateOutputBudget.v1
@@ -1425,14 +1507,29 @@ budgets:
         max_latency_ms: 15000
         max_heap_delta_bytes: 268435456
       serialized_output:
-        prime_capability_context_max_utf8_bytes: 50000
+        # Generic prime capability capsules retain the full instructions body.
+        # The status capability is a separate one-call surface with a stricter
+        # bound declared below and in the JSON surface manifest.
+        prime_capability_context_max_utf8_bytes: 55000
+        prime_status_context_max_utf8_bytes: 25000
     surfaces:
       prime_briefing:
         manifest_id: prime-briefing
-        max_utf8_bytes: 35000
+        # Bounded default decision brief (Plan Task 3): the bare default
+        # `agentera prime --format json` projects the full orientation payload
+        # to routing-essential leaves plus named recovery pointers for omitted
+        # rich state. Pretty UTF-8 JSON + trailing newline is measured and an
+        # over-budget brief is rejected in favor of a bounded degraded envelope;
+        # diagnostics stay on stderr. prime_dashboard keeps full fidelity.
+        max_utf8_bytes: 12000
       prime_dashboard:
         manifest_id: prime-dashboard
         max_utf8_bytes: 35000
+      prime_status_context:
+        manifest_id: prime-status-context
+        # Status startup includes the full instructions capsule as well as the
+        # bounded Task 3 decision brief. Diagnostics remain on stderr.
+        max_utf8_bytes: 25000
       prime_sparse:
         manifest_id: prime-fields-sparse
         max_utf8_bytes: 28000
@@ -1441,6 +1538,15 @@ budgets:
       Omit optional historical detail and retain counts, actionable IDs,
       compatibility, source_contract, and exact get/list command pointers. The
       caller must be able to distinguish omitted detail from unavailable detail.
+      The bare default briefing is a bounded decision brief: every required
+      top-level field stays present (content projected to routing-essential
+      leaves), missing versus present-but-empty stays distinguishable through
+      state_presence, and each omitted rich-state family carries a named
+      authoritative recovery command. When even the projected brief exceeds the
+      budget, emit a measured bounded degraded envelope that keeps command,
+      status, mode, state_presence, a brief source_contract, and the
+      byte-budget error with a recovery command; never emit an over-budget
+      payload. Diagnostics are measured on stderr separately.
   validation:
     authority: this file plus the referenced JSON surface manifest
     drift_rule: tests fail if manifest IDs or byte values disagree with this contract

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -62,7 +62,7 @@ slash_route_aliases:
     Decision 43 aliases are exact `/agentera <alias>` routes, not CLI state
     commands. Teaching `status`, `build`, `audit`, or `document` as CLI commands
     would blur route vocabulary with state access; the shared word `plan` keeps
-    separate meanings as `/agentera plan` routing and `agentera plan` state.
+     separate meanings as `/agentera plan` routing and `agentera state plan` state.
 doctor:
   status: implemented_hard_rename
   command: doctor
@@ -170,7 +170,7 @@ structured_output:
             - summary_fields
             - entry_fields
           complete_semantics: >-
-            When `complete_for_plan_artifact` is true, `agentera plan --format
+            When `complete_for_plan_artifact` is true, `agentera state plan --format
             json` includes plan summary metadata, tasks, dependencies, acceptance
             criteria, evidence, overall acceptance, surprises, and previous-plan
             archive references needed for normal read-only startup/evaluation
@@ -222,7 +222,8 @@ structured_output:
       fields:
         - command
         - status
-        - bundle
+        - app_home
+        - app
         - mode
         - profile
         - v1_migration
@@ -233,7 +234,10 @@ structured_output:
         - progress
         - objective
         - state_presence
+        - project_integration
         - attention
+        - history
+        - runtime_lifecycle
         - decision_attention
         - next_action
         - orchestration_context
@@ -359,7 +363,7 @@ startup_completeness:
     before any raw artifact read. Complete startup state must never require raw
     artifact reads for normal capability startup.
   current_cli_fallback:
-    - agentera plan --format json
+     - agentera state plan --format json
   state_families_added:
     - plan task details, dependencies, acceptance criteria, and evidence summaries
     - docs artifact mapping and source-contract completeness metadata
@@ -406,7 +410,7 @@ evidence_context_target_contract:
         caveats:
           - profile-derived state is stale and must not trigger profile refresh
           - orchestration_context is incomplete for missing decisions, vision, and profile state
-      - command: agentera plan --format json
+      - command: agentera state plan --format json
         included_state:
           - active plan header and summary
           - task dependencies
@@ -416,7 +420,7 @@ evidence_context_target_contract:
           - previous_plan_archived pointer
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera docs --format json
+      - command: agentera state docs --format json
         included_state:
           - artifact mapping
           - version files
@@ -424,7 +428,7 @@ evidence_context_target_contract:
           - indexed document freshness
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera todo --format json
+      - command: agentera state todo --format json
         included_state:
           - open 2.3.10 evidence-context TODO
           - deferred 2.3.11 and 2.3.12 source-contract TODOs
@@ -481,22 +485,22 @@ evidence_context_target_contract:
     required_for_normal_task_evaluation:
       - family: evaluation_target
         source: plan/orchestration CLI state
-        fallback: agentera plan --format json
+        fallback: agentera state plan --format json
       - family: plan_criteria
-        source: agentera plan --format json entries.acceptance
+        source: agentera state plan --format json entries.acceptance
         fallback: none when complete_for_plan_artifact is true
       - family: progress_verification
         source: agentera state progress list --limit 20 --format json latest verification
         fallback: agentera state progress get --number N --format json
       - family: docs_state
-        source: agentera docs --format json summary and entries
-        fallback: agentera docs --format json
+        source: agentera state docs --format json summary and entries
+        fallback: agentera state docs --format json
       - family: health_state
         source: agentera state health list --limit 20 --format json latest audit
         fallback: agentera state health get --number N --format json
       - family: todo_state
-        source: agentera todo --format json known issues and source-contract TODOs
-        fallback: agentera todo --format json
+        source: agentera state todo --format json known issues and source-contract TODOs
+        fallback: agentera state todo --format json
       - family: source_contract
         source: evidence_context.source_contract
         fallback: listed existing CLI commands before raw reads
@@ -556,7 +560,8 @@ field_selection:
       fields:
         - command
         - status
-        - bundle
+        - app_home
+        - app
         - mode
         - profile
         - v1_migration
@@ -567,7 +572,10 @@ field_selection:
         - progress
         - objective
         - state_presence
+        - project_integration
         - attention
+        - history
+        - runtime_lifecycle
         - decision_attention
         - next_action
         - orchestration_context