agentera 3.0.0-dev.4 → 3.0.0-dev.46

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

@@ -1,11 +1,17 @@
 # Progress Artifact Schema
 #
-# Cycle-by-cycle operational log for realisera. Each entry records what happened
-# in one development cycle: phase, work done, commit, discoveries, verification,
+# Cycle-by-cycle operational log for build. Each entry records what happened
+# in one development cycle: phase, work done, discoveries, verification,
 # next steps, and context envelope.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# 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.
 #
 # ── Field-by-field mapping: v1 PROGRESS.md → v2 progress.yaml ──
 #
@@ -16,12 +22,11 @@
 # (type-prefix from heading)            CYCLE.type             PR3
 # **Phase**: <phase>                    CYCLE.phase            PR4
 # **What**: <text>                      CYCLE.what             PR5
-# **Commit**: <hash/N/A>                CYCLE.commit           PR6
-# **Inspiration**: <text>               CYCLE.inspiration      PR7
-# **Discovered**: <text>                CYCLE.discovered       PR8
-# **Verified**: <text>                  CYCLE.verified         PR9
-# **Next**: <text>                      CYCLE.next             PR10
-# **Context**: <text>                   CYCLE.context          PR11
+# **Inspiration**: <text>               CYCLE.inspiration      PR6
+# **Discovered**: <text>                CYCLE.discovered       PR7
+# **Verified**: <text>                  CYCLE.verified         PR8
+# **Next**: <text>                      CYCLE.next             PR9
+# **Context**: <text>                   CYCLE.context          PR10
 # (intent from Context)                 CONTEXT.intent         PT1
 # (constraints from Context)            CONTEXT.constraints    PT2
 # (unknowns from Context)               CONTEXT.unknowns       PT3
@@ -37,19 +42,46 @@ meta:
   name: progress
   version: "1.0.0"
   description: >-
-    Cycle-by-cycle operational log. Produced by realisera. Consumed by
+    Cycle-by-cycle operational log. Produced by build. Consumed by
     capabilities that need recent work history and verification evidence.
   artifact_type: agent_facing
   path: ".agentera/progress.yaml"
-  producer: realisera
-  consumers: [dokumentera, hej, inspektera, optimera, orkestrera, planera, realisera, visionera, visualisera]
+  authority: legacy_migration_input_only
+  producer: build
+  consumers: [document, status, audit, optimize, orchestrate, plan, build, vision, design]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: progress
+  boundary: progress_cycle
+  retrieval:
+    list: npx -y agentera@next state progress list --format json
+    get: npx -y agentera@next state progress get --id ID --format json
+  mutation: npx -y agentera@next 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
 
@@ -73,10 +105,10 @@ BUDGET:
 COMPACTION:
   1:
     id: PX1
-    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: PX2
     full_detail:
@@ -95,21 +127,27 @@ COMPACTION:
     description: >-
       Cycles 11 through 50 are collapsed to one-line format under the
       archive section. One-line summaries preserve cycle number, date,
-      and work-type, enough for trend analysis by consuming skills.
+      and work-type, enough for trend analysis by consuming skills. Entries
+      beyond the summary default are represented by omission metadata while
+      their numbered archive records remain available.
   4:
     id: PX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Cycles 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: PX5
-    trigger: "When realisera writes a new cycle entry"
+    trigger: "When build writes a new cycle entry"
     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: PX6
     archive_section:
@@ -172,63 +210,116 @@ CYCLE:
       - "Non-empty string"
   6:
     id: PR6
-    field: commit
-    type: string
-    required: true
-    description: >-
-      Git commit that contains the product change for this cycle—not the commit
-      that last edited progress metadata. Use `pending` until that hash is known;
-      then the product commit hash, optionally with subject (e.g.
-      `abc1234 Speed up pytest suite`). Use `N/A: …` when no product commit was
-      made.
-    validation:
-      - "Non-empty string"
-      - "Use `pending` until the product-change commit hash is known; do not amend solely to backfill this field"
-      - >-
-        Hashes that do not resolve as commit objects in the local clone (another
-        machine's copy, shallow CI checkout, or not yet fetched) are intentionally
-        not flagged by progress validation or `agentera check backfill`; reconcile
-        with a full clone or forward-fill once the product commit exists locally
-  7:
-    id: PR7
     field: inspiration
     type: string
     required: false
     description: >-
       What prompted this cycle. References to active plan tasks,
       decisions, or conventions that drove the work.
-  8:
-    id: PR8
+  7:
+    id: PR7
     field: discovered
     type: string
     required: false
     description: >-
       Unexpected findings during the cycle. Things learned that were
       not known before starting.
-  9:
-    id: PR9
+  8:
+    id: PR8
     field: verified
     type: string
     required: false
     description: >-
       Evidence that the work was verified. Test commands run, validation
       passed, manual checks performed.
-  10:
-    id: PR10
+  9:
+    id: PR9
     field: next
     type: string
     required: false
     description: >-
       What should happen next. Guidance for subsequent cycles.
       Explicit about scope boundaries to prevent scope creep.
-  11:
-    id: PR11
+  10:
+    id: PR10
     field: context
     type: map
     required: true
     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:
@@ -293,14 +384,13 @@ VALIDATION:
     severity: error
     description: >-
       Each full-detail cycle entry must have: number, timestamp, type,
-      phase, what, commit, and context (with intent).
+      phase, what, and context (with intent).
     checks:
       - "number is present and is a positive integer"
       - "timestamp is present and matches YYYY-MM-DD HH:MM"
       - "type is present and is a valid commit prefix"
       - "phase is present and is a valid phase name"
       - "what is present and non-empty"
-      - "commit is present"
       - "context is present with intent sub-field"
   3:
     id: PV3