agentera 3.0.0-dev.8 → 3.0.0-dev.80

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

@@ -1,33 +1,16 @@
 # Progress Artifact Schema
 #
-# 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.
+# Durable project-outcome log for build. A Build invocation can produce zero or
+# one entry. The typed writer's progress_write_policy decides whether future
+# work needs the outcome or a governed glossary caveat. Attempt-only evidence
+# stays outside progress.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
-#
-# ── Field-by-field mapping: v1 PROGRESS.md → v2 progress.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# ## Cycle N · date · type-prefix       CYCLE.number           PR1
-# (date from heading)                   CYCLE.timestamp        PR2
-# (type-prefix from heading)            CYCLE.type             PR3
-# **Phase**: <phase>                    CYCLE.phase            PR4
-# **What**: <text>                      CYCLE.what             PR5
-# **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
-# (scope from Context)                  CONTEXT.scope          PT4
-# ## Archived Cycles                    (implicit section)     —
-# - Cycle N (date): summary            ARCHIVE.summary        PA1
+# 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.
 # Protocol references:
 #   phase: PH1-PH5 (protocol.yaml PHASES)
 #   type: conventional commit prefix (feat/fix/docs/refactor/chore/test)
@@ -36,19 +19,47 @@ meta:
   name: progress
   version: "1.0.0"
   description: >-
-    Cycle-by-cycle operational log. Produced by build. Consumed by
-    capabilities that need recent work history and verification evidence.
+    Durable project-outcome log. Produced by build. Consumed by capabilities
+    that need recent project truth and verification evidence.
   artifact_type: agent_facing
   path: ".agentera/progress.yaml"
+  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
+  write_policy: input_schema.semantics.progress_write_policy
+  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 +83,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 +105,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 build writes a new cycle entry"
+    trigger: "When build writes a new durable outcome 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 +226,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,18 +1,20 @@
 # Todo Artifact Schema
 #
 # Open issues and tasks maintained by build and audit. Severity-ranked
-# checklist of work to be done, resolved items, and deferred work.
+# 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:
@@ -29,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.
@@ -46,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
@@ -60,6 +108,222 @@ 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
+    Singleton set-severity, supersede, resolve, and reopen require flag-only
+    reason and date values. Set-severity and resolve also accept strict
+    agentera.todoSetSeverityBatch.v1 and agentera.todoResolveBatch.v1 envelopes;
+    batches require dry-run preview and exact effect-confirmed apply.
+    supersede additionally requires a distinct existing replacement ID. These
+    These operations never accept unversioned 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:
@@ -127,3 +391,37 @@ CONVENTION:
       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

@@ -7,25 +7,6 @@
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
 # following capability_schema_contract.yaml and protocol.yaml conventions.
 #
-# ── Field-by-field mapping: v1 VISION.md → v2 vision.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# # <project name>                       HEADER.project_name    VN1
-# ## North Star                          NORTH_STAR.content     VN2
-# ## Who It's For / ### persona name     PERSONA.entry          VN3
-# (persona heading)                      PERSONA.name           VN4
-# (persona prose)                        PERSONA.description    VN5
-# ## Principles / - principle            PRINCIPLE.entry        VN6
-# (bold name + description)              PRINCIPLE.name         VN7
-# (principle prose)                      PRINCIPLE.description  VN8
-# ## Direction                           DIRECTION.content      VN9
-# ## Identity / ### Personality          IDENTITY.personality   VN10
-# ## Identity / ### Voice                IDENTITY.voice         VN11
-# ## Identity / ### Emotional register   IDENTITY.emotional_register VN12
-# ## Identity / ### Naming               IDENTITY.naming        VN13
-# ## The Tension                         TENSION.content        VN14
-#
 # Protocol references:
 #   No protocol primitives directly. Vision defines project-level identity
 #   that capabilities reference for voice and personality consistency.

package/dist/.agentera-build-source.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "agentera.generatedBuildSource.v1",
+  "commit": "296cb7e29c2521b95985f933b08f1a5d7724b4f0",
+  "tree": "732d6174b4bbf04834ff7fde86172e24ad69689c",
+  "files": 6856,
+  "workingTreeSha256": "0c148b6e30d19f0945267efa03f12d71e92587c80f8744b1cc1e0541de2ab9bd",
+  "identitySha256": "aec00264c492a72d7501ee6e58d69fa6fd1f10e0b3d5d75b0feff257e5874914"
+}