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

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
+# 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 ──
 #
@@ -36,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
 
@@ -72,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:
@@ -94,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:
@@ -209,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:

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

@@ -1,32 +1,25 @@
 # Todo Artifact Schema
 #
-# Open issues and tasks maintained by realisera and inspektera. Severity-ranked
-# checklist of work to be done, resolved items, and deferred work.
+# Open issues and tasks maintained by build and audit. Severity-ranked
+# checklist of work to be done, resolved items, and deferred work. New writes
+# use the typed record below; the legacy description form remains readable only
+# through the explicit compatibility boundary used by entity migration.
 #
-# Note: TODO.md is a human-facing Markdown artifact. It remains at the
-# project root and is not migrated to YAML. This schema exists for validation
-# and CLI discovery consistency.
+# Marker-absent projects retain TODO.md as legacy authority. After durable
+# entity cutover, each item is authoritative in one shared-contract entity
+# file and `agentera state todo list` renders the bounded human-facing view.
 
 meta:
   name: todo
   version: "1.0.0"
   description: >-
     Open issues and tasks. Produced by capabilities that file work or findings.
-    Human-facing: remains Markdown at project root.
+    Human-facing legacy aggregate before cutover; bounded entity view after cutover.
   artifact_type: human_facing
   path: "TODO.md"
   producer:
-    [
-      dokumentera,
-      inspektera,
-      inspirera,
-      optimera,
-      orkestrera,
-      realisera,
-      resonera,
-      visualisera,
-    ]
-  consumers: [hej, all_skills]
+    [document, audit, research, optimize, orchestrate, build, discuss, design]
+  consumers: [status, all_skills]
   format: markdown
 
 GROUP_PREFIXES:
@@ -38,6 +31,7 @@ GROUP_PREFIXES:
 BUDGET:
   1:
     id: TB1
+    scope: full_file
     token_budget: 5000
     description: >-
       Maximum tokens for TODO.md content. Exceeding triggers compaction.
@@ -55,13 +49,58 @@ ITEM:
       - "Must be one of: critical, degraded, normal, annoying"
   2:
     id: TI2
-    field: description
+    field: kind
     type: string
     required: true
     description: >-
-      Brief description of the task or issue.
+      Work kind rendered as the public `[kind:target]` marker. It is not
+      severity; severity describes immediate impact.
   3:
     id: TI3
+    field: target_version
+    type: string_or_null
+    required: true
+    clearable: true
+    description: >-
+      Release target used with release_blocker; stable-cut dependencies need
+      not be critical.
+  4:
+    id: TI4
+    field: title
+    type: string
+    required: true
+    description: Short public TODO title, owned by TODO.md.
+  5:
+    id: TI5
+    field: requirements
+    type: string_list
+    required: true
+    clearable: true
+    description: Typed public requirements; an empty list is an explicit clear.
+  6:
+    id: TI6
+    field: acceptance
+    type: string_list
+    required: true
+    clearable: true
+    description: Typed public acceptance criteria; an empty list is an explicit clear.
+  7:
+    id: TI7
+    field: release_blocker
+    type: boolean
+    required: true
+    description: Release-gate state. Do not infer it from severity.
+  8:
+    id: TI8
+    field: description
+    type: string
+    required: false
+    compatibility: legacy_only
+    description: >-
+      Legacy public prose retained for existing entities. New typed records
+      use title and never store the `[kind:target]` marker in prose.
+  9:
+    id: TI9
     field: status
     type: string
     required: true
@@ -69,6 +108,219 @@ ITEM:
       Current status: open or resolved.
     validation:
       - "Must be one of: open, resolved"
+  10:
+    id: TI10
+    field: readiness
+    type: mapping
+    required: false
+    description: >-
+      Reviewer-declared state readiness. Absence means needs-triage and MUST
+      NOT be interpreted from description prose. When present, the complete
+      nested shape is owned by READINESS below.
+
+PUBLIC_OWNERSHIP:
+  description: >-
+    TODO.md owns public kind, target version, title, requirements, acceptance,
+    release blocker, severity, checkbox status, and within-severity order.
+    Agentera owns readiness, dependencies, gates, evidence, and lifecycle
+    transition metadata. A public disagreement is a conflict, never a silent
+    winner.
+  render: "[kind:target] title"
+  severity: >-
+    Immediate impact only. Release gating is release_blocker plus target_version;
+    a stable-cut dependency does not need critical severity.
+
+LIFECYCLE:
+  description: >-
+    activate is a flag-only reconciliation transition that requires the
+    preview effect SHA-256 and explicit confirmation. Item lifecycle transitions
+    set-severity, supersede, resolve, and reopen require a reason and date;
+    supersede additionally requires a distinct existing replacement ID. These
+    operations never accept structured record content or use Markdown
+    strikethrough.
+  clearable_patch_fields: [target_version, requirements, acceptance, readiness]
+  cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+  transition_fields: [reason, date, replacement]
+
+READINESS:
+  schema_version: agentera.todoReadiness.v1
+  description: >-
+    Single authority for a TODO item's intended destination, eligibility,
+    attention, recovery, and ordering semantics. Request routing remains
+    separate and open-ended language remains host-owned.
+  destination:
+    phase_authority: protocol.yaml#PHASES[*].capabilities
+    description: >-
+      The exact allowed destination set is the union of capabilities in the
+      canonical PHASES entries. A capability's containing PHASES entry is its
+      phase; TODO does not repeat either list or mapping.
+    excluded_capabilities:
+      status: >-
+        Orientation consumes readiness but is not work a TODO can request.
+      orchestrate: >-
+        Execution mode selects plan tasks but is not a TODO's work intent.
+  fields:
+    capability:
+      type: string
+      required: true
+      enum_source: protocol.yaml#PHASES[*].capabilities
+      description: Reviewer-approved capability that owns the next action.
+    reason:
+      type: string
+      required: true
+      non_empty: true
+      description: Durable intent explaining why the destination is correct.
+    dependencies:
+      type: list
+      required: true
+      description: >-
+        Zero or more TODO prerequisites. Only canonical TODO entity IDs are
+        valid; artifact-qualified references make cross-artifact mistakes
+        explicit instead of guessing identity.
+      entries:
+        artifact:
+          type: string
+          required: true
+          const: todo
+        id:
+          type: string
+          required: true
+          pattern: "^[a-z]{10}$"
+    blocked:
+      type: [mapping, "null"]
+      required: true
+      description: Explicit blocker, or null when no blocker is declared.
+      fields:
+        reason: {type: string, required: true, non_empty: true}
+        recovery: {type: string, required: true, non_empty: true}
+    gate:
+      type: [mapping, "null"]
+      required: true
+      description: Explicit external or approval gate, or null when ungated.
+      fields:
+        state: {type: string, required: true, enum: [pending, satisfied]}
+        reason: {type: string, required: true, non_empty: true}
+        recovery: {type: string, required: true, non_empty: true}
+    queue_rank:
+      type: integer
+      required: true
+      minimum: 1
+      description: >-
+        Reviewer-assigned durable intent order for nonprojected queues and for
+        projected entities intentionally absent from managed Markdown. Managed
+        projected rows use Markdown order instead. Lower values run first when
+        queue rank applies; the number is priority, not time.
+    order_reason:
+      type: string
+      required: true
+      non_empty: true
+      description: Durable reason for the queue_rank assignment.
+  evaluation:
+    precedence:
+      - todo_resolved
+      - readiness_absent
+      - blocked
+      - gate_pending
+      - dependency_cross_artifact
+      - dependency_missing
+      - dependency_cycle
+      - dependency_open
+      - ordering_conflict
+      - actionable
+    description: >-
+      Evaluate once in this order against complete entity state. The first
+      matching item result is final; bounded output projection happens afterward.
+      ordering_conflict applies only in nonprojected ordering mode.
+  outcomes:
+    todo_resolved:
+      result: resolved
+      eligible: false
+      attention: none
+      recovery: null
+    readiness_absent:
+      result: needs-triage
+      eligible: false
+      attention: item
+      recovery: Review the item and declare readiness through the typed TODO writer.
+    blocked:
+      result: blocked
+      eligible: false
+      attention: item
+      recovery: Emit only the declared bounded blocked.recovery action.
+    gate_pending:
+      result: gated
+      eligible: false
+      attention: none
+      recovery: Emit only the declared bounded gate.recovery action; re-evaluate after the gate is satisfied.
+    dependency_cross_artifact:
+      result: needs-triage
+      eligible: false
+      attention: item
+      recovery: Replace the reference with a canonical TODO dependency or remove it after review.
+    dependency_missing:
+      result: needs-triage
+      eligible: false
+      attention: item
+      recovery: Restore the referenced TODO or remove the stale dependency after review.
+    dependency_cycle:
+      result: needs-triage
+      eligible: false
+      attention: item
+      recovery: Break the cycle by reviewing and updating at least one TODO dependency.
+    dependency_open:
+      result: waiting
+      eligible: false
+      attention: none
+      recovery: Resolve the canonical TODO dependency, then re-evaluate this item.
+    dependency_resolved:
+      result: satisfied
+      eligible: null
+      attention: none
+      recovery: null
+    ordering_conflict:
+      result: needs-triage
+      eligible: false
+      attention: item
+      recovery: Assign distinct queue_rank values to same-severity actionable items after review.
+    actionable:
+      result: actionable
+      eligible: true
+      attention: none
+      recovery: null
+  queue_outcomes:
+    mixed_actionable_and_triage:
+      selection: highest_ordered_actionable
+      attention: bounded_triage_summary
+      recovery: Review unannotated or invalid items separately; do not displace actionable work.
+    all_non_actionable:
+      selection: abstain
+      attention: bounded_highest_severity_summary
+      recovery: Emit the first matching contract-owned item recovery; never infer plan or build from prose.
+  ordering:
+    primary: protocol.yaml#SEVERITY_ISSUE
+    modes:
+      nonprojected:
+        within_severity: queue_rank_ascending
+        duplicate_rank: ordering_conflict
+        prohibited_tiebreakers:
+          - entity_id
+          - file_order
+          - filesystem_time
+          - created_or_modified_time
+          - description_text
+      projected_startup:
+        entity_annotation: required_for_every_entity
+        eligibility: before_order
+        managed_before_absent: true
+        managed_within_severity: markdown_order_ascending
+        managed_duplicate_rank: ignored
+        absent_within_severity: queue_rank_then_id
+        absent_duplicate_rank: entity_id_ascending
+    description: >-
+      Severity remains primary. Nonprojected callers retain reviewed queue-rank
+      conflict behavior. Projected startup declares one order annotation for
+      every entity, filters operationally ineligible items first, then orders
+      managed rows by Markdown and absent rows by queue rank and ID.
 
 CONVENTION:
   1:
@@ -76,16 +328,17 @@ CONVENTION:
     field: type_tag
     level: advisory
     description: >-
-      Each item should carry a type tag such as [fix], [feat], [chore],
-      [test], [perf], or [docs] for commit-scope alignment and scan
-      discoverability.
+      Each item should carry a type tag such as [fix], [feat], [refactor],
+      [chore], [test], [perf], or [docs] for commit-scope alignment and
+      scan discoverability.
   2:
     id: TC2
     field: version_suffix
     level: advisory
     description: >-
-      Feature and fix items should include a version scope like [fix:2.4.x]
-      or [feat:2.3.x] when the work targets a specific release train.
+      Optional train scope in `[type:train]` form, e.g. `[fix:train]`, when
+      the work targets a specific release train; most common on feat and fix
+      items. Omit the train suffix when the item is not train-scoped.
   3:
     id: TC3
     field: title_format
@@ -95,30 +348,77 @@ CONVENTION:
       either all plain prose or all "**BoldTitle**: description".
   4:
     id: TC4
-    field: resolved_summary
+    field: resolved_checkbox
     level: advisory
     description: >-
-      Resolved items should end with "· resolved by ..." to distinguish
-      completed work from open or deferred items at a glance.
+      Resolved items should use a checked GitHub task-list checkbox
+      (`- [x]`) before the task text. Open items use `- [ ]`. The
+      checkbox state is the canonical completion marker; do not wrap
+      resolved text in Markdown strikethrough.
   5:
     id: TC5
-    field: resolved_strikethrough
-    level: advisory
+    field: severity_band_policy
+    level: required
     description: >-
-      Resolved items should wrap the original task text in Markdown
-      strikethrough (~~text~~) before the resolution summary, keeping
-      the original intent readable while visually marking it closed.
+      Severity band policy: all four severity bands (⇶ Critical, ⇉
+      Degraded, → Normal, ⇢ Annoying) may be header-only when they
+      have no open work. Open items use `- [ ]` only. Resolved items
+      must not appear in severity bands (see TC6). Executable checks
+      live in packages/cli/src/hooks/validateArtifact/markdown.ts
+      `validateMdItems` and packages/cli/src/hooks/compaction/parse.ts.
   6:
     id: TC6
-    field: severity_band_policy
+    field: resolved_section_placement
+    level: required
+    description: >-
+      Resolved ledger policy: completed items live only under
+      `## ✓ Resolved` as `- [x] [type:train]` checkboxes. Severity
+      bands must not contain `- [x]` or legacy `~~` strikethrough
+      resolved rows. The compaction gate counts every resolved row
+      (including mis-placed rows until migrated) against the uniform
+      10/40/50 retention cap. `compact --mode fix` migrates mis-placed
+      rows into `## ✓ Resolved` before applying retention.
+  7:
+    id: TC7
+    field: resolved_line_provenance
+    level: advisory
+    description: >-
+      Resolved provenance uses `resolved YYYY-MM-DD` or `resolved @
+      <semver>` after the item description. Do not use `resolved on
+      feat/v3 @ <hash>` or dual-branch hash reconciliation; git history
+      is the archaeology source. Fold the Resolved move into the
+      implementation commit — no follow-up hash-backfill commit.
+  8:
+    id: TC8
+    field: single_resolved_section
+    level: required
+    description: >-
+      Exactly one `## ✓ Resolved` section is permitted. Two or more
+      `## ✓ Resolved` sections hide the trailing entries from parsing
+      (which processes only the first) and from the compaction budget
+      gate. Validation (`validateTodoResolvedPlacement`) and compaction
+      (status + apply) refuse with an actionable diagnostic when more
+      than one is present; merge the duplicates into a single section
+      before compacting. See TC6 for placement and TC9 for recovery.
+  9:
+    id: TC9
+    field: bounded_queue_not_lossless_archive
     level: required
     description: >-
-      Severity band policy: Critical (⇶) is enforced by the validator
-      (level: required) and must contain at least one `- [type]` item;
-      Degraded (⇉), Normal (→), and Annoying (⇢) are advisory and may
-      be header-only (no list entries, no Placeholder sentinel). The
-      asymmetry reflects the fact that Critical is the only band whose
-      absence is user-visible routing damage; the other three bands
-      may be honestly empty. This rule lives in
-      packages/cli/src/hooks/validateArtifact.ts `validateMdItems` as
-      the single executable source of truth.
+      TODO.md is a bounded human-facing queue, not a lossless numbered
+      archive. It is excluded from the lossless numbered-archive model
+      that governs progress, decisions, and health (those preserve
+      verified numbered archives; TODO does not). Older resolved
+      entries and their detail bodies may be summarized to one-line or
+      removed entirely to stay within the 10/40/50 retention cap;
+      removal is destructive in the working tree. The first ten
+      resolved rows are the recent/full-detail tier even when they have
+      no indented body; rows 11 through 50 are the summary tier; rows
+      beyond 50 are dropped. Git history is the designated archaeology
+      source for dropped resolved entries, and only for previously
+      committed content: inspect prior versions with
+      `git log -p -- :/TODO.md` (the `:/` pathspec is project-root-safe
+      regardless of the current working directory). Non-Git projects
+      have no historical recovery for dropped entries. Compaction
+      diagnostics MUST report removed entries as `dropped` and MUST NOT
+      describe TODO compaction as a lossless projection.

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

@@ -35,13 +35,13 @@ meta:
   name: vision
   version: "1.0.0"
   description: >-
-    Project vision. Produced by visionera and direction-shaping capabilities.
+    Project vision. Produced by vision and direction-shaping capabilities.
     Consumed by capabilities that need strategic alignment. No compaction:
     vision is not a growing artifact.
   artifact_type: agent_facing
   path: ".agentera/vision.yaml"
-  producer: [inspirera, realisera, resonera, visionera]
-  consumers: [dokumentera, hej, inspektera, orkestrera, planera, realisera, resonera, visionera, visualisera]
+  producer: [research, build, discuss, vision]
+  consumers: [document, status, audit, orchestrate, plan, build, discuss, vision, design]
   format: yaml
 
 GROUP_PREFIXES: