agentera 3.0.0-dev.23 → 3.0.0-dev.25

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: objective
+    artifact: objective
     local_role: produces_and_consumes
     description: >-
       Optimization target definition: metric, current value, target, constraints,
@@ -10,7 +10,7 @@ ARTIFACTS:
       canonical closure.
   2:
     id: A2
-    artifact_id: optimize_harness
+    artifact: optimize_harness
     local_role: produces
     description: >-
       Eval script that measures the metric and outputs structured JSON. Written
@@ -18,7 +18,7 @@ ARTIFACTS:
       Never modified during optimization cycles.
   3:
     id: A3
-    artifact_id: experiments
+    artifact: experiments
     local_role: produces_and_consumes
     description: >-
       Log of every experiment: hypothesis, method, change, metric before/after,
@@ -26,42 +26,42 @@ ARTIFACTS:
       suggestion. Optimize appends to this each cycle.
   4:
     id: A4
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Optimize inspects the last 3 entries to detect 3 consecutive failures
       before reporting exit status.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: produces
     description: >-
       Optimize writes to this when logging a failure pattern after 3
       consecutive failures.
   6:
     id: A6
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Optimize reads this during Orient for context on prior deliberations
       about the optimization objective.
   7:
     id: A7
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Optimize reads this to modulate experiment aggressiveness and constraint
       tolerance based on user preferences.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Optimize reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   9:
     id: A9
-    artifact_id: benchmark_context
+    artifact: benchmark_context
     local_role: consumes
     description: >-
       CLI-provided startup benchmark summary from `agentera prime --context

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
       Orchestrate consumes plan task queue state through
@@ -11,51 +11,51 @@ ARTIFACTS:
       retry-safe typed `record-evaluation` mutation before retry or blocking.
   2:
     id: A2
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Orchestrate consumes progress verification state from the returned
       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
+      progress get --id ID`; raw reads are diagnostic-only for corruption or
       CLI-defect investigation.
   3:
     id: A3
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Orchestrate consumes returned health state first after plan completion to
       decide whether to start a new plan cycle; bounded `agentera state health
-      list --limit 20 --format json` and exact `state health get --number N`
+      list --limit 20 --format json` and exact `state health get --id ID`
       are the fallback contracts. Raw reads are diagnostic-only for corruption
       or CLI-defect investigation.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces
     description: >-
       Orchestrate consumes TODO caveats from CLI startup context and writes
       blocked task logging only when a task exhausts its retry budget.
   5:
     id: A5
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       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
+      exact `state decisions get --id ID` 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
+    artifact: vision
     local_role: consumes
     description: >-
       Orchestrate consumes returned vision state or missing-state caveats during
       bootstrap when chaining research for vision-gap analysis.
   7:
     id: A7
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Orchestrate consumes returned profile status and caveats first for persona
@@ -63,7 +63,7 @@ ARTIFACTS:
       state and preserves the caveat.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Orchestrate uses docs mapping from CLI startup context first to resolve

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
       Current plan with tasks, dependencies, and behavioral acceptance criteria.
@@ -10,7 +10,7 @@ ARTIFACTS:
       session and may read existing plan context before replacing or refining it.
   2:
     id: A2
-    artifact_id: plan_archive
+    artifact: plan_archive
     local_role: produces
     description: >-
       Immutable, non-executable history created when a plan is complete or
@@ -18,45 +18,45 @@ ARTIFACTS:
       plan's open status rather than claiming completion.
   3:
     id: A3
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Plan reads this during Orient to understand project direction and
       align the plan with the vision.
   4:
     id: A4
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Plan reads firm (DL1) entries only as hard constraints for planning.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: consumes
     description: >-
       Plan reads this to identify related known
       issues that the plan should address.
   6:
     id: A6
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Plan reads this to factor structural issues into the plan.
   7:
     id: A7
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Plan reads this to understand what was built recently.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Plan reads this to calibrate planning depth and pattern preferences.
   9:
     id: A9
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Plan reads this first to resolve project-local artifact mappings and

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: profile
+    artifact: profile
     local_role: produces_and_consumes
     description: >-
       Decision profile with per-entry confidence scoring, permanence
@@ -9,7 +9,7 @@ ARTIFACTS:
       and Validate modes, then reads it for validation and update context.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Profile treats this as a high-signal source for extraction scripts.

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: todo
+    artifact: todo
     local_role: produces
     description: >-
       Open problems by severity. Research writes actionable findings here
@@ -9,14 +9,14 @@ ARTIFACTS:
       SF1-SF3. Build picks up changes automatically in its next cycle.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: produces
     description: >-
       Research may refine project direction with user confirmation when the
       analysis shifts thinking about the project's direction.
   3:
     id: A3
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Research reads the profile via research_context.profile from the prime

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

@@ -1,63 +1,63 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Status reads this for the briefing's project context.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Status reads this to identify unresolved decisions requiring follow-up.
   3:
     id: A3
-    artifact_id: plan
+    artifact: plan
     local_role: consumes
     description: >-
       Status reads this to identify the next executable task and plan progress.
   4:
     id: A4
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Status reads this for the briefing's "what shipped" context.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: consumes
     description: >-
       Status reads this to identify high-severity open items for routing.
   6:
     id: A6
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Status reads this for the health status line and attention items.
   7:
     id: A7
-    artifact_id: objective
+    artifact: objective
     local_role: consumes
     description: >-
       Status reads this to check for active optimization objectives.
   8:
     id: A8
-    artifact_id: experiments
+    artifact: experiments
     local_role: consumes
     description: >-
       Status reads this alongside the active optimization target to determine
       optimization status.
   9:
     id: A9
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Status reads this first to resolve project-local artifact mappings before
       reading other artifacts.
   10:
     id: A10
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Status reads this for project design status metadata (exists, stale, missing).
@@ -66,7 +66,7 @@ ARTIFACTS:
       artifact.
   11:
     id: A11
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Status reads this to report profile status (loaded/not found) in the briefing.

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

@@ -1,56 +1,56 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Vision writes and refines project direction, principles, personas,
       aspirations, and identity.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Vision reads this to detect shifted thinking during refine mode
       and to surface unresolved tensions with the vision.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Vision reads this during refine mode to understand what has been
       built since the vision was last updated.
   4:
     id: A4
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Vision reads this to understand structural realities that
       constrain or inform the vision.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: consumes
     description: >-
       Vision reads this during refine mode to detect recurring problems
       that suggest the vision needs adjustment.
   6:
     id: A6
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Vision reads this during codebase exploration to ensure the
       Identity section in project direction coheres with the visual system.
   7:
     id: A7
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Vision reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Vision reads this to calibrate the vision conversation: high-confidence

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

@@ -4,8 +4,9 @@
 # one entry. Decisions are referenced by build, optimize, and profile
 # for context on why choices were made.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority uses writer-owned decision, revision, and satisfaction
+# entity files. The numbered projection model below is retained only as an exact
+# legacy migration input schema; it is not an ordinary post-cutover contract.
 #
 # ── Field-by-field mapping: v1 DECISIONS.md → v2 decisions.yaml ──
 #
@@ -38,10 +39,22 @@ meta:
     and orchestrate for context on why choices were made.
   artifact_type: agent_facing
   path: ".agentera/decisions.yaml"
+  authority: legacy_migration_input_only
   producer: discuss
   consumers: [document, status, audit, optimize, orchestrate, plan, profile, build, discuss, vision]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: decisions
+  boundaries: [decision, decision_revision, decision_satisfaction]
+  retrieval:
+    list: agentera state decisions list --format json
+    get: agentera state decisions get --id ID --format json
+  mutation: agentera state decisions explain --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: DB
   COMPACTION: DX

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

@@ -2,7 +2,10 @@
 #
 # Documentation contract maintained by document. Tracks project doc
 # conventions, artifact path overrides, document index with status, coverage
-# metrics, and timestamped audit findings.
+# metrics, and timestamped audit findings. After durable entity cutover only
+# index entries become independent entities; mappings, conventions, coverage,
+# audit/editorial configuration, and other singleton sections retain
+# intentional whole-document authority in docs.yaml.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
 # following capability_schema_contract.yaml and protocol.yaml conventions.

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

@@ -275,16 +275,17 @@ PUBLICATION:
     id: EP1
     operation: publish
     command: >-
-      agentera state experiments publish --objective OBJECTIVE_ID --number N
+      agentera state experiments publish --objective ID [--id ID]
       --input EXPERIMENT.yaml --format json
     description: >-
       The typed state writer is the mutation authority. It validates the
-      objective, identity, caller entry, existing projection, and final bytes
-      before assigning number and atomically publishing one experiment.
+      objective, identity, caller entry, and canonical entity state before
+      atomically publishing one experiment entity.
   2:
     id: EP2
-    identity: '<objective-id>/experiment:<non-negative-integer>'
-    cli_owned_fields: [number]
+    identity: bare_ten_letter_id
+    classification: experiments
+    cli_owned_fields: [id, artifact, objective]
     retry: byte_equivalent_identity_is_idempotent
     collision: same_identity_with_different_content_fails
     description: >-
@@ -292,14 +293,14 @@ PUBLICATION:
       pre-publication failures preserve active and archive projection bytes.
   3:
     id: EP3
-    projection: uniform_10_40_50
-    durable_archive: objective_scoped_immutable_full_detail
+    projection: bounded_entity_list
+    durable_archive: not_applicable
     description: >-
-      Publication validates and durably publishes the full experiment under
-      the objective directory before replacing the compacted projection. The
-      projection still retains 10 full entries and 40 one-line summaries.
+      Publication validates and durably publishes one immutable canonical
+      experiment entity. Bounded list output never compacts entity records.
   4:
     id: EP4
+    classification: legacy_migration_source_provenance
     archive_path: '.agentera/<objective-root>/<objective>/archive/experiments/<experiment-number>.yaml'
     canonical_objective_root: optimize
     readable_legacy_objective_roots: [optimera]
@@ -333,14 +334,13 @@ RETRIEVAL:
   1:
     id: ER1
     list: >-
-      agentera state experiments list --objective OBJECTIVE_ID [--limit N]
+      agentera state experiments list --objective ID [--limit N]
       [--cursor TOKEN] --format json
     get: >-
-      agentera state experiments get --objective OBJECTIVE_ID --number N
-      --format json
+      agentera state experiments get --id ID --format json
     description: >-
-      List returns newest-first objective-scoped identities from the bounded
-      projection and immutable archive. Get returns one exact identity.
+      List returns newest-first objective-scoped canonical entities. Get returns
+      one exact entity by bare ID.
   2:
     id: ER2
     cursor: opaque_snapshot_cursor
@@ -408,22 +408,22 @@ ARCHIVE:
 VALIDATION:
   1:
     id: EV1
-    rule: unique_experiment_numbers
+    rule: unique_entity_ids
     severity: error
     description: >-
-      Experiment numbers must be unique and sequential.
+      Experiment IDs must be unique project-wide and match the canonical pattern.
     checks:
-      - "All experiment numbers are unique across active and archived entries"
-      - "Experiment numbers are sequential starting from 0"
+      - "All experiment IDs are unique across canonical entities"
+      - "Every ID is ten lowercase letters"
   2:
     id: EV2
     rule: required_fields
     severity: error
     description: >-
-      Each full-detail experiment entry must have: number, date, label,
+      Each full-detail experiment entity record must have: date, label,
       hypothesis, method, change, metric, status, and conclusion.
     checks:
-      - "number is present and is a non-negative integer"
+      - "the envelope has id and artifact fields"
       - "date is present and matches YYYY-MM-DD HH:MM"
       - "label is present and non-empty"
       - "hypothesis is present and non-empty"

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

@@ -5,8 +5,9 @@
 # per-dimension grades (A-F), per-dimension findings with confidence, and
 # trend analysis against the prior audit.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority is one health_audit entity per writer-owned file. The
+# numbered projection model below is retained only as an exact legacy migration
+# input schema; it is not an ordinary read or write contract after cutover.
 #
 # ── Field-by-field mapping: v1 HEALTH.md → v2 health.yaml ──
 #
@@ -53,10 +54,22 @@ meta:
     codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
+  authority: legacy_migration_input_only
   producer: audit
   consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: health
+  boundary: health_audit
+  retrieval:
+    list: agentera state health list --format json
+    get: agentera state health get --id ID --format json
+  mutation: agentera state health explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: HB
   COMPACTION: HX