agentera 3.0.0-dev.2 → 3.0.0-dev.20

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

@@ -1,6 +1,6 @@
 # Changelog Artifact Schema
 #
-# Release history maintained by realisera. Tracks versioned releases with
+# Release history maintained by build. Tracks versioned releases with
 # categorized changes (Added, Changed, Fixed, Removed).
 #
 # Note: CHANGELOG.md is a human-facing Markdown artifact. It remains at the
@@ -11,12 +11,12 @@ meta:
   name: changelog
   version: "1.0.0"
   description: >-
-    Release history. Produced by realisera. Consumed by users and agents
+    Release history. Produced by build. Consumed by users and agents
     for version context. Human-facing: remains Markdown at project root.
   artifact_type: human_facing
   path: "CHANGELOG.md"
-  producer: realisera
-  consumers: [hej, all_skills]
+  producer: build
+  consumers: [status, all_skills]
   format: markdown
 
 GROUP_PREFIXES:

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

@@ -1,7 +1,7 @@
 # Decisions Artifact Schema
 #
-# Reasoning trail maintained by resonera. Each deliberation session appends
-# one entry. Decisions are referenced by realisera, optimera, and profilera
+# Reasoning trail maintained by discuss. Each deliberation session appends
+# one entry. Decisions are referenced by build, optimize, and profile
 # for context on why choices were made.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
@@ -32,14 +32,14 @@ meta:
   name: decisions
   version: "1.0.0"
   description: >-
-    Reasoning trail maintained by resonera. Each deliberation session
-    appends one entry. Decisions are referenced by realisera, optimera,
-    profilera, planera, inspektera, hej, dokumentera, visionera, resonera,
-    and orkestrera for context on why choices were made.
+    Reasoning trail maintained by discuss. Each deliberation session
+    appends one entry. Decisions are referenced by build, optimize,
+    profile, plan, audit, status, document, vision, discuss,
+    and orchestrate for context on why choices were made.
   artifact_type: agent_facing
   path: ".agentera/decisions.yaml"
-  producer: resonera
-  consumers: [dokumentera, hej, inspektera, optimera, orkestrera, planera, profilera, realisera, resonera, visionera]
+  producer: discuss
+  consumers: [document, status, audit, optimize, orchestrate, plan, profile, build, discuss, vision]
   format: yaml
 
 GROUP_PREFIXES:
@@ -55,7 +55,7 @@ BUDGET:
   1:
     id: DB1
     scope: per_decision_entry
-    max_words: 200
+    max_words: 1000
     description: >-
       Maximum words per decision entry. Budgets are guidelines, not hard
       blockers.
@@ -103,7 +103,7 @@ COMPACTION:
       Decisions older than 50 are dropped entirely.
   5:
     id: DX5
-    trigger: "When resonera writes a new decision"
+    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.

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

@@ -1,6 +1,6 @@
 # Design Artifact Schema
 #
-# Visual identity system maintained by visualisera. Defines design tokens,
+# Visual identity system maintained by design. Defines design tokens,
 # palette, typography, spacing, and component styling rules.
 #
 # Note: DESIGN.md is a human-facing Markdown artifact. It remains at the
@@ -11,12 +11,12 @@ meta:
   name: design
   version: "1.0.0"
   description: >-
-    Visual identity system. Produced by visualisera. Consumed by capabilities
+    Visual identity system. Produced by design. Consumed by capabilities
     that need visual identity context. Human-facing: remains Markdown at root.
   artifact_type: human_facing
   path: "DESIGN.md"
-  producer: visualisera
-  consumers: [dokumentera, hej, inspektera, realisera, visionera, visualisera]
+  producer: design
+  consumers: [document, status, audit, build, vision, design]
   format: markdown
 
 GROUP_PREFIXES:

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

@@ -1,6 +1,6 @@
 # Docs Artifact Schema
 #
-# Documentation contract maintained by dokumentera. Tracks project doc
+# Documentation contract maintained by document. Tracks project doc
 # conventions, artifact path overrides, document index with status, coverage
 # metrics, and timestamped audit findings.
 #
@@ -47,11 +47,11 @@ meta:
   name: docs
   version: "1.0.0"
   description: >-
-    Documentation contract. Produced by dokumentera. Consumed by all skills
+    Documentation contract. Produced by document. Consumed by all skills
     for artifact path resolution and doc status tracking.
   artifact_type: agent_facing
   path: ".agentera/docs.yaml"
-  producer: dokumentera
+  producer: document
   consumers: [all_skills]
   format: yaml
 
@@ -123,7 +123,7 @@ CONVENTIONS:
     required: true
     description: >-
       Files whose content changes indicate a version bump is needed.
-      Tracked by planera, inspektera, and realisera for bump discipline.
+      Tracked by plan, audit, and build for bump discipline.
     validation:
       - "At least one entry required"
   5:
@@ -177,8 +177,9 @@ MAPPING:
     required: true
     description: >-
       File path for this artifact. May be absolute or relative.
-      Environment variable references (e.g., $PROFILERA_PROFILE_DIR)
-      are resolved at read time.
+      Environment variable references (e.g., $AGENTERA_PROFILE_DIR or
+      the deprecated $PROFILERA_PROFILE_DIR alias) are resolved at read
+      time with AGENTERA_PROFILE_DIR taking precedence.
     validation:
       - "Non-empty string"
   4:
@@ -288,7 +289,7 @@ AUDIT_LOG:
     type: map
     required: false
     description: >-
-      Each audit log entry. Timestamped findings from dokumentera audits.
+      Each audit log entry. Timestamped findings from document audits.
       Appended when an audit is performed.
   2:
     id: DA2

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

@@ -1,6 +1,6 @@
 # Experiments Artifact Schema
 #
-# Experiment log maintained by optimera. Each experiment records hypothesis,
+# 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>/.
 #
@@ -40,12 +40,12 @@ meta:
   name: experiments
   version: "1.0.0"
   description: >-
-    Experiment log for optimera objectives. Produced and consumed by optimera.
+    Experiment log for optimize objectives. Produced and consumed by optimize.
     Lives in .agentera/optimera/<name>/ alongside the objective.
   artifact_type: agent_facing
   path: ".agentera/optimera/<name>/experiments.yaml"
-  producer: optimera
-  consumers: [hej, optimera]
+  producer: optimize
+  consumers: [status, optimize]
   format: yaml
 
 GROUP_PREFIXES:
@@ -108,7 +108,7 @@ COMPACTION:
       Experiments older than 50 are dropped entirely.
   5:
     id: EX_CMP5
-    trigger: "When optimera writes a new experiment"
+    trigger: "When optimize writes a new experiment"
     description: >-
       Compaction runs when the producing skill writes a new entry.
       If >10 full-detail entries exist, collapse the oldest to one-line.

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

@@ -1,6 +1,6 @@
 # Health Artifact Schema
 #
-# Audit log maintained by inspektera. Each audit entry records assessed
+# Audit log maintained by audit. Each audit entry records assessed
 # dimensions, findings (critical/warning/info counts), overall trajectory,
 # per-dimension grades (A-F), per-dimension findings with confidence, and
 # trend analysis against the prior audit.
@@ -49,12 +49,12 @@ meta:
   name: health
   version: "1.0.0"
   description: >-
-    Audit log maintained by inspektera. Consumed by capabilities that need
+    Audit log maintained by audit. Consumed by capabilities that need
     codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
-  producer: inspektera
-  consumers: [dokumentera, hej, inspektera, orkestrera, planera, realisera, visionera]
+  producer: audit
+  consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
 GROUP_PREFIXES:
@@ -119,7 +119,7 @@ COMPACTION:
       Audits older than 50 are dropped entirely.
   5:
     id: HX5
-    trigger: "When inspektera writes a new audit"
+    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.

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

@@ -1,6 +1,6 @@
 # Objective Artifact Schema
 #
-# Optimization objective maintained by optimera. Each objective lives in its
+# Optimization objective maintained by optimize. Each objective lives in its
 # own subdirectory under .agentera/optimera/<name>/ and captures the metric,
 # target, baseline, constraints, measurement method, gates, and scope.
 #
@@ -47,12 +47,12 @@ meta:
   name: objective
   version: "1.0.0"
   description: >-
-    Optimization objective. Produced by optimera and resonera. Each objective
+    Optimization objective. Produced by optimize and discuss. Each objective
     lives in its own subdirectory under .agentera/optimera/<name>/.
   artifact_type: agent_facing
   path: ".agentera/optimera/<name>/objective.yaml"
-  producer: [optimera, resonera]
-  consumers: [hej, optimera, resonera]
+  producer: [optimize, discuss]
+  consumers: [status, optimize, discuss]
   format: yaml
 
 GROUP_PREFIXES:

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,7 +138,7 @@ 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"
@@ -191,7 +195,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 +205,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 +338,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 +369,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 +409,186 @@ VALIDATION:
     checks:
       - "Per-task word count <= 100"
       - "Total file word count <= 2500"
+
+LIFECYCLE_CONTRACT:
+  authority: this schema
+  canonical:
+    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/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/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
+      - skills/agentera/SKILL.md
+      - skills/agentera/agents/*
+      - skills/agentera/references/*
+      - references/**/*.md
+      - docs/**
+      - packages/web/src/**
+      - "*.md"
+      - AGENTS.md
+      - README.md
+      - UPGRADE.md