agentera 3.0.0-dev.3 → 3.0.0-dev.31

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

@@ -1,11 +1,12 @@
 # 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 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 +17,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,14 +37,26 @@ 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: agentera state progress list --format json
+    get: agentera state progress get --id ID --format json
+  mutation: agentera state progress explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: PB
   COMPACTION: PX
@@ -73,10 +85,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 +107,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,57 +190,38 @@ 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
@@ -293,14 +292,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

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

@@ -1,32 +1,23 @@
 # Todo Artifact Schema
 #
-# Open issues and tasks maintained by realisera and inspektera. Severity-ranked
+# Open issues and tasks maintained by build and audit. Severity-ranked
 # checklist of work to be done, resolved items, and deferred work.
 #
-# 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` 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 +29,7 @@ GROUP_PREFIXES:
 BUDGET:
   1:
     id: TB1
+    scope: full_file
     token_budget: 5000
     description: >-
       Maximum tokens for TODO.md content. Exceeding triggers compaction.
@@ -69,6 +61,181 @@ ITEM:
       Current status: open or resolved.
     validation:
       - "Must be one of: open, resolved"
+  4:
+    id: TI4
+    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.
+
+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 among open items of the same
+        severity. Lower values run first; 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 result is final; bounded output projection happens afterward.
+  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
+    within_severity: queue_rank_ascending
+    duplicate_rank: ordering_conflict
+    prohibited_tiebreakers:
+      - entity_id
+      - file_order
+      - filesystem_time
+      - created_or_modified_time
+      - description_text
+    description: >-
+      Severity remains primary. Equally severe actionable work is ordered only
+      by explicit queue_rank. Duplicate ranks require triage rather than an
+      invented chronology or opaque identity tie-break.
 
 CONVENTION:
   1:
@@ -76,16 +243,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,16 +263,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
+    field: severity_band_policy
+    level: required
+    description: >-
+      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: 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 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.
+      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: >-
+      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: