agentera 3.0.0-dev.8 → 3.0.0-dev.81

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

@@ -0,0 +1,87 @@
+# 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
+  personal_mining_authority: references/artifacts/glossary-entry-contract.yaml#personal_mining_authority
+  stable_term_identity_runtime: packages/cli/src/registries/glossaryTermIdentity.ts#stableGlossaryTermIdentity
+  candidate_revision_runtime: packages/cli/src/registries/glossaryTermIdentity.ts#glossaryCandidateRevision
+  candidate_contracts_authority: references/artifacts/glossary-entry-contract.yaml#candidate_contracts
+  candidate_contracts_runtime: packages/cli/src/registries/glossaryCandidateContracts.ts#validatePersonalCandidateContracts
+  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/glossaryVariantGuard.test.ts
+  consumer_lookup: forbidden

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

@@ -1,44 +1,12 @@
 # Health Artifact Schema
 #
-# Audit log maintained by audit. 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.
-#
-# ── Field-by-field mapping: v1 HEALTH.md → v2 health.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# ## Audit N · date                     AUDIT.number           HA1
-# (date from heading)                   AUDIT.date             HA2
-# **Dimensions assessed**: <list>       AUDIT.dimensions       HA3
-# **Findings**: N crit, N warn, N info  AUDIT.findings_summary HA4
-# **Overall trajectory**: <text>        AUDIT.trajectory       HA5
-# **Grades**: Dim [X] | Dim [Y]        AUDIT.grades           HA6
-# ### Dimension: grade                  DIMENSION.name         HD1
-# (grade from heading)                  DIMENSION.grade        HD2
-# #### finding text                     FINDING.heading        HF1
-# - **Location**: <text>               FINDING.location       HF2
-# - **Evidence**: <text>               FINDING.evidence       HF3
-# - **Impact**: <text>                 FINDING.impact         HF4
-# - **Suggested action**: <text>       FINDING.suggested_action HF5
-# (severity glyph from prefix)         FINDING.severity       HF6
-# (confidence from parenthetical)      FINDING.confidence     HF7
-# ### Trends vs Audit N                 TRENDS.entry           HT1
-# - **Improved**: <text>               TRENDS.improved        HT2
-# - **Degraded**: <text>               TRENDS.degraded        HT3
-# - **Stable**: <text>                 TRENDS.stable          HT4
-# - **New findings**: <text>           TRENDS.new_findings    HT5
-# - **Resolved**: <text>              TRENDS.resolved         HT6
-# - **Carried forward**: <text>       TRENDS.carried_forward  HT7
-# ### Patterns Observed                 PATTERNS.heading       HP1
-# - Pattern text                       PATTERNS.entry         HP2
-# ## Archived Audits                    (implicit section)     —
-# ### Audit N · date (summary)         ARCHIVE.summary        HR1
+# 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.
 #
+# The active authority is one health_audit entity per writer-owned file.
 # Protocol references:
 #   severity: SF1-SF3 (protocol.yaml SEVERITY_FINDING)
 #   confidence: CS1-CS5 (protocol.yaml CONFIDENCE_SCALE)
@@ -49,14 +17,27 @@ meta:
   name: health
   version: "1.0.0"
   description: >-
-    Audit log maintained by audit. 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: audit
+  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 +68,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 +90,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 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 +206,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,43 +1,12 @@
 # Objective Artifact Schema
 #
 # Optimization objective maintained by optimize. Each objective lives in its
-# own subdirectory under .agentera/optimera/<name>/ and captures the metric,
+# 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,
 # following capability_schema_contract.yaml and protocol.yaml conventions.
 #
-# ── Field-by-field mapping: v1 OBJECTIVE.md → v2 objective.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# # <title>                              HEADER.title           OB1
-# **Status**: <status>                   HEADER.status          OB2
-# **Closed at**: <timestamp>             HEADER.closed_at       OB3
-# **Final value**: <value>               HEADER.final_value     OB4
-# **Target**: <target>                   HEADER.target_ref      OB5
-# **Reason**: <text>                     HEADER.reason          OB6
-# ## Objective / description             OBJECTIVE.description  OJ1
-# ### Two-tier metric (or single)        OBJECTIVE.metric_type  OJ2
-# **Tier 1 (primary metric)**: <text>    METRIC.description     OM1
-# Direction/Unit/Variance                METRIC.direction       OM2
-# METRIC.unit                            OM3
-# METRIC.variance                        OM4
-# **Tier 2 (behavioral)**: <text>        VALIDATION.description OV1
-# **Keep gate**: <text>                  VALIDATION.keep_gate   OV2
-# **Discard gate**: <text>               VALIDATION.discard_gate OV3
-# ### Why two tiers                      OBJECTIVE.rationale    OJ3
-# ## Why this matters                    OBJECTIVE.why          OJ4
-# ## Measurement                         OBJECTIVE.measurement  OJ5
-# ## Gates                               GATES.description      OG1
-# **Causal**: <text>                     GATES.causal           OG2
-# **Structural**: <text>                 GATES.structural       OG3
-# **Regression**: <text>                 GATES.regression       OG4
-# ## Constraints                         OBJECTIVE.constraints  OJ6
-# ## Scope / In scope                    SCOPE.included         OS1
-# ## Scope / Out of scope                SCOPE.excluded         OS2
-# ## Baseline                            BASELINE.description   OB7
-# ## Measurement model                   BASELINE.model_notes   OB8
 #
 # Protocol references:
 #   exit signals: EX1-EX4 (protocol.yaml EXIT_SIGNALS)
@@ -48,9 +17,9 @@ meta:
   version: "1.0.0"
   description: >-
     Optimization objective. Produced by optimize and discuss. Each objective
-    lives in its own subdirectory under .agentera/optimera/<name>/.
+    lives in its own subdirectory under .agentera/optimize/<name>/.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/objective.yaml"
+  path: ".agentera/optimize/<name>/objective.yaml"
   producer: [optimize, discuss]
   consumers: [status, optimize, discuss]
   format: yaml
@@ -78,6 +47,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 +342,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"