agentera 3.0.0-dev.3 → 3.0.0-dev.31

package/bundle/skills/agentera/route-phrases.yaml

@@ -0,0 +1,81 @@
+schema_version: agentera.route_phrase_registry.v1
+status: active_authority
+purpose: >-
+  Own the small, explicit inventory of deterministic leading phrases. Trigger
+  schemas remain semantic intent documentation and are not a phrase source.
+normalization: references/cli/hybrid-route-contract.yaml#phrase_matching
+rules:
+  stable_ids: Phrase IDs are permanent and never reassigned.
+  active_matching: Only entries with status active are eligible for matching.
+  global_collisions: >-
+    Normalized phrases must be unique across active and deprecated entries; a
+    collision is a validation error, never a precedence decision.
+  direct_route_collisions: >-
+    A phrase cannot duplicate or begin with a canonical capability name or a
+    primary alias under the direct-route grammar.
+  deprecation: >-
+    Remove no entry. Mark it deprecated, retain its ID and phrase, and set
+    replaced_by to an active registry ID. Deprecated phrases abstain.
+  prohibited_sources: [legacy_patterns, regexes, thresholds, bands, trigger_descriptions]
+
+phrases:
+  - id: RP_STATUS_PROJECT_BRIEFING
+    capability: status
+    phrase: show project briefing
+    status: active
+    evidence: [DEV-PHRASE-STATUS]
+  - id: RP_VISION_PRODUCT_DIRECTION
+    capability: vision
+    phrase: define product direction
+    status: active
+    evidence: [DEV-PHRASE-VISION]
+  - id: RP_DISCUSS_DECISION
+    capability: discuss
+    phrase: help me decide
+    status: active
+    evidence: [DEV-PHRASE-DISCUSS]
+  - id: RP_RESEARCH_EXTERNAL_PATTERNS
+    capability: research
+    phrase: study external patterns
+    status: active
+    evidence: [DEV-PHRASE-RESEARCH]
+  - id: RP_PLAN_IMPLEMENTATION
+    capability: plan
+    phrase: make an implementation plan
+    status: active
+    evidence: [DEV-PHRASE-PLAN]
+  - id: RP_BUILD_APPROVED_PLAN
+    capability: build
+    phrase: implement the approved plan
+    status: active
+    evidence: [DEV-PHRASE-BUILD]
+  - id: RP_OPTIMIZE_BOTTLENECK
+    capability: optimize
+    phrase: improve a measured bottleneck
+    status: active
+    evidence: [DEV-PHRASE-OPTIMIZE]
+  - id: RP_AUDIT_CODEBASE_HEALTH
+    capability: audit
+    phrase: check codebase health
+    status: active
+    evidence: [DEV-PHRASE-AUDIT]
+  - id: RP_DOCUMENT_PROJECT
+    capability: document
+    phrase: refresh project documentation
+    status: active
+    evidence: [DEV-PHRASE-DOCUMENT]
+  - id: RP_PROFILE_DECISION
+    capability: profile
+    phrase: save a decision profile
+    status: active
+    evidence: [DEV-PHRASE-PROFILE]
+  - id: RP_DESIGN_INTERFACE
+    capability: design
+    phrase: shape the interface
+    status: active
+    evidence: [DEV-PHRASE-DESIGN]
+  - id: RP_ORCHESTRATE_DELIVERY
+    capability: orchestrate
+    phrase: execute the approved plan
+    status: active
+    evidence: [DEV-PHRASE-ORCHESTRATE]

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

@@ -1,6 +1,6 @@
 # Changelog Artifact Schema
 #
-# Release history maintained by realisera. Tracks versioned releases with
+# Release history maintained by build. Tracks versioned releases with
 # categorized changes (Added, Changed, Fixed, Removed).
 #
 # Note: CHANGELOG.md is a human-facing Markdown artifact. It remains at the
@@ -11,12 +11,12 @@ meta:
   name: changelog
   version: "1.0.0"
   description: >-
-    Release history. Produced by realisera. Consumed by users and agents
+    Release history. Produced by build. Consumed by users and agents
     for version context. Human-facing: remains Markdown at project root.
   artifact_type: human_facing
   path: "CHANGELOG.md"
-  producer: realisera
-  consumers: [hej, all_skills]
+  producer: build
+  consumers: [status, all_skills]
   format: markdown
 
 GROUP_PREFIXES:
@@ -27,6 +27,7 @@ GROUP_PREFIXES:
 BUDGET:
   1:
     id: CB1
+    scope: full_file
     token_budget: 5000
     description: >-
       Maximum tokens for CHANGELOG.md content. Exceeding triggers compaction.

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

@@ -1,11 +1,12 @@
 # Decisions Artifact Schema
 #
-# Reasoning trail maintained by resonera. Each deliberation session appends
-# one entry. Decisions are referenced by realisera, optimera, and profilera
+# Reasoning trail maintained by discuss. Each deliberation session appends
+# 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 ──
 #
@@ -32,16 +33,28 @@ meta:
   name: decisions
   version: "1.0.0"
   description: >-
-    Reasoning trail maintained by resonera. Each deliberation session
-    appends one entry. Decisions are referenced by realisera, optimera,
-    profilera, planera, inspektera, hej, dokumentera, visionera, resonera,
-    and orkestrera for context on why choices were made.
+    Reasoning trail maintained by discuss. Each deliberation session
+    appends one entry. Decisions are referenced by build, optimize,
+    profile, plan, audit, status, document, vision, discuss,
+    and orchestrate for context on why choices were made.
   artifact_type: agent_facing
   path: ".agentera/decisions.yaml"
-  producer: resonera
-  consumers: [dokumentera, hej, inspektera, optimera, orkestrera, planera, profilera, realisera, resonera, visionera]
+  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
@@ -55,7 +68,7 @@ BUDGET:
   1:
     id: DB1
     scope: per_decision_entry
-    max_words: 200
+    max_words: 1000
     description: >-
       Maximum words per decision entry. Budgets are guidelines, not hard
       blockers.
@@ -69,10 +82,10 @@ BUDGET:
 COMPACTION:
   1:
     id: DX1
-    rule: uniform_10_40_50
+    rule: lossless_projection
     description: >-
-      Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
-      entries, 40 one-line archive entries, drop beyond 50 total.
+      The 10/40/50 values are current projection defaults, not deletion limits.
+      Numbered archive records remain complete and unlimited.
   2:
     id: DX2
     full_detail:
@@ -93,21 +106,26 @@ COMPACTION:
       the archive section. Compact summaries preserve decision number, date,
       and chosen alternative; structured compact fields preserve outcome and
       explicit feeds_into references when present so CLI downstream references
-      remain non-inferential.
+      remain non-inferential. Entries beyond the summary default are represented
+      by omission metadata while their numbered archive records remain available.
   4:
     id: DX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Decisions older than 50 are dropped entirely.
+      Omitted projection detail is never silently deleted or truncated. The
+      numbered archive is the complete historical source and retrieval points
+      use the direct state get contract.
   5:
     id: DX5
-    trigger: "When resonera writes a new decision"
+    trigger: "When discuss writes a new decision"
     description: >-
       Compaction runs when the producing skill writes a new entry.
-      If >10 full-detail entries exist, collapse the oldest to one-line.
-      If >40 one-line entries exist, drop the oldest.
+      If >10 full-detail entries exist and their numbered archives verify,
+      collapse the oldest to one-line. If >40 summary entries exist, omit the
+      oldest from this bounded projection with metadata; never delete its
+      numbered archive record. Unresolved review entries do not block storage.
   6:
     id: DX6
     archive_section:

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

@@ -1,6 +1,6 @@
 # Design Artifact Schema
 #
-# Visual identity system maintained by visualisera. Defines design tokens,
+# Visual identity system maintained by design. Defines design tokens,
 # palette, typography, spacing, and component styling rules.
 #
 # Note: DESIGN.md is a human-facing Markdown artifact. It remains at the
@@ -11,12 +11,12 @@ meta:
   name: design
   version: "1.0.0"
   description: >-
-    Visual identity system. Produced by visualisera. Consumed by capabilities
+    Visual identity system. Produced by design. Consumed by capabilities
     that need visual identity context. Human-facing: remains Markdown at root.
   artifact_type: human_facing
   path: "DESIGN.md"
-  producer: visualisera
-  consumers: [dokumentera, hej, inspektera, realisera, visionera, visualisera]
+  producer: design
+  consumers: [document, status, audit, build, vision, design]
   format: markdown
 
 GROUP_PREFIXES:
@@ -27,6 +27,7 @@ GROUP_PREFIXES:
 BUDGET:
   1:
     id: DB1
+    scope: full_file
     token_budget: 2000
     description: >-
       Maximum tokens for DESIGN.md content. Exceeding triggers compaction.

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

@@ -1,8 +1,11 @@
 # Docs Artifact Schema
 #
-# Documentation contract maintained by dokumentera. Tracks project doc
+# 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.
@@ -47,11 +50,11 @@ meta:
   name: docs
   version: "1.0.0"
   description: >-
-    Documentation contract. Produced by dokumentera. Consumed by all skills
+    Documentation contract. Produced by document. Consumed by all skills
     for artifact path resolution and doc status tracking.
   artifact_type: agent_facing
   path: ".agentera/docs.yaml"
-  producer: dokumentera
+  producer: document
   consumers: [all_skills]
   format: yaml
 
@@ -70,10 +73,10 @@ BUDGET:
   1:
     id: DB1
     scope: full_file
-    max_words: 2000
+    max_words: null
     description: >-
-      Maximum words for the full file. If a write would exceed this
-      budget, compact older audit log entries.
+      No full-file word budget. Historical audit_log entries are immutable;
+      keep the active inventory and coverage sections concise.
 
 HEADER:
   1:
@@ -123,7 +126,7 @@ CONVENTIONS:
     required: true
     description: >-
       Files whose content changes indicate a version bump is needed.
-      Tracked by planera, inspektera, and realisera for bump discipline.
+      Tracked by plan, audit, and build for bump discipline.
     validation:
       - "At least one entry required"
   5:
@@ -177,8 +180,9 @@ MAPPING:
     required: true
     description: >-
       File path for this artifact. May be absolute or relative.
-      Environment variable references (e.g., $PROFILERA_PROFILE_DIR)
-      are resolved at read time.
+      Environment variable references (e.g., $AGENTERA_PROFILE_DIR or
+      the deprecated $PROFILERA_PROFILE_DIR alias) are resolved at read
+      time with AGENTERA_PROFILE_DIR taking precedence.
     validation:
       - "Non-empty string"
   4:
@@ -288,7 +292,7 @@ AUDIT_LOG:
     type: map
     required: false
     description: >-
-      Each audit log entry. Timestamped findings from dokumentera audits.
+      Each audit log entry. Timestamped findings from document audits.
       Appended when an audit is performed.
   2:
     id: DA2
@@ -392,11 +396,3 @@ VALIDATION:
       Index status values should be from the allowed set.
     checks:
       - "Each status is one of: current, stale, missing, intent, generated"
-  4:
-    id: DVL4
-    rule: word_budget
-    severity: advisory
-    description: >-
-      Advisory check. Full file should be <=2000 words.
-    checks:
-      - "Total file word count <= 2000"

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

@@ -1,8 +1,8 @@
 # Experiments Artifact Schema
 #
-# Experiment log maintained by optimera. Each experiment records hypothesis,
+# Experiment log maintained by optimize. Each experiment records hypothesis,
 # method, metric results, kept/discarded status, and conclusions. Lives
-# alongside OBJECTIVE.md in .agentera/optimera/<name>/.
+# alongside OBJECTIVE.md in .agentera/optimize/<name>/.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
 # following capability_schema_contract.yaml and protocol.yaml conventions.
@@ -40,12 +40,12 @@ meta:
   name: experiments
   version: "1.0.0"
   description: >-
-    Experiment log for optimera objectives. Produced and consumed by optimera.
-    Lives in .agentera/optimera/<name>/ alongside the objective.
+    Experiment log for optimize objectives. Produced and consumed by optimize.
+    Lives in .agentera/optimize/<name>/ alongside the objective.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/experiments.yaml"
-  producer: optimera
-  consumers: [hej, optimera]
+  path: ".agentera/optimize/<name>/experiments.yaml"
+  producer: optimize
+  consumers: [status, optimize]
   format: yaml
 
 GROUP_PREFIXES:
@@ -54,6 +54,8 @@ GROUP_PREFIXES:
   EXPERIMENT: EX
   CLOSURE: EC
   ARCHIVE: EA
+  PUBLICATION: EP
+  RETRIEVAL: ER
   VALIDATION: EV
 
 BUDGET:
@@ -108,7 +110,7 @@ COMPACTION:
       Experiments older than 50 are dropped entirely.
   5:
     id: EX_CMP5
-    trigger: "When optimera writes a new experiment"
+    trigger: "When optimize writes a new experiment"
     description: >-
       Compaction runs when the producing skill writes a new entry.
       If >10 full-detail entries exist, collapse the oldest to one-line.
@@ -133,6 +135,7 @@ EXPERIMENT:
     validation:
       - "Must be a non-negative integer"
       - "Must be unique across active and archived entries"
+      - "Identity is <objective-id>/experiment:<number>"
   2:
     id: EX2
     field: date
@@ -267,6 +270,94 @@ EXPERIMENT:
       Harness refinement log for baseline experiments. Each entry
       records a run number, issue encountered, and fix applied.
 
+PUBLICATION:
+  1:
+    id: EP1
+    operation: publish
+    command: >-
+      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, and canonical entity state before
+      atomically publishing one experiment entity.
+  2:
+    id: EP2
+    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: >-
+      Retry never duplicates an experiment. Invalid identity, collisions, and
+      pre-publication failures preserve active and archive projection bytes.
+  3:
+    id: EP3
+    projection: bounded_entity_list
+    durable_archive: not_applicable
+    description: >-
+      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]
+    envelope_schema: agentera.experimentArchive.v1
+    required_fields:
+      - schemaVersion
+      - stable_id
+      - objective_id
+      - experiment_number
+      - record
+      - record_sha256
+      - provenance
+    provenance_fields: [authority, objective_id, experiment_id, storage_scope, publication_order]
+    retry: byte_equivalent_envelope_is_idempotent
+    collision: same_identity_with_different_bytes_fails
+    description: >-
+      Archive identity binds stable objective and experiment identity to the
+      immutable full record. Legacy projection entries remain readable without
+      fabricating archive history that predates this publication contract.
+  5:
+    id: EP5
+    directory_durability: fsync_each_new_child_parent_before_advancing
+    exact_full_replay: reconstruct_missing_archive_before_success
+    summary_only_replay: never_reconstruct_without_full_detail
+    description: >-
+      First publication durably records every new archive directory entry.
+      Replay may recover only the exact full record still present in the
+      projection; compacted summaries and dropped rows are not fabricated.
+
+RETRIEVAL:
+  1:
+    id: ER1
+    list: >-
+      agentera state experiments list --objective ID [--limit N]
+      [--cursor TOKEN] --format json
+    get: >-
+      agentera state experiments get --id ID --format json
+    description: >-
+      List returns newest-first objective-scoped canonical entities. Get returns
+      one exact entity by bare ID.
+  2:
+    id: ER2
+    cursor: opaque_snapshot_cursor
+    cursor_binding: [collection, objective, order, snapshot]
+    detail_availability: [full, summary, unavailable]
+    description: >-
+      Cursor tokens are copied, never parsed or constructed. List and get retain
+      compatibility and provenance when legacy detail is summary-only or absent.
+  3:
+    id: ER3
+    maximum_limit: 100
+    max_serialized_utf8_bytes: 32768
+    omission_fields: [omitted, omitted_count, omission_reason, retrieval]
+    description: >-
+      Structured pages omit whole entries rather than truncating scalar values;
+      every addressable omission has continuation or exact-get recovery.
+
 CLOSURE:
   1:
     id: EC1
@@ -317,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"
@@ -371,3 +462,43 @@ VALIDATION:
       and serve as the reference measurement.
     checks:
       - "Experiment 0 has status 'baseline'"
+  6:
+    id: EV6
+    rule: identity_compatibility
+    severity: error
+    description: >-
+      Experiment identity is objective-scoped. Reads retain legacy entries with
+      missing or duplicate numbers as unaddressable data with explicit caveats;
+      a new publication must reject ambiguous objective or experiment identity
+      before changing objective, experiment, or archive bytes.
+    checks:
+      - "Objective identity is stable across title and directory rename"
+      - "Experiment 0 and later non-negative numbers are addressable"
+      - "Duplicate or missing experiment numbers remain visible but unaddressable"
+      - "Publication rejects ambiguity before effects"
+  7:
+    id: EV7
+    rule: validated_publication
+    severity: error
+    description: >-
+      New experiments are published only through the typed writer after pure
+      identity and schema preflight, with atomic replacement and idempotent retry.
+    checks:
+      - "Caller input omits the CLI-owned number field"
+      - "Objective and experiment identity validate before staging"
+      - "Final experiments.yaml bytes validate before atomic replacement"
+      - "A byte-equivalent retry returns the existing experiment without duplication"
+  8:
+    id: EV8
+    rule: durable_archive_before_projection
+    severity: error
+    description: >-
+      Newly published full detail must be validated, immutably archived, and
+      directory-synced before the compacted projection is replaced.
+    checks:
+      - "Archive envelope identity and provenance validate before publication"
+      - "Every newly created archive directory entry is parent-synced in order"
+      - "Archive publication succeeds before projection replacement"
+      - "Exact full replay reconstructs a missing archive before success"
+      - "Conflicting immutable archive bytes preserve archive and projection"
+      - "Retry after archive or projection interruption does not duplicate detail"