agentera 3.0.0-dev.2 → 3.0.0-dev.21

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

@@ -1,6 +1,6 @@
 # Plan Artifact Schema
 #
-# Active work plan maintained by planera. 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.
 #
@@ -13,7 +13,7 @@
 # ─────────────────────────────────────────────────────────────────────
 # <!-- 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
@@ -32,6 +32,8 @@
 # **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)
@@ -41,12 +43,12 @@ meta:
   name: plan
   version: "1.0.0"
   description: >-
-    Active work plan. Produced by planera and updated by plan executors.
+    Active work plan. Produced by plan and updated by plan executors.
     Consumed by capabilities that inspect or execute plan state.
   artifact_type: agent_facing
   path: ".agentera/plan.yaml"
-  producer: [orkestrera, planera, realisera]
-  consumers: [hej, inspektera, orkestrera, planera, realisera]
+  producer: [orchestrate, plan, build]
+  consumers: [status, audit, orchestrate, plan, build]
   format: yaml
 
 GROUP_PREFIXES:
@@ -55,6 +57,8 @@ GROUP_PREFIXES:
   PLAN: PL
   SCOPE: PS
   TASK: PT
+  UNKNOWN: PU
+  REJECTED: PR
   VALIDATION: PV
 
 BUDGET:
@@ -99,10 +103,10 @@ HEADER:
     type: string
     required: true
     description: >-
-      Plan lifecycle status. Active plans are being executed; complete
-      plans are candidates for archival.
+      Canonical plan lifecycle. Positional activity is derived from the
+      plan's location and is not persisted.
     validation:
-      - "Must be one of: active, complete"
+      - "Must be one of: open, complete"
   4:
     id: PH4
     field: reviewed
@@ -134,10 +138,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: >-
+      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:
@@ -191,7 +206,7 @@ PLAN:
     required: false
     description: >-
       Runtime surprises discovered during plan execution. Populated
-      by realisera when reality diverges from plan. Default: empty.
+      by build when reality diverges from plan. Default: empty.
   7:
     id: PL22
     field: previous_plan_archived
@@ -201,6 +216,62 @@ PLAN:
       Path to the previous active plan archived when this plan was created.
       Preserves plan lineage without changing lifecycle status.
 
+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:
     id: PS11
@@ -278,6 +349,15 @@ 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 `agentera state plan
+      record-evaluation`. It records attempt and failure counts, the latest
+      verdict, retained failure evidence, and stable attempt provenance.
 
 VALIDATION:
   1:
@@ -300,7 +380,7 @@ VALIDATION:
     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' or 'complete'"
       - "title is present and non-empty"
       - "what is present and non-empty"
       - "why is present and non-empty"
@@ -340,3 +420,197 @@ VALIDATION:
     checks:
       - "Per-task word count <= 100"
       - "Total file word count <= 2500"
+
+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:
+        - open
+        - complete
+      meaning:
+        open: Work is unfinished, whether the plan is current or archived.
+        complete: Every task is complete.
+    position:
+      active: The plan occupies the docs-mapped current-plan path.
+      archived: The plan occupies the sibling archive directory.
+      persisted: false
+    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.
+    forced_archive:
+      unfinished_status: open
+      effect: Move the plan to immutable history without claiming completion.
+  compatibility:
+    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: Canonical writers and migrators must emit only open or complete.
+      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
+          - .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_id: 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/**]
+          reason: Tool caches 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/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/state/plan*.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/startupCompletenessContract.ts
+      - packages/cli/src/hooks/sessionStart.ts
+      - packages/cli/src/eval/evalSkills.ts
+    writers:
+      - packages/cli/src/state/write/*.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
+    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
+      - skills/agentera/SKILL.md
+      - skills/agentera/agents/*
+      - skills/agentera/references/*
+      - references/**/*.md
+      - docs/**
+      - packages/web/src/**
+      - "*.md"
+      - AGENTS.md
+      - README.md
+      - UPGRADE.md

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

@@ -1,7 +1,7 @@
 # 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,
@@ -16,12 +16,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,12 +36,12 @@ 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]
+  producer: build
+  consumers: [document, status, audit, optimize, orchestrate, plan, build, vision, design]
   format: yaml
 
 GROUP_PREFIXES:
@@ -73,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:
@@ -95,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 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 +177,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 +279,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