agentera 3.0.0-dev.5 → 3.0.0-dev.51

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: >-
+      npx -y agentera@next 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: >-
+      npx -y agentera@next state experiments list --objective ID [--limit N]
+      [--cursor TOKEN] --format json
+    get: >-
+      npx -y agentera@next 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"

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

@@ -0,0 +1,82 @@
+# Project Glossary Artifact Schema
+
+meta:
+  name: glossary
+  version: "1.0.0"
+  description: >-
+    Repository-scoped canonical terminology governed by the shared glossary
+    entry and project publication contracts. Build atomically publishes an
+    explicitly confirmed audit proposal; audit and discuss remain read-only.
+  artifact_type: agent_facing
+  path: ".agentera/glossary.yaml"
+  producer: build
+  consumers: [build]
+  format: yaml
+  implementation_status: active
+
+CONFORMANCE:
+  authority: references/artifacts/glossary-entry-contract.yaml
+  ownership_contract: project
+  provenance_variant: project_file
+  term_identity_runtime: packages/cli/src/registries/glossaryTermIdentity.ts#unicodeCaselessExact
+  term_occurrence_runtime: packages/cli/src/registries/glossaryTermOccurrence.ts#containsGlossaryTerm
+
+DOCUMENT:
+  schema_version: agentera.projectGlossary.v1
+  required_fields: [schema_version, approvals, entries]
+  additional_fields: forbidden
+  approvals:
+    type: list
+    immutable: true
+    record_fields: [proposal_digest, proposal, confirmation]
+    additional_record_fields: forbidden
+  entries:
+    type: list
+    item: shared_primitive
+    approval_fields: forbidden
+  terminology_set_identity:
+    normalization: unicode_caseless_exact_no_normalization
+    members: [paired_entry.term, paired_approval.proposal.variants.term]
+    uniqueness: global_across_complete_document
+
+PUBLICATION:
+  implementation: active
+  owner: build
+  command: npx -y agentera@next state glossary publish --input REQUEST --format json
+  request_schema_version: agentera.glossaryPublicationRequest.v1
+  atomic_unit: complete_document
+  lock: established_project_writer_lock
+  exact_replay: no_op
+  term_identity: unicode_caseless_exact_no_normalization_global_canonical_and_variant_set
+  source_revalidation: safe_real_path_line_identity_and_sha256
+  docs_mapping_mutation: forbidden
+  excluded_behavior: [consumer_lookup, consumer_precedence, consumer_semantic_review, personal_profile_mutation]
+
+CONSUMER_ACQUISITION:
+  implementation: active
+  authority: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.acquisition
+  runtime: packages/cli/src/analytics/glossaryInputAcquisition.ts#acquireGlossaryInputs
+  availability: [absent, valid_empty, valid_present, malformed, unreadable, ambiguous, over_bound]
+  output_entry_fields: [term, meaning, owner]
+  source_output_fields: [owner, availability, entries, gap_proving, diagnostic]
+  raw_byte_bound: 65536
+  entry_bound: 100
+  utf8_decoding: fatal
+  project_read: descriptor_bound_no_follow_with_parent_identity_checks
+  mutation: forbidden
+  consumer_semantics: [project_precedence, proven_gap_personal_fallback, divergent_tension, host_review]
+
+ADVICE_RESOLUTION:
+  implementation: active
+  authority: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.advice_resolution
+  runtime: packages/cli/src/analytics/glossaryAdviceResolution.ts#resolveGlossaryAdvice
+  input: [requested_term, acquired, host_review]
+  output_schema_version: agentera.glossaryAdvice.v1
+  mutation: forbidden
+  capability_integrations: [discuss, plan, build, prime]
+
+CONFIRMED_VARIANT_GUARD:
+  authority: references/artifacts/glossary-entry-contract.yaml#ownership_contracts.project.confirmed_variant_guard
+  implementation: active
+  validation_surface: packages/cli/test/cli/v1LegacyCruft.test.ts
+  consumer_lookup: forbidden

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

@@ -1,12 +1,14 @@
 # Health Artifact Schema
 #
-# Audit log maintained by inspektera. Each audit entry records assessed
-# dimensions, findings (critical/warning/info counts), overall trajectory,
-# per-dimension grades (A-F), per-dimension findings with confidence, and
-# trend analysis against the prior audit.
+# Audit normally owns health records. Orchestrate may append only the limited
+# artifact_freshness record for terminal-plan closure after Audit passes. Each
+# audit entry records assessed dimensions, findings (critical/warning/info
+# counts), overall trajectory, 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 ──
 #
@@ -14,6 +16,7 @@
 # ─────────────────────────────────────────────────────────────────────
 # ## Audit N · date                     AUDIT.number           HA1
 # (date from heading)                   AUDIT.date             HA2
+# (CLI append time)                     AUDIT.appended_at      HA7
 # **Dimensions assessed**: <list>       AUDIT.dimensions       HA3
 # **Findings**: N crit, N warn, N info  AUDIT.findings_summary HA4
 # **Overall trajectory**: <text>        AUDIT.trajectory       HA5
@@ -49,14 +52,27 @@ meta:
   name: health
   version: "1.0.0"
   description: >-
-    Audit log maintained by inspektera. Consumed by capabilities that need
-    codebase health context.
+    Audit normally owns health records. Orchestrate may append only the
+    limited artifact_freshness record for terminal-plan closure after Audit
+    passes. Consumed by capabilities that need codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
-  producer: inspektera
-  consumers: [dokumentera, hej, inspektera, orkestrera, planera, realisera, visionera]
+  authority: legacy_migration_input_only
+  producer: [audit, orchestrate]
+  consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: health
+  boundary: health_audit
+  retrieval:
+    list: npx -y agentera@next state health list --format json
+    get: npx -y agentera@next state health get --id ID --format json
+  mutation: npx -y agentera@next state health explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: HB
   COMPACTION: HX
@@ -87,10 +103,10 @@ BUDGET:
 COMPACTION:
   1:
     id: HX1
-    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: HX2
     full_detail:
@@ -109,21 +125,27 @@ COMPACTION:
     description: >-
       Audits 11 through 50 are collapsed to one-line format under the
       archive section. One-line summaries preserve audit number, date,
-      overall grade, and trajectory.
+      overall grade, and trajectory. Entries beyond the summary default are
+      represented by omission metadata while their numbered archive records
+      remain available.
   4:
     id: HX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Audits 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: HX5
-    trigger: "When inspektera writes a new audit"
+    trigger: "When audit writes a new audit"
     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. Unverified entries remain full for recovery.
   6:
     id: HX6
     archive_section:
@@ -219,6 +241,21 @@ AUDIT:
     validation:
       - "Every assessed dimension has a grade"
       - "Grades are single characters A through F"
+  7:
+    id: HA7
+    field: appended_at
+    type: string
+    format: "YYYY-MM-DDTHH:mm:ss.sssZ"
+    required: false
+    cli_owned: true
+    description: >-
+      Canonical UTC timestamp assigned by the health append writer. Full records
+      with this field sort newest-first by append time, then stable ID. Legacy
+      records without it retain date-then-ID ordering; migration never fabricates
+      append chronology.
+    validation:
+      - "When present, must be canonical UTC ISO-8601 with millisecond precision"
+      - "Must be omitted from caller input and assigned by the CLI writer"
 
 DIMENSION:
   1:

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

@@ -1,7 +1,7 @@
 # Objective Artifact Schema
 #
-# Optimization objective maintained by optimera. Each objective lives in its
-# own subdirectory under .agentera/optimera/<name>/ and captures the metric,
+# Optimization objective maintained by optimize. Each objective lives in its
+# own subdirectory under .agentera/optimize/<name>/ and captures the metric,
 # target, baseline, constraints, measurement method, gates, and scope.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
@@ -47,12 +47,12 @@ meta:
   name: objective
   version: "1.0.0"
   description: >-
-    Optimization objective. Produced by optimera and resonera. Each objective
-    lives in its own subdirectory under .agentera/optimera/<name>/.
+    Optimization objective. Produced by optimize and discuss. Each objective
+    lives in its own subdirectory under .agentera/optimize/<name>/.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/objective.yaml"
-  producer: [optimera, resonera]
-  consumers: [hej, optimera, resonera]
+  path: ".agentera/optimize/<name>/objective.yaml"
+  producer: [optimize, discuss]
+  consumers: [status, optimize, discuss]
   format: yaml
 
 GROUP_PREFIXES:
@@ -78,6 +78,19 @@ BUDGET:
       bounded by the measurement description's inherent complexity.
 
 HEADER:
+  0:
+    id: OB_HDR0
+    field: id
+    type: string
+    required: true
+    description: >-
+      Stable objective identity in objective:<lowercase RFC 9562 UUID> form.
+      It is assigned when a new objective is published and remains unchanged
+      when the title or containing directory is renamed. Legacy objectives
+      without this field remain read-compatible through a derived identity and
+      an explicit compatibility caveat; reads never rewrite legacy bytes.
+    validation:
+      - "Matches objective:<lowercase-rfc9562-uuid>"
   1:
     id: OB_HDR1
     field: title
@@ -360,10 +373,11 @@ VALIDATION_RULES:
     rule: required_fields
     severity: error
     description: >-
-      The objective must have: title, status, description, why,
+      A newly published objective must have: stable id, title, status, description, why,
       measurement, metric (description, direction, unit), baseline,
       and scope (included, excluded).
     checks:
+      - "id is present and matches objective:<lowercase-rfc9562-uuid>"
       - "title is present and non-empty"
       - "status is present and is 'open' or 'closed'"
       - "description is present and non-empty"