agentera 3.0.0-dev.20 → 3.0.0-dev.21

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

@@ -79,14 +79,12 @@ doctor:
     - codebase quality audit findings
     - inspektera architecture, test, dependency, or documentation audit output
   adjacent_surfaces:
-    project_artifact_health: agentera health
     codebase_audit: /agentera audit routes to inspektera
     setup_specific_diagnostics: packages/cli/src/setup/doctor.ts
   rationale: >-
     Decision 45 rejects `bundle-status` as too narrow and rejects an alias for
-    release-clean vocabulary. `doctor` is Agentera CLI/install/runtime
-    self-check vocabulary only; artifact health and codebase audits remain owned
-    by `agentera health` and inspektera.
+     release-clean vocabulary; `doctor` is the CLI/install/runtime self-check
+     vocabulary, while artifact health and codebase audits remain separate concerns.
 schema:
   status: implemented_runtime_introspection
   command: schema
@@ -328,8 +326,9 @@ structured_output:
             `agentera prime --format json` may include one bounded `decision_attention`
             payload when returned decisions require satisfaction review. The payload
             derives from the same `_decision_context_entry` and
-            `_decision_satisfaction_context` semantics as `agentera decisions --format
-            json`, never infers satisfaction, never mutates `.agentera/decisions.yaml`,
+             `_decision_satisfaction_context` semantics as bounded `agentera state
+             decisions list --limit 20 --format json` plus exact `state decisions
+             get --number N`, never infers satisfaction, never mutates `.agentera/decisions.yaml`,
             keeps top-level attention bounded, and must not change `next_action`
             routing priority.
           evidence_context_target_contract: evidence_context_target_contract
@@ -361,8 +360,6 @@ startup_completeness:
     artifact reads for normal capability startup.
   current_cli_fallback:
     - agentera plan --format json
-    - agentera docs --format json
-    - agentera progress --format json
   state_families_added:
     - plan task details, dependencies, acceptance criteria, and evidence summaries
     - docs artifact mapping and source-contract completeness metadata
@@ -405,7 +402,7 @@ evidence_context_target_contract:
           - vision
           - profile
         fallback_commands:
-          - agentera decisions --format json
+          - agentera state decisions list --limit 20 --format json
         caveats:
           - profile-derived state is stale and must not trigger profile refresh
           - orchestration_context is incomplete for missing decisions, vision, and profile state
@@ -419,14 +416,6 @@ evidence_context_target_contract:
           - previous_plan_archived pointer
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera progress --format json
-        included_state:
-          - latest progress cycles
-          - latest verification text
-          - cycle provenance
-        missing_state:
-          - explicit retry-attempt count
-        raw_artifact_reads_required: false
       - command: agentera docs --format json
         included_state:
           - artifact mapping
@@ -435,14 +424,6 @@ evidence_context_target_contract:
           - indexed document freshness
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera health --format json
-        included_state:
-          - latest audit
-          - dimension grades
-          - findings
-          - trajectory
-        missing_state: []
-        raw_artifact_reads_required: false
       - command: agentera todo --format json
         included_state:
           - open 2.3.10 evidence-context TODO
@@ -450,15 +431,6 @@ evidence_context_target_contract:
           - known open issues
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera decisions --format json
-        included_state:
-          - decisions 51 and 52 with complete context
-          - compacted historical decision summaries
-        missing_state:
-          - full context for 40 compacted historical entries
-        raw_artifact_reads_required: false
-        caveats:
-          - compacted decisions expose missing_fields and caveats instead of reconstructed history
     last_resort_raw_fallbacks:
       - reason: archived previous-plan status is not exposed by routine CLI state
         path: .agentera/archive/PLAN-2026-05-15-2-3-9-dokumentera-closeout-context-source-contract.yaml
@@ -514,14 +486,14 @@ evidence_context_target_contract:
         source: agentera plan --format json entries.acceptance
         fallback: none when complete_for_plan_artifact is true
       - family: progress_verification
-        source: agentera progress --format json latest verification
-        fallback: agentera progress --format json
+        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
       - family: health_state
-        source: agentera health --format json latest audit
-        fallback: agentera health --format json
+        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
@@ -530,7 +502,7 @@ evidence_context_target_contract:
         fallback: listed existing CLI commands before raw reads
     optional_or_caveated_for_normal_task_evaluation:
       - family: decisions_context
-        source: agentera decisions --format json
+        source: agentera state decisions list --limit 20 --format json
         caveat: compacted historical entries remain incomplete and must not be reconstructed from raw artifacts
       - family: vision_context
         source: hej startup only when included by capability context

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -186,16 +186,17 @@ audience_namespaces:
         canonical_shape: agentera check compact [--project PATH] [--mode check|fix] [--format text|json]
         delegates_from:
           - compact
-          - gate
         notes: >-
-          `check compact` in default check-only mode matches today's `agentera gate`.
-          Artifact compaction budget checks remain on `check compact`.
-    legacy_top_level_aliases:
-      - validate
+          `check compact` owns check-only and fix modes. Top-level `gate` was
+          removed in Phase 3; artifact compaction budget checks remain on
+          `check compact`.
+    transitional_top_level_aliases:
+      - query
+      - compact
       - verify
+      - stats
       - lint
-      - gate
-      - compact
+      - validate
 help_grouping:
   agent: [prime, state, schema, capabilities]
   user: [upgrade, doctor, report]
@@ -263,25 +264,25 @@ plan_routing_distinction:
   state_read:
     invocation: agentera state plan
     legacy_alias: >-
-      Top-level `agentera plan` was removed on the npm 3.x CLI in Phase 3; use
-      `agentera state plan`.
+      Top-level `agentera plan` is capability routing, not a state-read alias;
+      use `agentera state plan` for project state.
     surface: CLI routine state read
     meaning: >-
       Read-only access to the active plan artifact summary, tasks, acceptance
       criteria, evidence, and source_contract. Does not invoke Planera workflow
       execution.
   capability_top:
-    invocation: agentera planera
+    invocation: agentera plan
     surface: CLI top-level capability routing command
     meaning: >-
-      Emits Planera routing guidance prose/schemas pointers. Does not replace
+      Emits plan capability routing guidance prose/schemas pointers. Does not replace
       `state plan` reads or `/agentera plan` slash routing. Capability startup JSON
-      for Planera remains `agentera prime --context planera --format json`.
+      remains `agentera prime --context plan --format json`.
   agent_guidance: >-
     Use `/agentera plan` when the user wants planning work routed to Planera; use
     `agentera state plan` when the agent needs plan artifact state; use
-    `agentera planera` for capability routing guidance; use
-    `agentera prime --context planera` for bounded Planera startup context.
+    `agentera plan` for capability routing guidance; use
+    `agentera prime --context plan` for bounded plan startup context.
 migration_phases:
   phase_1:
     name: add_namespaces_and_delegate
@@ -344,9 +345,9 @@ command_tree_target:
 removed_top_level_commands:
   # Phase 3 on npm 3.x: removed from help and dispatch (unsupported_target)
   - hej
+  - status
   - describe
   - gate
-  - plan
   - progress
   - health
   - todo
@@ -355,6 +356,20 @@ removed_top_level_commands:
   - objective
   - experiments
 
+removed_top_level_corrections:
+  # Unsupported Phase 3 names return these canonical runnable corrections.
+  - { legacy: hej, canonical: prime }
+  - { legacy: status, canonical: prime }
+  - { legacy: describe, canonical: schema }
+  - { legacy: gate, canonical: "check compact" }
+  - { legacy: progress, canonical: "state progress" }
+  - { legacy: health, canonical: "state health" }
+  - { legacy: todo, canonical: "state todo" }
+  - { legacy: decisions, canonical: "state decisions" }
+  - { legacy: docs, canonical: "state docs" }
+  - { legacy: objective, canonical: "state objective" }
+  - { legacy: experiments, canonical: "state experiments" }
+
 transitional_stderr_aliases:
   # Still delegate with one-line stderr deprecation on npm 3.x
   - { legacy: query, canonical: "state query" }

package/bundle/references/meta/documentation-inventory.md

@@ -23,6 +23,7 @@ guides — not under `docs/`.
 | Human vocabulary index | `references/cli/vocabulary.md` |
 | Benchmark contract | `references/analysis/startup-measurement-contract.yaml` |
 | Benchmark runbook | `references/analysis/benchmark.md` |
+| State storage, path, API, compatibility, and output authority | `references/artifacts/state-storage-authority.yaml` |
 | JSON surface budgets | `scripts/json_output_surface_manifest.yaml` |
 | Project drafts | `docs/` (gitignored except `docs/README.md`, `docs/packaging/`, `docs/consolidation/`) |
 

package/bundle/skills/agentera/capabilities/audit/schemas/artifacts.yaml

@@ -8,7 +8,9 @@ ARTIFACTS:
       Audit writes audit entries with per-dimension grades, findings with
       severity and confidence scores, trend comparisons, and de facto
       architecture patterns. During evaluation startup, Audit consumes health
-      state through CLI `evidence_context` before raw health artifact fallback.
+      state through CLI `evidence_context`, then bounded `agentera state health
+      list --limit 20 --format json` and exact `state health get --number N`.
+      Raw health reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
     artifact_id: vision
@@ -22,9 +24,11 @@ ARTIFACTS:
     artifact_id: decisions
     local_role: consumes
     description: >-
-      Audit consumes decision caveats through CLI `evidence_context` and the
-      listed `agentera decisions --format json` fallback before raw decisions artifact fallback.
-      Compacted decision caveats must be preserved rather than reconstructed.
+      Audit consumes decision caveats through CLI `evidence_context`, then
+      bounded `agentera state decisions list --limit 20 --format json` discovery
+      and exact `state decisions get --number N` retrieval. Raw decision reads
+      are diagnostic-only for corruption or CLI-defect investigation. Compacted
+      decision caveats must be preserved rather than reconstructed.
   4:
     id: A4
     artifact_id: todo
@@ -33,21 +37,25 @@ ARTIFACTS:
       Audit reads this to avoid re-reporting known issues and writes to it
       with user confirmation when filing
       critical and warning findings. During evaluation startup, known TODO state is
-      consumed through CLI `evidence_context` before raw TODO artifact fallback.
+      consumed through CLI `evidence_context`; raw TODO reads are diagnostic-only
+      for corruption or CLI-defect investigation.
   5:
     id: A5
     artifact_id: progress
     local_role: consumes
     description: >-
       Audit consumes latest progress verification and progress caveats through
-      CLI `evidence_context` before raw progress artifact fallback.
+      CLI `evidence_context`, then bounded `agentera state progress list --limit
+      20 --format json` discovery and exact `state progress get --number N`
+      retrieval. Raw progress reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   6:
     id: A6
     artifact_id: plan
     local_role: consumes
     description: >-
       Audit consumes evaluation target and plan criteria through CLI
-      `evidence_context` before raw plan artifact fallback. The plan's Created date
+      `evidence_context` before any diagnostic-only raw plan read. The plan's Created date
       still provides the artifact-current-state baseline when that state is needed.
   7:
     id: A7
@@ -55,8 +63,8 @@ ARTIFACTS:
     local_role: consumes
     description: >-
       Audit treats design state as optional during evidence-context startup;
-      missing design caveats from CLI `evidence_context` are preserved before any raw
-      design artifact fallback.
+      missing design caveats from CLI `evidence_context` are preserved before any
+      diagnostic-only raw design read.
   8:
     id: A8
     artifact_id: docs
@@ -65,7 +73,7 @@ ARTIFACTS:
       Audit reads this first to resolve project-local artifact mappings
       and checks the versioning convention for the version health dimension. During
       evaluation startup, docs state and version-boundary caveats are consumed through
-      CLI `evidence_context` before raw docs artifact fallback.
+      CLI `evidence_context` before any diagnostic-only raw docs read.
   9:
     id: A9
     artifact_id: profile

package/bundle/skills/agentera/capabilities/audit/schemas/validation.yaml

@@ -66,25 +66,25 @@ VALIDATION:
     id: V7
     rule: evidence_context_first
     description: >-
-      Audit evaluation startup MUST begin with `agentera prime --context
-      audit --format json` and use complete CLI `evidence_context` before
-      raw plan, progress, docs, health, TODO, or decisions artifacts.
+       Audit evaluation startup MUST begin with `agentera prime --context
+       audit --format json` and use complete CLI `evidence_context` before
+       bounded state list/get contracts for plan, progress, docs, health, TODO,
+       or decisions. Raw artifact access is diagnostic-only.
     severity: critical
     checks:
-      - "Evidence context is requested through prime --context before raw artifacts"
-      - "Complete evidence_context is used for evaluation target, criteria, evidence, caveats, and residual risks"
+       - "Evidence context is requested through prime --context before bounded state list/get"
   8:
     id: V8
     rule: evidence_context_fallback_before_raw
     description: >-
       When evidence_context is absent, incomplete, or caveated for needed state,
-      Audit MUST run listed existing CLI fallback commands before any last-resort
-      raw artifact read.
+       Audit MUST run listed bounded CLI fallback commands before any
+       diagnostic-only raw artifact read.
     severity: critical
     checks:
-      - "evidence_context.fallback_commands are attempted before raw artifact reads"
-      - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
-      - "Raw artifact reads are last-resort diagnostics, not normal evaluation startup"
+       - "evidence_context.fallback_commands are attempted before diagnostic-only raw reads"
+       - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
+       - "Raw artifact reads are diagnostic-only, not normal evaluation startup"
   9:
     id: V9
     rule: evidence_context_caveats_preserved

package/bundle/skills/agentera/capabilities/build/schemas/artifacts.yaml

@@ -29,24 +29,29 @@ ARTIFACTS:
     local_role: produces_and_consumes
     description: >-
       Operational cycle log. Build consumes latest progress evidence from
-      execution_context first, then appends one entry per cycle with mandatory
-      Verified field. Compacted by applying schema COMPACTION rules.
+      execution_context first, then bounded `agentera state progress list --limit
+      20 --format json` discovery or exact `state progress get --number N`
+      retrieval, and appends one entry per cycle with mandatory Verified field.
+      Compacted by applying schema COMPACTION rules.
   5:
     id: A5
     artifact_id: health
     local_role: consumes
     description: >-
       Build consumes health state from execution_context and included status
-      state before direct reads, focusing on critical and degraded findings for
-      work selection.
+      state before bounded `agentera state health list --limit 20 --format json`
+      discovery or exact `state health get --number N` retrieval, focusing on
+      critical and degraded findings for work selection. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
     artifact_id: decisions
     local_role: consumes
     description: >-
-      Build consumes decision caveats and fallback commands from
+      Build consumes decision caveats and bounded list/get fallback commands from
       execution_context first. Firm (DL1) entries are constraints and exploratory
-      (DL3) entries are uncertain foundations during work selection.
+      (DL3) entries are uncertain foundations during work selection. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   7:
     id: A7
     artifact_id: plan

package/bundle/skills/agentera/capabilities/discuss/schemas/artifacts.yaml

@@ -5,8 +5,9 @@ ARTIFACTS:
     local_role: produces_and_consumes
     description: >-
       Reasoning trail with confidence labels. Discuss reads existing decisions
-      through `agentera state decisions --format json` and its source_contract
-      to avoid re-deliberation, and writes new decision entries with confidence
+      through bounded `agentera state decisions list --limit 20 --format json`
+      discovery plus exact `agentera state decisions get --number N --format json`
+      retrieval and its source_contract to avoid re-deliberation, and writes new decision entries with confidence
       (DL1 firm, DL2 provisional, DL3 exploratory). Compact older entries by
       applying schema COMPACTION rules; incomplete compacted entries are
       caveated context, not a reason for historical reconstruction during

package/bundle/skills/agentera/capabilities/document/schemas/artifacts.yaml

@@ -8,8 +8,8 @@ ARTIFACTS:
       documentation index. Document writes and reads doc root, style
       conventions, auto-generated doc tracking, project-local artifact mappings,
       and a status index (current/stale/missing) for tracked docs. During
-      closeout, Document consumes docs state through CLI `closeout_context`
-      before raw artifact fallback.
+      closeout, Document consumes docs state through CLI `closeout_context`;
+      raw reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
     artifact_id: vision
@@ -24,22 +24,29 @@ ARTIFACTS:
     description: >-
       Document reads this during explore-and-generate mode to understand
       recent project context. During closeout, latest progress evidence and
-      verification pointers are consumed through CLI `closeout_context` before
-      raw artifact fallback.
+      verification pointers are consumed through CLI `closeout_context`, then
+      bounded `agentera state progress list --limit 20 --format json` discovery
+      or exact `state progress get --number N` retrieval. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   4:
     id: A4
     artifact_id: decisions
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode for project
-      context and decision awareness.
+      context and decision awareness through bounded `agentera state decisions
+      list --limit 20 --format json` discovery or exact `state decisions get
+      --number N` retrieval. Raw reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   5:
     id: A5
     artifact_id: health
     local_role: consumes
     description: >-
-      Document reads this to discover documentation gaps surfaced
-      during health audits.
+      Document reads this to discover documentation gaps surfaced during health
+      audits through bounded `agentera state health list --limit 20 --format
+      json` discovery or exact `state health get --number N` retrieval. Raw reads
+      are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
     artifact_id: todo
@@ -48,7 +55,7 @@ ARTIFACTS:
       Document writes to this when code diverges from docs (per DTC,
       the code is wrong). Also reads for context during documentation work;
       closeout blocker state is consumed through CLI `closeout_context` before
-      raw artifact fallback.
+      any diagnostic-only raw TODO read.
   7:
     id: A7
     artifact_id: design

package/bundle/skills/agentera/capabilities/document/schemas/validation.yaml

@@ -85,12 +85,13 @@ VALIDATION:
     id: V9
     rule: closeout_context_first
     description: >-
-      During final synchronization, Document MUST use `agentera prime
-      --context document --format json` and its `closeout_context`
-      before reading TODO, docs, changelog, or progress artifacts directly.
-      Complete closeout context is the normal source for mappings, version
-      policy, blockers, boundaries, progress evidence, benchmark evidence,
-      caveats, fallback commands, raw-read policy, and completeness.
+       During final synchronization, Document MUST use `agentera prime
+       --context document --format json` and its `closeout_context`
+       before using bounded state list/get contracts for TODO, docs, changelog,
+       or progress. Raw artifact access is diagnostic-only or a write target.
+        Complete closeout context is the normal source for mappings, version
+        policy, blockers, boundaries, progress evidence, benchmark evidence,
+        caveats, fallback commands, raw-read policy, and completeness.
     severity: critical
     checks:
       - "Closeout starts from status capability context"
@@ -100,15 +101,14 @@ VALIDATION:
     id: V10
     rule: closeout_fallback_before_raw
     description: >-
-      If closeout context is incomplete or caveated, Document MUST run the
-      listed existing CLI fallback commands before any last-resort raw artifact
-      read. No unsupported capability-name command or new closeout command may
-      be introduced.
+       If closeout context is incomplete or caveated, Document MUST run the
+       listed bounded CLI fallback commands before any diagnostic-only raw
+       artifact read. No unsupported capability-name command or new closeout command may
+        be introduced.
     severity: critical
     checks:
-      - "Listed CLI fallback commands run before raw artifact reads"
-      - "Raw reads are last-resort diagnostics or write targets only"
-      - "No unsupported capability-name command is introduced"
+       - "Listed bounded CLI fallback commands run before diagnostic-only raw reads"
+       - "Raw reads are diagnostic-only or write targets"
   11:
     id: V11
     rule: closeout_caveat_preservation

package/bundle/skills/agentera/capabilities/orchestrate/schemas/artifacts.yaml

@@ -15,16 +15,20 @@ ARTIFACTS:
     local_role: consumes
     description: >-
       Orchestrate consumes progress verification state from the returned
-      orchestration context first, then routine CLI fallback output before any
-      last-resort raw artifact read for the Step 3 presence check.
+      orchestration context first, then bounded `agentera state progress list
+      --limit 20 --format json` fallback output. Exact detail uses `state
+      progress get --number N`; raw reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   3:
     id: A3
     artifact_id: health
     local_role: consumes
     description: >-
       Orchestrate consumes returned health state first after plan completion to
-      decide whether to start a new plan cycle; raw reads are last-resort after
-      listed CLI fallbacks.
+      decide whether to start a new plan cycle; bounded `agentera state health
+      list --limit 20 --format json` and exact `state health get --number N`
+      are the fallback contracts. Raw reads are diagnostic-only for corruption
+      or CLI-defect investigation.
   4:
     id: A4
     artifact_id: todo
@@ -37,9 +41,11 @@ ARTIFACTS:
     artifact_id: decisions
     local_role: consumes
     description: >-
-      Orchestrate consumes included decision context or the listed
-      `agentera decisions --format json` fallback before raw access, preserving
-      firm constraints, exploratory uncertainties, and compacted-entry caveats.
+      Orchestrate consumes included decision context or bounded
+      `agentera state decisions list --limit 20 --format json` discovery and
+      exact `state decisions get --number N` retrieval, preserving firm
+      constraints, exploratory uncertainties, and compacted-entry caveats.
+      Raw reads are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
     artifact_id: vision
@@ -61,5 +67,5 @@ ARTIFACTS:
     local_role: consumes
     description: >-
       Orchestrate uses docs mapping from CLI startup context first to resolve
-      project-local artifact mappings before any last-resort raw artifact read
-      or artifact write.
+      project-local artifact mappings before any diagnostic-only raw artifact
+      read or artifact write.