agentera 3.0.0-dev.20 → 3.0.0-dev.21

package/bundle/skills/agentera/references/contract.md

@@ -252,21 +252,34 @@ The test: if a reader can reconstruct the information from the project's current
 
 ### Compaction thresholds
 
-Growing artifacts are compacted to cap read cost for consuming skills. Compaction runs when the producing skill writes a new entry. All growing artifacts follow a uniform 10/40/50 rule: 10 full-detail entries, 40 one-line archive entries, drop beyond 50 total.
+Numbered state artifacts use `uniform_10_40_50` as projection capacity to cap
+read cost for consuming skills: 10 active full-detail entries and 40 archive
+projection entries. These are bounded active/archive projections, not retention
+or deletion limits. Verified numbered archives remain authoritative; projection
+compaction performs no destructive deletion. Recovery refuses to omit entries
+when archive evidence is missing and retains full entries with metadata.
+Compaction runs when the producing skill writes a new entry. Other artifacts
+retain their owning artifact-specific compaction rules below.
 
 **CHANGELOG.md is exempt**: it is the public version-level history and is not compacted.
 
 **PROGRESS.md**, compacted by realisera when writing a new cycle entry:
 
-| Tier             | Entries               | Format                                   |
-| ---------------- | --------------------- | ---------------------------------------- |
-| Full detail      | 10 most recent cycles | Standard cycle entry format              |
-| One-line archive | Cycles 11 through 50  | `Cycle N (YYYY-MM-DD): ≤15-word summary` |
-| Dropped          | Cycles older than 50  | Removed entirely                         |
+| Tier                | Entries               | Format                                   |
+| ------------------- | --------------------- | ---------------------------------------- |
+| Active full detail  | 10 most recent cycles | Standard cycle entry format              |
+| Archive projection  | Cycles 11 through 50  | `Cycle N (YYYY-MM-DD): ≤15-word summary` |
+| Outside projection  | Older cycles          | Omission metadata; numbered archive      |
 
-When writing a new cycle: if >10 full-detail entries exist, collapse the oldest to one-line format under an `## Archived Cycles` heading (below the recent cycles). If >40 one-line entries exist, drop the oldest. One-line summaries preserve cycle number, date, and work-type, enough for trend analysis by consuming skills.
+When writing a new cycle: if >10 full-detail entries exist and their numbered
+archives verify, collapse the oldest to one-line format under an `## Archived
+Cycles` heading (below the recent cycles). If >40 one-line entries exist, omit
+the oldest from this bounded projection with metadata; if archive evidence is
+missing, retain the full entry and refuse the projection change. One-line
+summaries preserve cycle number, date, and work-type, enough for trend analysis
+by consuming skills.
 
-Active cycle entries are stored newest-first: descending by cycle number. Insert the newest full-detail cycle before older active cycles so `agentera progress --limit 1` reads the current cycle without scanning the full file.
+Active cycle entries are stored newest-first: descending by cycle number. Insert the newest full-detail cycle before older active cycles so `agentera state progress list --limit 1 --format json` reads the current cycle through the bounded state interface.
 
 **EXPERIMENTS.md**, compacted by optimera when writing a new experiment:
 
@@ -276,17 +289,24 @@ Active cycle entries are stored newest-first: descending by cycle number. Insert
 | One-line archive | Experiments 11 through 50  | `EXP-N: ≤15-word result summary` |
 | Dropped          | Experiments older than 50  | Removed entirely                 |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent experiments under an `## Archived Experiments` heading.
+Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest
+one-line when >40 one-line entries exist. Archive section sits below recent
+experiments under an `## Archived Experiments` heading.
 
 **DECISIONS.md**, compacted by resonera when writing a new decision:
 
-| Tier             | Entries                  | Format                                                 |
-| ---------------- | ------------------------ | ------------------------------------------------------ |
-| Full detail      | 10 most recent decisions | Standard decision entry format                         |
-| One-line archive | Decisions 11 through 50  | `Decision N (YYYY-MM-DD): [Choice] — ≤15-word summary` |
-| Dropped          | Decisions older than 50  | Removed entirely                                       |
+| Tier                | Entries                  | Format                                                 |
+| ------------------- | ------------------------ | ------------------------------------------------------ |
+| Active full detail  | 10 most recent decisions | Standard decision entry format                         |
+| Archive projection  | Decisions 11 through 50  | `Decision N (YYYY-MM-DD): [Choice] — ≤15-word summary` |
+| Outside projection  | Older decisions          | Omission metadata; numbered archive                   |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent decisions under an `## Archived Decisions` heading. One-line summaries preserve decision number, date, and the chosen alternative.
+Same logic: collapse oldest full-detail to one-line when >10 exist and their
+numbered archives verify. If >40 one-line entries exist, omit the oldest from
+this bounded projection with metadata; if archive evidence is missing, retain
+the full entry and refuse the projection change. Archive section sits below
+recent decisions under an `## Archived Decisions` heading. One-line summaries
+preserve decision number, date, and the chosen alternative.
 
 When writing a new decision, choose `N` as one greater than the highest decision number in active and archived entries. Insert the new full entry in the active section immediately before `## Archived Decisions`; if no archive exists, append it at the end of the file. Active decision entries must have unique numbers and remain ascending by decision number. Do not reuse or renumber decisions except when repairing artifact corruption.
 
@@ -294,23 +314,45 @@ When writing a new decision, choose `N` as one greater than the highest decision
 
 **HEALTH.md**, compacted by inspektera when writing a new audit:
 
-| Tier             | Entries               | Format                                             |
-| ---------------- | --------------------- | -------------------------------------------------- |
-| Full detail      | 10 most recent audits | Standard audit entry format                        |
-| One-line archive | Audits 11 through 50  | `Audit N (YYYY-MM-DD): [grade] — ≤15-word summary` |
-| Dropped          | Audits older than 50  | Removed entirely                                   |
+| Tier                | Entries               | Format                                             |
+| ------------------- | --------------------- | -------------------------------------------------- |
+| Active full detail  | 10 most recent audits | Standard audit entry format                        |
+| Archive projection  | Audits 11 through 50  | `Audit N (YYYY-MM-DD): [grade] — ≤15-word summary` |
+| Outside projection  | Older audits          | Omission metadata; numbered archive                |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent audits under an `## Archived Audits` heading. One-line summaries preserve audit number, date, overall grade, and trajectory.
+Same logic: collapse oldest full-detail to one-line when >10 exist and their
+numbered archives verify. If >40 one-line entries exist, omit the oldest from
+this bounded projection with metadata; if archive evidence is missing, retain
+the full entry and refuse the projection change. Archive section sits below
+recent audits under an `## Archived Audits` heading. One-line summaries preserve
+audit number, date, overall grade, and trajectory.
 
 **TODO.md Resolved section**, compacted by realisera when marking an item resolved:
 
 | Tier             | Entries                       | Format                                           |
 | ---------------- | ----------------------------- | ------------------------------------------------ |
 | Full detail      | 10 most recent resolved items | Standard resolved entry format                   |
-| One-line archive | Items 11 through 50           | `- [x] [type:train] ≤15-word resolution summary` |
+| One-line summary | Items 11 through 50           | `- [x] [type:train] ≤15-word resolution summary` |
 | Dropped          | Items older than 50           | Removed entirely                                 |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Compaction applies only within the `## ✓ Resolved` section; active severity sections are not affected.
+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. Collapse the oldest
+full-detail entries to one line when more than 10 exist. Drop the oldest
+summaries when more than 40 exist. Compaction applies only within the
+`## ✓ Resolved` section; active severity sections are not affected.
+
+TODO.md is a **bounded human-facing queue, not a lossless numbered archive**.
+Unlike progress, decisions, and health—which preserve verified numbered archives
+and perform no destructive deletion—TODO compaction is intentionally destructive.
+Dropped resolved entries are removed from the working tree and are recoverable
+only for previously committed content through project history
+(`git log -p -- :/TODO.md`; the `:/` pathspec is project-root-safe). 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. Exactly one `## ✓ Resolved` section is permitted;
+parsing, validation, and compaction refuse with an actionable diagnostic when
+duplicates are present because parsing processes only the first section and
+otherwise hides trailing entries from the budget.
 
 ## 5. Artifact Path Resolution
 

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

@@ -69,10 +69,10 @@ BUDGET:
 COMPACTION:
   1:
     id: DX1
-    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: DX2
     full_detail:
@@ -93,21 +93,26 @@ COMPACTION:
       the archive section. Compact summaries preserve decision number, date,
       and chosen alternative; structured compact fields preserve outcome and
       explicit feeds_into references when present so CLI downstream references
-      remain non-inferential.
+      remain non-inferential. Entries beyond the summary default are represented
+      by omission metadata while their numbered archive records remain available.
   4:
     id: DX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Decisions 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: DX5
     trigger: "When discuss writes a new decision"
     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. Unresolved review entries do not block storage.
   6:
     id: DX6
     archive_section:

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

@@ -2,7 +2,7 @@
 #
 # Experiment log maintained by optimize. Each experiment records hypothesis,
 # method, metric results, kept/discarded status, and conclusions. Lives
-# alongside OBJECTIVE.md in .agentera/optimera/<name>/.
+# alongside OBJECTIVE.md in .agentera/optimize/<name>/.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
 # following capability_schema_contract.yaml and protocol.yaml conventions.
@@ -41,9 +41,9 @@ meta:
   version: "1.0.0"
   description: >-
     Experiment log for optimize objectives. Produced and consumed by optimize.
-    Lives in .agentera/optimera/<name>/ alongside the objective.
+    Lives in .agentera/optimize/<name>/ alongside the objective.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/experiments.yaml"
+  path: ".agentera/optimize/<name>/experiments.yaml"
   producer: optimize
   consumers: [status, optimize]
   format: yaml
@@ -54,6 +54,8 @@ GROUP_PREFIXES:
   EXPERIMENT: EX
   CLOSURE: EC
   ARCHIVE: EA
+  PUBLICATION: EP
+  RETRIEVAL: ER
   VALIDATION: EV
 
 BUDGET:
@@ -133,6 +135,7 @@ EXPERIMENT:
     validation:
       - "Must be a non-negative integer"
       - "Must be unique across active and archived entries"
+      - "Identity is <objective-id>/experiment:<number>"
   2:
     id: EX2
     field: date
@@ -267,6 +270,94 @@ EXPERIMENT:
       Harness refinement log for baseline experiments. Each entry
       records a run number, issue encountered, and fix applied.
 
+PUBLICATION:
+  1:
+    id: EP1
+    operation: publish
+    command: >-
+      agentera state experiments publish --objective OBJECTIVE_ID --number N
+      --input EXPERIMENT.yaml --format json
+    description: >-
+      The typed state writer is the mutation authority. It validates the
+      objective, identity, caller entry, existing projection, and final bytes
+      before assigning number and atomically publishing one experiment.
+  2:
+    id: EP2
+    identity: '<objective-id>/experiment:<non-negative-integer>'
+    cli_owned_fields: [number]
+    retry: byte_equivalent_identity_is_idempotent
+    collision: same_identity_with_different_content_fails
+    description: >-
+      Retry never duplicates an experiment. Invalid identity, collisions, and
+      pre-publication failures preserve active and archive projection bytes.
+  3:
+    id: EP3
+    projection: uniform_10_40_50
+    durable_archive: objective_scoped_immutable_full_detail
+    description: >-
+      Publication validates and durably publishes the full experiment under
+      the objective directory before replacing the compacted projection. The
+      projection still retains 10 full entries and 40 one-line summaries.
+  4:
+    id: EP4
+    archive_path: '.agentera/<objective-root>/<objective>/archive/experiments/<experiment-number>.yaml'
+    canonical_objective_root: optimize
+    readable_legacy_objective_roots: [optimera]
+    envelope_schema: agentera.experimentArchive.v1
+    required_fields:
+      - schemaVersion
+      - stable_id
+      - objective_id
+      - experiment_number
+      - record
+      - record_sha256
+      - provenance
+    provenance_fields: [authority, objective_id, experiment_id, storage_scope, publication_order]
+    retry: byte_equivalent_envelope_is_idempotent
+    collision: same_identity_with_different_bytes_fails
+    description: >-
+      Archive identity binds stable objective and experiment identity to the
+      immutable full record. Legacy projection entries remain readable without
+      fabricating archive history that predates this publication contract.
+  5:
+    id: EP5
+    directory_durability: fsync_each_new_child_parent_before_advancing
+    exact_full_replay: reconstruct_missing_archive_before_success
+    summary_only_replay: never_reconstruct_without_full_detail
+    description: >-
+      First publication durably records every new archive directory entry.
+      Replay may recover only the exact full record still present in the
+      projection; compacted summaries and dropped rows are not fabricated.
+
+RETRIEVAL:
+  1:
+    id: ER1
+    list: >-
+      agentera state experiments list --objective OBJECTIVE_ID [--limit N]
+      [--cursor TOKEN] --format json
+    get: >-
+      agentera state experiments get --objective OBJECTIVE_ID --number N
+      --format json
+    description: >-
+      List returns newest-first objective-scoped identities from the bounded
+      projection and immutable archive. Get returns one exact identity.
+  2:
+    id: ER2
+    cursor: opaque_snapshot_cursor
+    cursor_binding: [collection, objective, order, snapshot]
+    detail_availability: [full, summary, unavailable]
+    description: >-
+      Cursor tokens are copied, never parsed or constructed. List and get retain
+      compatibility and provenance when legacy detail is summary-only or absent.
+  3:
+    id: ER3
+    maximum_limit: 100
+    max_serialized_utf8_bytes: 32768
+    omission_fields: [omitted, omitted_count, omission_reason, retrieval]
+    description: >-
+      Structured pages omit whole entries rather than truncating scalar values;
+      every addressable omission has continuation or exact-get recovery.
+
 CLOSURE:
   1:
     id: EC1
@@ -371,3 +462,43 @@ VALIDATION:
       and serve as the reference measurement.
     checks:
       - "Experiment 0 has status 'baseline'"
+  6:
+    id: EV6
+    rule: identity_compatibility
+    severity: error
+    description: >-
+      Experiment identity is objective-scoped. Reads retain legacy entries with
+      missing or duplicate numbers as unaddressable data with explicit caveats;
+      a new publication must reject ambiguous objective or experiment identity
+      before changing objective, experiment, or archive bytes.
+    checks:
+      - "Objective identity is stable across title and directory rename"
+      - "Experiment 0 and later non-negative numbers are addressable"
+      - "Duplicate or missing experiment numbers remain visible but unaddressable"
+      - "Publication rejects ambiguity before effects"
+  7:
+    id: EV7
+    rule: validated_publication
+    severity: error
+    description: >-
+      New experiments are published only through the typed writer after pure
+      identity and schema preflight, with atomic replacement and idempotent retry.
+    checks:
+      - "Caller input omits the CLI-owned number field"
+      - "Objective and experiment identity validate before staging"
+      - "Final experiments.yaml bytes validate before atomic replacement"
+      - "A byte-equivalent retry returns the existing experiment without duplication"
+  8:
+    id: EV8
+    rule: durable_archive_before_projection
+    severity: error
+    description: >-
+      Newly published full detail must be validated, immutably archived, and
+      directory-synced before the compacted projection is replaced.
+    checks:
+      - "Archive envelope identity and provenance validate before publication"
+      - "Every newly created archive directory entry is parent-synced in order"
+      - "Archive publication succeeds before projection replacement"
+      - "Exact full replay reconstructs a missing archive before success"
+      - "Conflicting immutable archive bytes preserve archive and projection"
+      - "Retry after archive or projection interruption does not duplicate detail"

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

@@ -87,10 +87,10 @@ BUDGET:
 COMPACTION:
   1:
     id: HX1
-    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: HX2
     full_detail:
@@ -109,21 +109,27 @@ COMPACTION:
     description: >-
       Audits 11 through 50 are collapsed to one-line format under the
       archive section. One-line summaries preserve audit number, date,
-      overall grade, and trajectory.
+      overall grade, and trajectory. Entries beyond the summary default are
+      represented by omission metadata while their numbered archive records
+      remain available.
   4:
     id: HX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Audits 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: HX5
     trigger: "When audit writes a new audit"
     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: HX6
     archive_section:

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

@@ -1,7 +1,7 @@
 # Objective Artifact Schema
 #
 # Optimization objective maintained by optimize. Each objective lives in its
-# own subdirectory under .agentera/optimera/<name>/ and captures the metric,
+# own subdirectory under .agentera/optimize/<name>/ and captures the metric,
 # target, baseline, constraints, measurement method, gates, and scope.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
@@ -48,9 +48,9 @@ meta:
   version: "1.0.0"
   description: >-
     Optimization objective. Produced by optimize and discuss. Each objective
-    lives in its own subdirectory under .agentera/optimera/<name>/.
+    lives in its own subdirectory under .agentera/optimize/<name>/.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/objective.yaml"
+  path: ".agentera/optimize/<name>/objective.yaml"
   producer: [optimize, discuss]
   consumers: [status, optimize, discuss]
   format: yaml
@@ -78,6 +78,19 @@ BUDGET:
       bounded by the measurement description's inherent complexity.
 
 HEADER:
+  0:
+    id: OB_HDR0
+    field: id
+    type: string
+    required: true
+    description: >-
+      Stable objective identity in objective:<lowercase RFC 9562 UUID> form.
+      It is assigned when a new objective is published and remains unchanged
+      when the title or containing directory is renamed. Legacy objectives
+      without this field remain read-compatible through a derived identity and
+      an explicit compatibility caveat; reads never rewrite legacy bytes.
+    validation:
+      - "Matches objective:<lowercase-rfc9562-uuid>"
   1:
     id: OB_HDR1
     field: title
@@ -360,10 +373,11 @@ VALIDATION_RULES:
     rule: required_fields
     severity: error
     description: >-
-      The objective must have: title, status, description, why,
+      A newly published objective must have: stable id, title, status, description, why,
       measurement, metric (description, direction, unit), baseline,
       and scope (included, excluded).
     checks:
+      - "id is present and matches objective:<lowercase-rfc9562-uuid>"
       - "title is present and non-empty"
       - "status is present and is 'open' or 'closed'"
       - "description is present and non-empty"

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

@@ -142,6 +142,17 @@ HEADER:
       Format: 'Plan: <descriptive name>'.
     validation:
       - "Non-empty string"
+  8:
+    id: PH8
+    field: id
+    type: string
+    required: false
+    description: >-
+      Stable plan identity assigned by the typed writer at first publication and
+      retained unchanged when the plan moves from active to archived history.
+      Legacy plans without this field derive a read-only identity.
+    validation:
+      - "Must match plan:<lowercase RFC 9562 UUID> when present"
 
 PLAN:
   1:
@@ -413,6 +424,13 @@ VALIDATION:
 LIFECYCLE_CONTRACT:
   authority: this schema
   canonical:
+    identity:
+      field: header.id
+      format: 'plan:<lowercase-rfc9562-uuid>'
+      assignment: The typed create writer assigns identity at first publication.
+      transition: Active and archived positions retain the identical identity.
+      legacy: Missing identity is derived deterministically at read time without rewriting bytes.
+      collision: Different documents with one identity are ambiguous and never selected by path or time.
     persisted_status:
       field: header.status
       values:
@@ -536,7 +554,8 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/cli/plan*.ts
       - packages/cli/src/cli/orientation.ts
       - packages/cli/src/cli/appContext.ts
-      - packages/cli/src/cli/commands/state/plan.ts
+      - packages/cli/src/cli/commands/state/plan*.ts
+      - packages/cli/src/state/plan*.ts
       - packages/cli/src/cli/commands/prime/*.ts
       - packages/cli/src/cli/capabilityContext/*.ts
       - packages/cli/src/cli/contracts/orientationState.ts
@@ -558,6 +577,8 @@ LIFECYCLE_CONTRACT:
     adapters:
       - references/**/*.yaml
       - packages/cli/src/registries/*.ts
+      - packages/cli/src/state/retrievalAuthority.ts
+      - packages/cli/src/state/projectionPolicy.ts
       - packages/cli/src/state/startupAnalysis/*.ts
       - packages/cli/src/cli/commands/schema.ts
       - packages/cli/src/cli/commands/validate.ts
@@ -582,6 +603,7 @@ LIFECYCLE_CONTRACT:
       - .agentera/**
     documented_external_commitments:
       - packages/cli/src/capabilities/*/instructions.ts
+      - packages/cli/README.md
       - skills/agentera/SKILL.md
       - skills/agentera/agents/*
       - skills/agentera/references/*

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

@@ -72,10 +72,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 +94,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"
     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:

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

@@ -127,3 +127,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.