agentera 3.0.0-dev.32 → 3.0.0-dev.38

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -176,14 +176,42 @@ entity_target:
         forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
         temporal_fields: [timestamp]
         timestamp_format: 'YYYY-MM-DD HH:MM'
+        publication_order:
+          field: publication_order
+          type: positive_safe_integer
+          presence: optional_for_legacy_required_for_new_publications
+          visibility: public_record_metadata
+          ownership: progress_writer_only
+          assignment: max_valid_existing_progress_publication_order_plus_one
+          synchronization: .agentera/.writer.lock
+          dry_run: omitted_without_consuming_or_mutating_order
+          caller_input: forbidden
+          malformed_or_spoofed_input: reject_before_mutation_with_bounded_diagnostics
+          durability: persisted_in_each_new_progress_cycle_entity
+          privacy: bounded_ordinal_without_time_identity_or_content
       retrieval:
         exact: agentera state progress get --id ID --format json
         list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
-        ordering: timestamp_desc_then_id_asc
+        ordering: timestamp_desc_then_publication_order_desc_then_id_asc
+        semantic_recency: >-
+          The first full progress cycle is latest. Timestamp remains the public
+          minute-compatible primary key. Within one timestamp, a valid writer-owned
+          publication_order sorts descending; a marked publication sorts after all
+          unmarked legacy records observed by that publication and therefore before
+          them in newest-first retrieval. Missing markers are legacy unordered ties.
+          Equal valid markers can result from independently published histories and
+          do not establish relative publication order. Missing or equal markers use
+          opaque ID ascending only as a deterministic final fallback and never claim
+          reconstructed publication chronology.
         default_limit: 20
         maximum_limit: 100
         max_utf8_bytes: 32768
-        cursor: opaque_snapshot_cursor
+        cursor: opaque_snapshot_cursor_v2
+        cursor_compatibility: >-
+          Version 2 continuation keys include timestamp, publication_order presence
+          and value, and opaque ID. Version 1 progress cursors are rejected with
+          recovery to omit --cursor and establish a new snapshot; authority changes
+          also invalidate prior cursor signatures by design.
         mutation_after_snapshot: cursor_snapshot_unavailable
         omission: whole_entries_only_with_count_reason_continuation_and_exact_get
         scalar_truncation: forbidden
@@ -647,7 +675,7 @@ entity_target:
           detail_availability: summary
           compatibility: degraded
           caveats: required
-          ordering: full_timestamp_desc_then_id_asc_then_summary_id_asc
+          ordering: full_timestamp_desc_then_publication_order_desc_then_id_asc_then_summary_id_asc
           summary_ordering: canonical_id_asc_without_chronology_claim
           mutation: read_only
       - boundary: decision_summary

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -160,12 +160,23 @@ audience_namespaces:
           [--project-root PATH] [--format text|json]
         delegates_from: stats refresh
         behavior: Matches today's `agentera stats refresh` including consent gates.
+      profile_glossary:
+        canonical_shape: >-
+          agentera report profile-glossary --input <file|-> [--dry-run]
+          --format json
+        delegates_from: null
+        behavior: >-
+          Applies one versioned personal glossary update request to the exact
+          PROFILE.md path supplied by Profile Full. Runs headlessly without a
+          project checkout; never discovers or reads project state or a project
+          glossary. Dry-run validates and computes the candidate without a write.
     legacy_top_level_alias: stats
     rejected_top_level: corpus
     notes: >-
       `agentera usage` and `agentera usage` remain backward-compatible
       maintainer seams per AGENTS.md until separately classified; public user-facing
-      analytics consolidate under `report`.
+      analytics and Profile's bounded personal-output implementation consolidate
+      under `report`.
   check:
     audience: [maintainer]
     status: target_canonical_namespace

package/bundle/references/cli/prime-consumer-compatibility.yaml

@@ -235,7 +235,13 @@ field_classification:
       recommendation is active.
   - field: attention
     status: required
-    rationale: Bounded; opencode and status dashboard consume it.
+    rationale: >-
+      Bounded; opencode and status dashboard consume it. Valid current glossary
+      caveats add at most one generic review item through the glossary authority's
+      declared prime projection. When current, its one reserved final slot leaves
+      the first five unrelated items in their existing order under the six-item
+      public cap; lifecycle identity and private semantics remain internal, and
+      next_action is unchanged.
   - field: history
     status: diagnostic
     rationale: >-

package/bundle/skills/agentera/capabilities/audit/schemas/validation.yaml

@@ -66,13 +66,13 @@ VALIDATION:
     id: V7
     rule: evidence_context_first
     description: >-
-       Audit evaluation startup MUST begin with `agentera prime --context
-       audit --format json` and use complete CLI `evidence_context` before
-       bounded state list/get contracts for plan, progress, docs, health, TODO,
-       or decisions. Raw artifact access is diagnostic-only.
+      Audit evaluation startup MUST begin with `agentera prime --context
+      audit --format json` and use complete CLI `evidence_context` before
+      bounded state list/get contracts for plan, progress, docs, health, TODO,
+      or decisions. Raw artifact access is diagnostic-only.
     severity: critical
     checks:
-       - "Evidence context is requested through prime --context before bounded state list/get"
+      - "Evidence context is requested through prime --context before bounded state list/get"
   8:
     id: V8
     rule: evidence_context_fallback_before_raw
@@ -82,9 +82,9 @@ VALIDATION:
        diagnostic-only raw artifact read.
     severity: critical
     checks:
-       - "evidence_context.fallback_commands are attempted before diagnostic-only raw reads"
-       - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
-       - "Raw artifact reads are diagnostic-only, not normal evaluation startup"
+      - "evidence_context.fallback_commands are attempted before diagnostic-only raw reads"
+      - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
+      - "Raw artifact reads are diagnostic-only, not normal evaluation startup"
   9:
     id: V9
     rule: evidence_context_caveats_preserved
@@ -112,3 +112,21 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  11:
+    id: V11
+    rule: terminology_drift_read_only
+    description: >-
+      Terminology-drift findings MUST cite every variant with verified
+      project-relative file and line evidence. Canonical terms are proposals,
+      never decisions or writes. Optional personal-profile divergence is
+      comparison evidence only; missing profile evidence produces no claim.
+      Audit remains mutation-free and read-only. Build project-glossary
+      publication is active. Audit performs no consumer lookup; Discuss, Plan,
+      and Build use the separate active read-only advice path. Personal-profile
+      mutation and docs-mapping mutation remain outside both paths.
+    severity: critical
+    checks:
+      - "Every reported drift variant has project-file evidence"
+      - "Weak, deliberate, tracked, and no-drift candidates produce no finding"
+      - "Audit mutates no glossary, profile, docs mapping, code, or project file"
+      - "Build publication and read-only glossary consumers are active under separate mutation boundaries"

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

@@ -28,7 +28,8 @@ ARTIFACTS:
     artifact: progress
     local_role: produces_and_consumes
     description: >-
-      Operational cycle log. Build consumes latest progress evidence from
+      Operational cycle log and the sole durable channel for bounded autonomous
+      glossary caveat lifecycle evidence. Build consumes latest progress evidence from
       execution_context first, then bounded `agentera state progress list --limit
        20 --format json` discovery or exact `state progress get --id ID`
       retrieval, and appends one entry per cycle with mandatory Verified field.
@@ -65,9 +66,10 @@ ARTIFACTS:
     artifact: profile
     local_role: consumes
     description: >-
-      Build consumes status profile summary first. Missing or stale profile state
-      is a caveat and does not authorize profile refresh or direct profile reads
-      during normal startup.
+      Build consumes status profile summary first and reads profile grounding
+      only from `agentera report profile-grounding --format json`. Missing,
+      stale, or malformed state is a caveat and does not authorize refresh or
+      direct profile reads during normal startup.
   9:
     id: A9
     artifact: docs
@@ -83,3 +85,18 @@ ARTIFACTS:
       Build treats design state missing from execution_context as a caveat or
       fallback-only need, and reads it only when building user-facing features
       after listed CLI fallbacks are exhausted.
+  11:
+    id: A11
+    artifact: glossary
+    local_role: produces_and_consumes
+    description: >-
+      Build alone publishes one explicitly user-confirmed terminology proposal
+      through `agentera state glossary publish --input REQUEST`. The typed writer
+      revalidates audit source evidence and atomically records the immutable
+      approval beside the shared-only project entry. Build does not consume the
+      glossary only to validate replay and preserve unrelated publication state.
+      Separately, at governed meaning-sensitive Build events it requests bounded
+      read-only advice through `agentera report glossary-advice --input REQUEST
+      --format json`. Advice and progress caveats never publish terminology,
+      approve a proposal, reuse confirmation, mutate personal profiles or docs
+      mappings, or grant publication authority to another capability.

package/bundle/skills/agentera/capabilities/build/schemas/validation.yaml

@@ -108,3 +108,53 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  11:
+    id: V11
+    rule: sanitized_profile_grounding
+    description: >-
+      Build MUST ground only from the `content` returned by `agentera report
+      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+    severity: critical
+    checks:
+      - "Sanitized grounding command used after prime startup"
+      - "Raw profile path not read"
+  12:
+    id: V12
+    rule: governed_glossary_advice
+    description: >-
+      At initial meaning-sensitive cycle intent and later user-authored changes
+      or clarification answers that can alter intent, Build MUST request bounded
+      advice through `agentera report glossary-advice --input REQUEST --format
+      json`. Unchanged replay, unrelated turns, rendering, and tool output MUST
+      NOT refresh advice.
+    severity: critical
+    checks:
+      - "Exact project authority or proven-gap personal fallback grounds intent"
+      - "Governed changes refresh only the affected meaning"
+      - "Incidental turns and unchanged replay do not refresh"
+  13:
+    id: V13
+    rule: glossary_review_and_autonomy
+    description: >-
+      Interactive Build MUST ask one focused clarification before disputed
+      meaning-sensitive reliance whenever review is required. If autonomous Build
+      cannot pause, it MUST avoid the disputed meaning, proceed conservatively
+      only where safe, and append one idempotent privacy-safe glossary_caveat
+      lifecycle envelope through the typed progress writer.
+    severity: critical
+    checks:
+      - "Clarification precedes meaning-sensitive execution and re-evaluates only the affected meaning"
+      - "Autonomous work does not assume disputed meaning"
+      - "Current, resolved, and superseded caveat events obey opaque identity lifecycle"
+  14:
+    id: V14
+    rule: glossary_publication_isolation
+    description: >-
+      Advice, tension, clarification, and progress caveat lifecycle MUST NOT call
+      `agentera state glossary publish`, create or reuse approval, substitute for
+      digest-bound user confirmation, satisfy decisions or plan state, or grant
+      Discuss or Audit publication authority.
+    severity: critical
+    checks:
+      - "Advice and caveat paths perform zero glossary publication writes"
+      - "Only separately supplied digest-confirmed publication retains Build authority"

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

@@ -39,8 +39,9 @@ ARTIFACTS:
     artifact: profile
     local_role: consumes
     description: >-
-      Discuss reads this at session start to acknowledge high-confidence
-      entries and avoid re-deliberating settled ground.
+      Discuss reads only sanitized non-glossary content from `agentera report
+      profile-grounding --format json` at session start. It never direct-reads
+      the profile path; malformed owned Glossary boundaries fail closed.
   6:
     id: A6
     artifact: docs

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

@@ -76,3 +76,67 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  8:
+    id: V8
+    rule: sanitized_profile_grounding
+    description: >-
+      Discuss MUST ground only from the `content` returned by `agentera report
+      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+    severity: critical
+    checks:
+      - "Sanitized grounding command used at session start"
+      - "Raw profile path not read"
+  9:
+    id: V9
+    rule: governed_glossary_advice_events
+    description: >-
+      Discuss MUST invoke `agentera report glossary-advice --input <file|->
+      --format json` for initial meaning-sensitive user input and later
+      user-authored premise changes or affected clarification answers that can
+      change meaning. It MUST NOT invoke advice for unchanged replay, rendering,
+      unrelated turns, tool output, background rereads, or Done-only control,
+      and MUST NOT use an unbounded or persistent transcript scan.
+    severity: critical
+    checks:
+      - "Initial and changed meaning-sensitive user events refresh advice"
+      - "Incidental, unchanged, and Done-only events do not refresh advice"
+      - "Only current user-authored meaning-sensitive input is inspected"
+  10:
+    id: V10
+    rule: glossary_review_before_reliance
+    description: >-
+      When advice requires inferred-equivalence review, Discuss MUST ask one
+      focused clarification with Done before meaning-sensitive reasoning or
+      decision framing relies on either meaning. It MUST NOT silently infer
+      equivalence, and the clarification MUST NOT count as decision confirmation.
+    severity: critical
+    checks:
+      - "Focused review question precedes reliance"
+      - "One-question-per-turn and Done behavior are preserved"
+      - "Clarification is not decision confirmation"
+  11:
+    id: V11
+    rule: glossary_authority_and_disclosure
+    description: >-
+      Discuss MUST use only the transient applicable meaning and owner. Project
+      meaning governs a divergent exact collision and the divergence appears as
+      a concise scratchpad tension or Crux; Discuss MUST NOT ask the user to
+      choose project versus personal authority or quote unrelated entries.
+    severity: critical
+    checks:
+      - "Applicable project or proven personal fallback meaning is used"
+      - "Divergence appears as tension or Crux without an authority-choice question"
+      - "Unrelated glossary content is not disclosed"
+  12:
+    id: V12
+    rule: glossary_consumer_mutation_isolation
+    description: >-
+      Advice, divergence, and consumer clarification are transient. Discuss MUST
+      NOT write glossary, approval, publication consent, progress caveat, plan
+      conflict, or decision conflict state, and MUST NOT call glossary publish.
+      Unavailable or no-applicable advice adds no glossary facts.
+    severity: critical
+    checks:
+      - "No glossary or consumer-caveat mutation occurs"
+      - "No approval, consent, or conflict bookkeeping occurs"
+      - "Unavailable advice does not fabricate glossary grounding"

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

@@ -53,7 +53,10 @@ ARTIFACTS:
     artifact: profile
     local_role: consumes
     description: >-
-      Plan reads this to calibrate planning depth and pattern preferences.
+      Plan reads only sanitized non-glossary content from `agentera report
+      profile-grounding --format json` to calibrate planning depth and pattern
+      preferences. It never direct-reads the profile path; malformed owned
+      Glossary boundaries fail closed.
   9:
     id: A9
     artifact: docs

package/bundle/skills/agentera/capabilities/plan/schemas/validation.yaml

@@ -87,3 +87,33 @@ VALIDATION:
     checks:
       - "Full plans with dismissed critic findings have `rejected:` entries"
       - "Each rejection has issue and rationale fields"
+  9:
+    id: V9
+    rule: sanitized_profile_grounding
+    description: >-
+      Plan MUST ground only from the `content` returned by `agentera report
+      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+    severity: critical
+    checks:
+      - "Sanitized grounding command used during Orient"
+      - "Raw profile path not read"
+  10:
+    id: V10
+    rule: governed_terminology_advice
+    description: >-
+      Plan MUST consume terminology advice through the shared glossary consumer
+      authority at governed meaning-sensitive user events. Interactive review
+      MUST precede fixing affected requirements. Autonomous unresolved review
+      MUST abstain, defer the affected requirements, and emit at most one bounded
+      current writer intent without delivering or storing it or writing plan
+      conflict or progress state.
+    severity: critical
+    checks:
+      - "Advice refreshes only for authority-declared Plan events"
+      - "Mode follows explicit authority precedence and unknown mode waits"
+      - "Interactive review precedes affected requirements and acceptance"
+      - "Autonomous unresolved meaning remains deferred without a Plan write"
+      - "Emitted-only handoff intent contains exactly event=current, reason, and ownership state"
+      - "Writer owns caveat identity, Build capability, and transition fields"
+      - "Exact project authority suppresses personal-unavailable durable handoff"
+      - "Plan artifacts exclude private glossary content"

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

@@ -5,8 +5,11 @@ ARTIFACTS:
     local_role: produces_and_consumes
     description: >-
       Decision profile with per-entry confidence scoring, permanence
-      classification, and temporal metadata. Profile writes this in both Full
-      and Validate modes, then reads it for validation and update context.
+      classification, and temporal metadata. Profile Full also owns one
+      deterministic personal Glossary section containing shared glossary entries
+      and lifecycle metadata; rendering and persistence are active while lookup
+      remains deferred. Profile writes this in both Full and Validate modes,
+      then reads it for validation and update context.
   2:
     id: A2
     artifact: decisions

package/bundle/skills/agentera/capabilities/profile/schemas/exit.yaml

@@ -4,8 +4,9 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       PROFILE.md was written (Full mode) or updated (Validate mode).
-      Metadata changes were applied, prediction accuracy was assessed
-      (Full mode), and changes were summarized.
+      In Full mode its owned personal Glossary section was rendered and persisted,
+      metadata changes were applied, prediction accuracy was assessed, and
+      changes were summarized.
     exit_signal: complete
   2:
     id: E2

package/bundle/skills/agentera/capabilities/profile/schemas/validation.yaml

@@ -83,3 +83,33 @@ VALIDATION:
       - "Signal tier state, count, and sufficiency are read before synthesizing"
       - "Underrepresented families are surfaced with retained and intended counts"
       - "No high-confidence claims are fabricated from sparse or missing evidence"
+  7:
+    id: V7
+    rule: personal_glossary_output
+    description: >-
+      Profile Full MUST render and persist exactly one owned Glossary section
+      through `agentera report profile-glossary`. Entries use only the shared
+      primitive and personal provenance variants. Replacement preserves every
+      non-glossary byte, malformed or ambiguous boundaries fail before effects,
+      and personal production never reads a project glossary.
+    severity: critical
+    checks:
+      - "Explicit entries retain exactly one evidence anchor"
+      - "Inferred entries retain exactly two pairwise-distinct evidence anchors"
+      - "Non-glossary PROFILE.md bytes and decision-pattern confidence are unchanged"
+      - "No project glossary identity, path, parameter, import, or read is used"
+  8:
+    id: V8
+    rule: personal_glossary_lifecycle
+    description: >-
+      Established entries MUST survive regeneration without fresh evidence.
+      Confidence is deterministically derived from the retained confidence basis,
+      unchanged permanence class, injected date, existing Profile decay formula,
+      and floor; permanence and observed_at remain unchanged. Matching fresh
+      evidence follows the shared authority refresh rule. Lookup remains deferred.
+    severity: critical
+    checks:
+      - "Same-date replay is idempotent and decay never compounds from rendered confidence"
+      - "Stable, durable, and situational classes use their existing lambdas and floor"
+      - "Fresh evidence refreshes only matching meaning and provenance kind"
+      - "Glossary confidence never mutates decision-pattern confidence"

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: agentera 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/plan.yaml

@@ -374,7 +374,11 @@ TASK:
     description: >-
       CLI-owned evaluator state written only by `agentera state plan
       record-evaluation`. It records attempt and failure counts, the latest
-       verdict, retained failure evidence, and stable attempt provenance.
+      verdict, retained failure evidence, and stable attempt provenance. Normal
+      workflow records evaluation before completion. As recovery for persisted
+      out-of-order replacement state only, the writer accepts the first PASS on
+      an unevaluated complete task while its open same-plan superseded predecessor
+      names it in superseded_by; every other terminal evaluation remains rejected.
   7:
     id: PT21
     field: superseded_by

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

@@ -4,6 +4,11 @@
 # in one development cycle: phase, work done, discoveries, verification,
 # next steps, and context envelope.
 #
+# The optional glossary_caveat envelope, Build writer, and bounded prime reader
+# are active. Build remains the sole progress producer; Plan may only emit the
+# bounded current writer intent for Build and never delivers or persists it in
+# plan state. Prime projects generic review attention without lifecycle details.
+#
 # The active authority is one progress_cycle 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.
@@ -56,12 +61,27 @@ ENTITY_AUTHORITY:
   mutation: agentera state progress explain --verb append --format json
   direct_file_edits: forbidden
   legacy_schema_below: migration_input_only
+  semantic_recency:
+    primary: timestamp_desc
+    same_minute: publication_order_desc
+    final_fallback: opaque_id_asc_for_missing_or_duplicate_publication_order
+    latest: first_full_progress_cycle_in_canonical_list_order
+  publication_order:
+    type: positive_safe_integer
+    presence: optional_for_legacy_required_for_new_publications
+    visibility: public_record_metadata
+    owner: progress_writer
+    assignment: max_valid_existing_plus_one_under_publication_lock
+    caller_input: forbidden
+    dry_run: omitted
+    copy_and_restart: persisted_with_entity
 
 GROUP_PREFIXES:
   BUDGET: PB
   COMPACTION: PX
   CYCLE: PR
   CONTEXT: PT
+  GLOSSARY_CAVEAT: GC
   ARCHIVE: PA
   VALIDATION: PV
 
@@ -228,6 +248,78 @@ CYCLE:
     description: >-
       Context envelope capturing intent, constraints, unknowns, and
       scope for this cycle. Contains sub-fields defined in CONTEXT group.
+  11:
+    id: PR11
+    field: glossary_caveat
+    type: mapping
+    required: false
+    implementation_status: active_build
+    authority: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.autonomous_caveat
+    description: >-
+      Privacy-safe autonomous glossary-review lifecycle evidence. Build alone
+      appends it through the typed progress writer. It is never glossary
+      publication, decision approval, plan state, or a container for meanings,
+      definitions, anchors, paths, raw sections, unrelated entries, or provenance.
+  12:
+    id: PR12
+    field: publication_order
+    type: integer
+    required: false
+    cli_owned: true
+    description: >-
+      Positive safe integer assigned by the progress writer under the publication
+      lock. New full records use it to resolve equal-minute semantic recency.
+      Legacy records may omit it; callers cannot supply or override it.
+    validation:
+      - "When present, must be a positive safe integer"
+      - "Must be omitted from caller input and assigned by the CLI writer"
+
+GLOSSARY_CAVEAT:
+  schema_version: agentera.glossaryConsumerCaveat.v1
+  implementation_status: active_build
+  reader_status:
+    prime: active
+  envelope_validator: packages/cli/src/state/progressGlossaryCaveat.ts#validateProgressGlossaryCaveat
+  lifecycle_validator: packages/cli/src/state/progressGlossaryCaveat.ts#glossaryCaveatLifecycleInvalidEntities
+  allowed_current_pairs: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.autonomous_caveat.allowed_current_pairs
+  current_append:
+    caller_fields: [event, reason, ownership_state]
+    caller_fixed_values:
+      event: current
+    writer_fields: [caveat_id, capability, transition_id]
+    writer_fixed_values:
+      capability: build
+      transition_id: null
+    rule: >-
+      The caller must submit event=current, reason, and ownership_state. The
+      writer creates caveat_id, capability=build, and transition_id=null; it does
+      not default the caller-owned event.
+  fields:
+    caveat_id:
+      type: opaque_non_content_id
+      required: true
+    event:
+      type: enum
+      values: [current, resolved, superseded]
+      required: true
+    capability:
+      type: enum
+      values: [build]
+      required: true
+    reason:
+      type: enum
+      values: [inferred_equivalence, authority_unavailable, personal_input_unavailable]
+      required: true
+    ownership_state:
+      type: enum
+      values: [project_governs_exact, review_required, authority_unavailable]
+      required: true
+    transition_id:
+      type: [opaque_non_content_id, "null"]
+      required: true
+  lifecycle: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.autonomous_caveat.lifecycle
+  prime_projection: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.autonomous_caveat.prime_projection
+  privacy: references/artifacts/glossary-entry-contract.yaml#consumer_boundary.disclosure.durable_surfaces
 
 CONTEXT:
   1: