agentera 3.0.0-dev.7 → 3.0.0-dev.72

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

@@ -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

@@ -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: npx -y agentera@next state decisions list --format json
+    get: npx -y agentera@next state decisions get --id ID --format json
+  mutation: npx -y agentera@next state decisions explain --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: DB
   COMPACTION: DX
@@ -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 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

@@ -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

@@ -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.
@@ -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:
@@ -393,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

@@ -2,7 +2,7 @@
 #
 # 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.
@@ -41,9 +41,9 @@ meta:
   version: "1.0.0"
   description: >-
     Experiment log for optimize objectives. Produced and consumed by optimize.
-    Lives in .agentera/optimera/<name>/ alongside the objective.
+    Lives in .agentera/optimize/<name>/ alongside the objective.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/experiments.yaml"
+  path: ".agentera/optimize/<name>/experiments.yaml"
   producer: optimize
   consumers: [status, optimize]
   format: yaml
@@ -54,6 +54,8 @@ GROUP_PREFIXES:
   EXPERIMENT: EX
   CLOSURE: EC
   ARCHIVE: EA
+  PUBLICATION: EP
+  RETRIEVAL: ER
   VALIDATION: EV
 
 BUDGET:
@@ -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 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.
+# 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 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 +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 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: