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

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

@@ -1,12 +1,12 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: decisions
+    artifact: decisions
     local_role: produces_and_consumes
     description: >-
       Reasoning trail with confidence labels. Discuss reads existing decisions
       through bounded `agentera state decisions list --limit 20 --format json`
-      discovery plus exact `agentera state decisions get --number N --format json`
+       discovery plus exact `agentera state decisions get --id ID --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
@@ -14,7 +14,7 @@ ARTIFACTS:
       normal deliberation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Discuss may update project direction only with explicit user
@@ -22,28 +22,28 @@ ARTIFACTS:
       context during deliberation.
   3:
     id: A3
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Discuss may add tech debt items surfaced during deliberation only with
       explicit user confirmation. Severity per protocol SI1-SI4.
   4:
     id: A4
-    artifact_id: objective
+    artifact: objective
     local_role: produces_and_consumes
     description: >-
       Discuss may write optimization decisions only with explicit user
       confirmation when a decision feeds into what to optimize.
   5:
     id: A5
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Discuss reads this at session start to acknowledge high-confidence
       entries and avoid re-deliberating settled ground.
   6:
     id: A6
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Discuss reads this first to resolve project-local artifact mappings.

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: docs
+    artifact: docs
     local_role: produces_and_consumes
     description: >-
       Documentation contract with conventions, artifact mapping, and
@@ -12,44 +12,44 @@ ARTIFACTS:
       raw reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Document reads this to understand who the documentation is for
       and what tone to use.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     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`, then
       bounded `agentera state progress list --limit 20 --format json` discovery
-      or exact `state progress get --number N` retrieval. Raw reads are
+       or exact `state progress get --id ID` retrieval. Raw reads are
       diagnostic-only for corruption or CLI-defect investigation.
   4:
     id: A4
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode for project
       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
+       --id ID` retrieval. Raw reads are diagnostic-only for corruption or
       CLI-defect investigation.
   5:
     id: A5
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       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
+       json` discovery or exact `state health get --id ID` retrieval. Raw reads
       are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Document writes to this when code diverges from docs (per DTC,
@@ -58,21 +58,21 @@ ARTIFACTS:
       any diagnostic-only raw TODO read.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Document reads this to respect the declared aesthetic and voice
       when generating user-facing documentation.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Document reads this to calibrate documentation style preferences:
       detail level, tone, format.
   9:
     id: A9
-    artifact_id: changelog
+    artifact: changelog
     local_role: consumes
     description: >-
       Document reads this during closeout synchronization through CLI

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.