agentera 3.0.0-dev.21 → 3.0.0-dev.23

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/artifacts/verbosity-budget-authority.yaml

@@ -0,0 +1,42 @@
+schema_version: agentera.verbosityBudgetAuthority.v1
+status: active_authority
+purpose: >-
+  Define which artifact schema owns each verbosity budget. Budget values stay
+  in the owning schema so validators and future consumers cannot introduce a
+  second value table.
+authority:
+  source: references/artifacts/verbosity-budget-authority.yaml
+  schema_directory: ../../skills/agentera/schemas/artifacts
+  single_source_rule: >-
+    Each supported artifact resolves to exactly one schema BUDGET group.
+    Missing, unreadable, duplicate, or malformed declarations are authority
+    errors; consumers must not substitute generic or historical limits.
+classification:
+  numeric_limit: A positive max_words value.
+  explicit_no_limit: A null max_words value.
+  non_word_unit: A positive token_budget value; it does not authorize word lint.
+  invalid_declaration: A missing, duplicate, ambiguous, or malformed declaration.
+scope:
+  supported_artifacts:
+    - artifact_id: changelog
+      schema: changelog.yaml
+    - artifact_id: decisions
+      schema: decisions.yaml
+    - artifact_id: design
+      schema: design.yaml
+    - artifact_id: docs
+      schema: docs.yaml
+    - artifact_id: experiments
+      schema: experiments.yaml
+    - artifact_id: health
+      schema: health.yaml
+    - artifact_id: objective
+      schema: objective.yaml
+    - artifact_id: plan
+      schema: plan.yaml
+    - artifact_id: progress
+      schema: progress.yaml
+    - artifact_id: todo
+      schema: todo.yaml
+    - artifact_id: vision
+      schema: vision.yaml

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