agentera 3.0.0-dev.7 → 3.0.0-dev.72

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

@@ -1,19 +1,26 @@
 # Plan Artifact Schema
 #
-# Active work plan maintained by plan. Each plan captures what will be built,
+# Current work plan maintained by plan. Each plan captures what will be built,
 # why, constraints, scope boundaries, design approach, tasks with dependencies
 # and acceptance criteria, overall acceptance, and surprises.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority uses one plan or plan_task entity per writer-owned file.
+# The aggregate model below is the complete atomic plan-create input. Its task
+# numbers and numeric/string dependency references are create-local symbols,
+# not persisted identities. Fields explicitly labeled migration-only remain
+# compatibility input and are not ordinary post-cutover entity contracts.
 #
-# ── Field-by-field mapping: v1 PLAN.md → v2 plan.yaml ──
+# ── Legacy migration-input mapping: v1 PLAN.md → v2 plan.yaml ──
+#
+# The ordinal task fields in this mapping are create-local symbolic references.
+# They are valid only inside one atomic `state plan create --input` document and
+# are removed when the writer publishes plan and plan_task entities.
 #
 # v1 Field                              v2 Field               v2 ID
 # ─────────────────────────────────────────────────────────────────────
 # <!-- Level: light/full -->            HEADER.level           PL1
 # <!-- Created: date -->                HEADER.created         PL2
-# <!-- Status: active/completed -->     HEADER.status          PL3
+# <!-- Status: active/completed -->     HEADER.status          PL3 (normalized)
 # <!-- Reviewed: date -->               HEADER.reviewed        PL4
 # <!-- Critic issues: N found... -->    HEADER.critic_issues   PL5
 # <!-- Revised: description -->         HEADER.revised         PL6
@@ -25,13 +32,15 @@
 # ## Scope / **Out**: <list>            SCOPE.excluded         PL12
 # ## Scope / **Deferred**: <list>       SCOPE.deferred         PL13
 # ## Design                             PLAN.design            PL14
-# ### Task N: <name>                    TASK.number            PL15
+# ### Task N: <name>                    TASK.number            PL15 (create-local only)
 # (task name from heading)              TASK.name              PL16
 # **Depends on**: <text>                TASK.depends_on        PL17
 # **Status**: <status>                  TASK.status            PL18
 # **Acceptance**: <criteria list>       TASK.acceptance        PL19
 # ## Overall Acceptance                 PLAN.overall_acceptance PL20
 # ## Surprises                          PLAN.surprises         PL21
+# ## Unknowns                           UNKNOWN.entry          PU1
+# ## Rejected Review Findings           REJECTED.entry         PR1
 #
 # Protocol references:
 #   status visual tokens: VT1-VT4 (protocol.yaml VISUAL_TOKENS)
@@ -45,16 +54,60 @@ meta:
     Consumed by capabilities that inspect or execute plan state.
   artifact_type: agent_facing
   path: ".agentera/plan.yaml"
+  authority: legacy_migration_input_only
   producer: [orchestrate, plan, build]
   consumers: [status, audit, orchestrate, plan, build]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: plan
+  boundaries: [plan, plan_task]
+  relationship: plan_task.record.plan is a bare plan ID
+  retrieval:
+    list: npx -y agentera@next state plan list --format json
+    get: npx -y agentera@next state plan get --id ID --format json
+    tasks_list: npx -y agentera@next state plan tasks list [PLAN_ID] --format json
+    task_get: npx -y agentera@next state plan tasks get --id ID --format json
+  mutation: npx -y agentera@next state plan explain --format json
+  direct_file_edits: forbidden
+  aggregate_schema_below: atomic_create_input
+  migration_compatibility: explicitly_labeled_fields_only
+
+CANONICAL_ENTITY_CONTRACT:
+  authority: typed_state_writer
+  envelope_identity:
+    plan:
+      field: id
+      format: bare_ten_letter_id
+      selector: --id ID
+      assignment: writer_assigned_on_create
+    plan_task:
+      field: id
+      format: bare_ten_letter_id
+      selector: --id ID
+      assignment: writer_assigned_on_append
+  create_local_symbols:
+    scope: one_atomic_plan_create_input
+    task_field: number
+    dependency_accepted_forms: [positive_integer, canonical_numeric_string]
+    dependency_normalization: canonical_numeric_string_before_resolution
+    publication: remove_number_and_resolve_dependencies_to_bare_entity_ids
+  migration_compatibility:
+    header_id:
+      format: composite_plan_identity
+      status: migration_only_noncanonical
+      public_selector: forbidden
+    legacy_task_references: convert_to_bare_entity_ids_during_migration
+
 GROUP_PREFIXES:
   BUDGET: PB
   HEADER: PH
   PLAN: PL
   SCOPE: PS
   TASK: PT
+  UNKNOWN: PU
+  REJECTED: PR
   VALIDATION: PV
 
 BUDGET:
@@ -99,10 +152,11 @@ HEADER:
     type: string
     required: true
     description: >-
-      Plan lifecycle status. Active plans are being executed; complete
-      plans are candidates for archival.
+      Canonical plan lifecycle. Open plans are active candidates, complete
+       plans satisfy every task through completion or valid supersession, and
+       archived plans are historical or abandoned.
     validation:
-      - "Must be one of: active, complete"
+      - "Must be one of: open, complete, archived"
   4:
     id: PH4
     field: reviewed
@@ -134,10 +188,21 @@ HEADER:
     type: string
     required: true
     description: >-
-      Short plan title. Used in archive naming and plan listing.
+      Short plan title. Used in archive naming and active/archived plan listing.
       Format: 'Plan: <descriptive name>'.
     validation:
       - "Non-empty string"
+  8:
+    id: PH8
+    field: id
+    type: string
+    required: false
+    description: >-
+      Migration-only source identity. Canonical plan identity is the bare
+      ten-letter envelope `id` assigned by the typed writer; this source
+      `header.id` is never a public selector.
+    validation:
+      - "Composite header.id is accepted only by legacy migration compatibility"
 
 PLAN:
   1:
@@ -195,11 +260,78 @@ PLAN:
   7:
     id: PL22
     field: previous_plan_archived
-    type: string
+    type: bare_ten_letter_id
+    required: false
+    description: >-
+      Writer-owned bare ID of the predecessor archived when this successor was
+       created. The predecessor's archived lifecycle and this successor reference
+       provide bidirectional lineage without changing task, evaluation, or
+       completion history.
+  8:
+    id: PL23
+    field: replacement_input_sha256
+    type: lowercase_sha256_hex
     required: false
     description: >-
-      Path to the previous active plan archived when this plan was created.
-      Preserves plan lineage without changing lifecycle status.
+      Writer-owned immutable logical identity for a targeted replacement
+      successor. It excludes mutable task lifecycle and evaluation fields, so an
+      exact replacement input can replay after task execution changes.
+
+UNKNOWN:
+  1:
+    id: PU1
+    field: entry
+    type: map
+    required: true
+    description: >-
+      A planning-time question that can change whether downstream work remains
+      necessary as written. Full plans require at least one entry.
+    min_count: 1
+  2:
+    id: PU2
+    field: question
+    parent: UNKNOWN.entry
+    type: string
+    required: true
+    description: "The unresolved planning-time question."
+  3:
+    id: PU3
+    field: affects_task
+    parent: UNKNOWN.entry
+    type: integer
+    required: true
+    description: "The task number whose scope depends on the answer."
+  4:
+    id: PU4
+    field: resolve_by
+    parent: UNKNOWN.entry
+    type: string
+    required: true
+    description: "How the affected task will resolve the question."
+
+REJECTED:
+  1:
+    id: PR1
+    field: entry
+    type: map
+    required: true
+    description: >-
+      A dismissed adversarial-review finding preserved with its rationale.
+    min_count: 1
+  2:
+    id: PR2
+    field: issue
+    parent: REJECTED.entry
+    type: string
+    required: true
+    description: "The critic finding that was dismissed."
+  3:
+    id: PR3
+    field: rationale
+    parent: REJECTED.entry
+    type: string
+    required: true
+    description: "Why the finding was dismissed rather than addressed."
 
 SCOPE:
   1:
@@ -236,11 +368,12 @@ TASK:
     type: integer
     required: true
     description: >-
-      Task number within the plan. Sequential, starting from 1.
-      May include a descriptive name (e.g., 'Task 2: Shared Protocol').
+      Create-local symbolic task ordinal within one atomic plan input.
+      Sequential values start at 1, are removed on publication, and are never
+      a canonical entity identity or public selector.
     validation:
-      - "Must be a positive integer"
-      - "Must be unique within the plan"
+      - "Must be a positive integer in the create input"
+      - "Must be unique within that atomic input"
   2:
     id: PT16
     field: name
@@ -254,11 +387,24 @@ TASK:
   3:
     id: PT17
     field: depends_on
-    type: list[string]
+    path: tasks[].depends_on
+    type: list[integer|string]
+    write_operations: [create]
+    accepted_forms:
+      atomic_plan_create: [positive_integer, canonical_numeric_string]
+      legacy_migration_only: [legacy_task_reference_string]
+    normalization: canonical_numeric_string_before_same_document_resolution
     required: false
     description: >-
-      Task dependencies. References task numbers or names that must
-      complete before this task can start. Empty for root tasks.
+      Numeric or numeric-string dependency references are create-local symbolic
+      task ordinals only inside the current complete plan create input. The writer
+      resolves them within that atomic document, removes the ordinal references,
+      and publishes dependencies as bare ten-letter task envelope IDs. Empty for
+      root tasks.
+    validation:
+      - positive_integer_or_canonical_numeric_string
+      - unique_after_normalization_within_task
+      - resolves_to_declared_task_ordinal_in_same_atomic_document
   4:
     id: PT18
     field: status
@@ -268,7 +414,7 @@ TASK:
       Task execution status. Uses visual tokens from protocol.yaml
       VISUAL_TOKENS (VT1-VT4) for display.
     validation:
-      - "Must be one of: complete, in_progress, pending, blocked"
+      - "Must be one of: complete, in_progress, pending, blocked, superseded"
   5:
     id: PT19
     field: acceptance
@@ -278,29 +424,61 @@ TASK:
       Acceptance criteria for this task. Each entry is a GIVEN/WHEN/THEN
       statement that must hold for the task to be considered complete.
       Required for full-level plans.
+  6:
+    id: PT20
+    field: evaluation
+    type: mapping
+    required: false
+    description: >-
+      CLI-owned evaluator state written only by `npx -y agentera@next state plan
+      record-evaluation`. It records attempt and failure counts, the latest
+      verdict, retained failure evidence, and stable attempt provenance. Normal
+      workflow records evaluation before completion. As recovery for persisted
+      out-of-order replacement state only, the writer accepts the first PASS on
+      an unevaluated complete task while its open same-plan superseded predecessor
+      names it in superseded_by; every other terminal evaluation remains rejected.
+  7:
+    id: PT21
+    field: superseded_by
+    type: list[string]
+    required: false
+    description: >-
+      CLI-owned replacement task IDs from the same plan. Prospective supersession
+      requires every replacement to be complete with evaluation.last_verdict pass.
+      Required only when status is superseded; IDs must be distinct.
+  8:
+    id: PT22
+    field: superseded_reason
+    type: string
+    required: false
+    description: >-
+      CLI-owned required explanation, at most 500 characters, for a superseded
+      task. Present only with superseded_by when status is superseded.
 
 VALIDATION:
   1:
     id: PV1
-    rule: unique_task_numbers
+    rule: unique_entity_ids
     severity: error
     description: >-
-      Task numbers must be unique within a plan and sequential.
+      Create-local task ordinals must be unique within one atomic plan input and
+      sequential; they are not persisted entity identities.
     checks:
-      - "All task numbers are unique"
-      - "Task numbers are sequential starting from 1"
+      - "All create-local task ordinals are unique"
+      - "Create-local task ordinals are sequential starting from 1"
   2:
     id: PV2
     rule: required_fields
     severity: error
     description: >-
-      The plan must have: level, created, status, title, what, why,
-      scope.included, scope.excluded, and at least one task. Each task
-      must have number, name, and status.
+      A complete create input must have: level, created, status, title, what,
+      why, scope.included, scope.excluded, and at least one task. Each task's
+      number is create-local and is removed before identity conversion. Legacy
+      source documents use the separate migration compatibility contract.
     checks:
       - "level is present and is 'light' or 'full'"
       - "created is present and matches YYYY-MM-DD"
-      - "status is present and is 'active' or 'completed'"
+      - "status is present and is 'open', 'complete', or 'archived'"
       - "title is present and non-empty"
       - "what is present and non-empty"
       - "why is present and non-empty"
@@ -325,10 +503,14 @@ VALIDATION:
     rule: dependency_references
     severity: error
     description: >-
-      Task depends_on references must point to valid task numbers
-      within the same plan.
+      Create-local depends_on references must point to valid task ordinals in
+      the same atomic input before conversion to bare task IDs. Legacy source
+      references use the migration compatibility path, not this public writer
+      vocabulary.
     checks:
-      - "Each dependency references an existing task number"
+      - "Each create-local dependency is a positive integer or canonical numeric string"
+      - "Each normalized dependency references an existing task ordinal"
+      - "Each task's normalized dependency ordinals are unique"
       - "No circular dependency chains"
   5:
     id: PV5
@@ -340,3 +522,246 @@ VALIDATION:
     checks:
       - "Per-task word count <= 100"
       - "Total file word count <= 2500"
+
+LIFECYCLE_CONTRACT:
+  authority: this schema
+  canonical:
+    identity:
+      field: id
+      format: bare_ten_letter_id
+      assignment: The typed entity writer assigns the envelope identity at first publication.
+      transition: Active and archived entity positions retain the identical bare identity.
+      legacy: Legacy source header.id is migration-only and never a public selector.
+      collision: Different canonical entities with one identity are ambiguous and never selected by path or time.
+    migration_source_identity:
+      field: header.id
+      format: 'plan:<lowercase-rfc9562-uuid> or legacy-plan:<sha256>'
+      status: migration_only_noncanonical
+      assignment: Read-only compatibility derivation or retained legacy source value.
+      public_selector: forbidden
+    persisted_status:
+      field: header.status
+      values:
+        - open
+        - complete
+        - archived
+      meaning:
+        open: Work is active and unfinished.
+        complete: Every task is complete or validly superseded.
+        archived: Historical or abandoned source; tasks may be incomplete or empty.
+    position:
+      active: A unique open entity plan supplies the default active selection.
+      archived: Archived lifecycle marks historical or abandoned entity plans; legacy archives occupy the sibling archive directory.
+      persisted: true
+    execution:
+      eligible: Only a plan at the current-plan path can supply executable work.
+      archived: An archived plan is historical and non-executable regardless of status.
+    lineage:
+      field: previous_plan_archived
+      representation: bare predecessor plan entity ID
+      publication: The writer assigns the field only while atomically archiving a predecessor and publishing its successor.
+      reverse: A predecessor's successor is derived from the unique canonical plan record that names its ID in previous_plan_archived; no second mutable lineage field exists.
+      replacement_input_identity:
+        field: replacement_input_sha256
+        representation: lowercase SHA-256 of the normalized logical replacement input
+        ownership: Writer-owned at targeted replacement publication and immutable afterward.
+        exclusions: [task.status, task.evaluation, task.superseded_by, task.superseded_reason]
+    forced_archive:
+      unfinished_status: archived
+      effect: Change the plan lifecycle to archived without claiming completion or changing tasks, evaluations, or completion history.
+    forced_create:
+      no_open_predecessor: Publish the successor normally.
+      one_open_predecessor: --force archives the predecessor unchanged and publishes the successor with previous_plan_archived set to the predecessor bare ID.
+      multiple_open_predecessors: Reject before effects because implicit creation cannot choose a predecessor.
+    targeted_replacement:
+      command: state plan replace --predecessor PREDECESSOR (--successor SUCCESSOR | --input PLAN.yaml)
+      existing_successor: Names both bare plan IDs, archives only the named predecessor, and assigns previous_plan_archived on the named open successor.
+      create_successor: Names the bare predecessor and supplies one complete plan document when no successor exists.
+      selection: Reject before effects if an unnamed open plan would remain, roles are invalid, or the requested successor conflicts with canonical lineage.
+      diagnostics: Competing-open readers and implicit writers expose bounded bare candidate IDs and the state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID recovery grammar. Canonical state never infers predecessor or successor roles from list order.
+      replay: The archived predecessor and unique derived successor identify an existing-successor replay; create retries compare the exact input identity retained on the successor rather than mutable task state.
+      atomicity: The complete predecessor, successor, and created-task target set is durable under the private entity recovery authority before any target is visible. Pending journals block plan reads until the exact retry finishes or restores the operation.
+    replacement_evidence_transition:
+      predicate: A replacement is complete and its latest persisted evaluation.last_verdict is pass.
+      supersession: Every superseded_by replacement must satisfy the predicate before a new supersession is published.
+      completion: Every replacement named by a superseded task must satisfy the predicate before an open plan becomes complete.
+      replay: Exact supersession and plan-completion replays remain idempotent no-ops.
+  compatibility:
+    historical_replacement_evidence:
+      readable: Existing superseded records without replacement PASS evidence remain readable and are not rewritten or invalidated.
+      closeout: An affected open plan cannot become complete until every replacement satisfies the current predicate.
+      recovery: An unevaluated complete replacement named by an open same-plan superseded predecessor may persist its first PASS, then closeout can retry.
+      scope: The first-PASS exception repairs already-persisted out-of-order state only; it does not permit new supersession without PASS evidence.
+    legacy_read_window:
+      scope: >-
+        Read normalization and typed-writer canonicalization of plan-level
+        active to open and completed to complete for artifacts produced by
+        pre-canonical Agentera versions at the docs-mapped current-plan path
+        or its sibling archive directory.
+      writers: Ordinary create and status writers emit open or complete; only archive lifecycle and migration emit archived.
+      removal_condition: >-
+        Remove normalization only after the deterministic migration covers
+        current plans, archives, fixtures, and bundled upgrade inputs, and
+        regression tests prove no supported producer can emit a legacy value.
+      test_boundary:
+        - current plan with active normalizes to open and reports legacy input
+        - archived plan with active normalizes to open and remains non-executable
+        - completed normalizes to complete only at the plan-level compatibility seam
+        - canonical writers reject active and completed after migration support lands
+        - typed writes canonicalize a legacy current plan before publication
+    external_consumers:
+      evidence: >-
+        No shipped SDK, adapter, or package reads header.status directly;
+        supported consumers use the CLI plan discovery and state contracts.
+      commitment: No compatibility window is provided for direct YAML consumers.
+  inventory:
+    method: >-
+      Classification is pattern-based and enforced by a bounded repository
+      scan. Every file under scan.roots containing a discovery marker must
+      match at least one family pattern unless an explicit exclusion applies.
+    scan:
+      roots:
+        - .
+      symlinks: Excluded because their targets may leave the repository boundary.
+      excluded_directory_names:
+        names:
+          - .git
+          - node_modules
+          - .pnpm-store
+          - .venv
+          - .pytest_cache
+          - .ruff_cache
+          - .playwright-cli
+          - .agentera-generated
+          - .cache
+          - .snapshots
+          - __pycache__
+          - dist
+          - build
+          - coverage
+          - bundle
+          - .astro
+          - .svelte-kit
+          - .wrangler
+        reason: >-
+          Directory-name pruning prevents traversal of VCS metadata, vendor
+          dependencies, environments, caches, snapshots, bytecode, and generated
+          build or publication outputs at any repository depth.
+      markers:
+        - planDocumentParts
+        - discoverPlanArtifacts
+        - resolvePlanTaskEvidence
+        - header.status
+        - previous_plan_archived
+        - plan_archive
+        - state plan
+        - .agentera/plan.yaml
+        - plan.yaml
+        - state.plan.
+        - artifact: plan
+        - artifact: plan
+        - active plan
+        - archived plan
+        - plan lifecycle
+      exclusions:
+        - patterns: [.git, .git/**]
+          reason: Git object and worktree metadata is not a repository contract surface.
+        - patterns: [node_modules, node_modules/**, "**/node_modules", "**/node_modules/**"]
+          reason: Installed third-party dependencies are vendor content.
+        - patterns: [.pnpm-store, .pnpm-store/**, .venv, .venv/**]
+          reason: Package and Python environments are external dependency caches.
+        - patterns: [.pytest_cache, .pytest_cache/**, .ruff_cache, .ruff_cache/**, .playwright-cli, .playwright-cli/**]
+          reason: Tool caches and local browser sessions are generated and carry no product contract.
+        - patterns: ["**/.cache", "**/.cache/**", .snapshots, .snapshots/**]
+          reason: Caches and filesystem snapshots are generated or external state.
+        - patterns: ["**/dist", "**/dist/**", "**/build", "**/build/**", "**/coverage", "**/coverage/**"]
+          reason: Compiled, bundled, and coverage outputs are generated from classified sources.
+        - patterns: [packages/cli/.agentera-generated, packages/cli/.agentera-generated/**, packages/cli/bundle, packages/cli/bundle/**, "**/.astro", "**/.astro/**", "**/.svelte-kit", "**/.svelte-kit/**"]
+          reason: Runtime bundles and framework outputs are generated publication artifacts.
+        - patterns: [.wrangler, .wrangler/**, "**/.wrangler", "**/.wrangler/**", "*.tgz", "**/*.tgz"]
+          reason: Deployment outputs and package tarballs are generated publication artifacts.
+        - patterns: [.env, .env.*, "**/.env", "**/.env.*", "*.pem", "**/*.pem", "*.key", "**/*.key"]
+          reason: Local secret files are neither read nor classified by repository contract tests.
+        - patterns:
+            - references/adapters/runtime-lifecycle-*.yaml
+            - packages/cli/src/runtime/lifecycle*.ts
+            - packages/cli/src/upgrade/lifecycle*.ts
+            - packages/cli/test/runtime/lifecycle*.test.ts
+            - packages/cli/test/upgrade/lifecycle*.test.ts
+            - packages/cli/test/cli/lifecycle*.test.ts
+            - packages/cli/test/validate/lifecycle*.test.ts
+          reason: These surfaces govern runtime installation lifecycle, not plan artifact lifecycle.
+    readers:
+      - src/**
+      - hooks/**
+      - .opencode/plugins/**/*.js
+      - 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/prime.ts
+      - packages/cli/src/state/{plan*,entityListRuntimeRegistry}.ts
+      - packages/cli/src/state/durability.ts
+      - packages/cli/src/cli/commands/prime/*.ts
+      - packages/cli/src/cli/capabilityContext/*.ts
+      - packages/cli/src/cli/contracts/orientationState.ts
+      - packages/cli/src/cli/migrationRequired.ts
+      - packages/cli/src/cli/startupCompletenessContract.ts
+      - packages/cli/src/hooks/sessionStart.ts
+      - packages/cli/src/eval/evalSkills.ts
+      - packages/cli/src/state/stateMode.ts
+    writers:
+      - packages/cli/src/state/write/*.ts
+      - packages/cli/src/state/entityStorage.ts
+      - packages/cli/src/state/entityPublicationContext.ts
+      - packages/cli/src/cli/commands/state/write.ts
+    migrators:
+      - packages/cli/src/upgrade/migrateArtifacts*.ts
+      - packages/cli/src/upgrade/upgradeOrchestrator.ts
+      - packages/cli/src/upgrade/doctor.ts
+      - packages/cli/src/cli/commands/prime/v1Migration.ts
+      - packages/cli/src/state/entityMigration*.ts
+      - packages/cli/src/state/canonicalMigrationRecord.ts
+    schemas:
+      - skills/agentera/schemas/artifacts/*.yaml
+      - skills/agentera/capabilities/*/schemas/*.yaml
+      - skills/agentera/capability_schema_contract.yaml
+    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
+      - packages/cli/src/cli/help.ts
+      - packages/cli/src/cli/prime-blob.ts
+      - packages/cli/src/hooks/validateArtifact/*.ts
+      - packages/cli/src/validate/selfAudit.ts
+      - packages/cli/src/hooks/compaction/*.ts
+      - packages/cli/src/cli/dispatch/*.ts
+      - .agentera/docs.yaml
+      - scripts/**
+    fixtures:
+      - packages/cli/test/**/*.ts
+      - packages/cli/test/**/*.md
+      - packages/cli/test/fixtures/**
+      - packages/cli/test/fixtures/**/.agentera/*
+      - packages/cli/test/upgrade/fixtures/**
+      - packages/cli/test/upgrade/fixtures/**/.agentera/*
+      - packages/cli/test/cli/fixtures/**
+      - tests/**
+      - fixtures/**
+      - .agentera/**
+    documented_external_commitments:
+      - packages/cli/src/capabilities/*/instructions.ts
+      - packages/cli/README.md
+      - .opencode/skills/*/SKILL.md
+      - skills/agentera/SKILL.md
+      - skills/agentera/references/*
+      - references/**/*.md
+      - docs/**
+      - "*.md"
+      - AGENTS.md
+      - README.md
+      - UPGRADE.md