agentera 3.0.0-dev.3 → 3.0.0-dev.30

package/bundle/skills/agentera/capabilities/orchestrate/schemas/validation.yaml

@@ -0,0 +1,121 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: must_not_read_source
+    description: >-
+      Orchestrate MUST NOT read implementation source code. It dispatches
+      capabilities; it does not implement. Artifact files (`.agentera/*.yaml`,
+      `TODO.md`) are state records, not source code; raw reads are last-resort
+      after CLI context and listed fallback commands. This rule verifies the
+      instructions explicitly state the source-code read prohibition.
+    severity: critical
+    checks:
+      - "orchestrate instructions (packages/cli/src/capabilities/orchestrate/instructions.ts) contains MUST NOT read implementation source code"
+  2:
+    id: V2
+    rule: evaluation_gate_required
+    description: >-
+      Every completed task MUST be verified by audit before being marked
+      complete. The orchestrator MUST NOT skip evaluation. This rule verifies
+      the instructions contain the must-not-skip-evaluation safety rail.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains MUST NOT skip evaluation"
+  3:
+    id: V3
+    rule: retry_budget_enforced
+    description: >-
+      No task may be retried more than 2 times. After the second failure,
+      the task must be marked blocked. This rule verifies the retry budget
+      is stated in the instructions and safety rails.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains retry a task more than 2 times"
+  4:
+    id: V4
+    rule: exit_marker_required
+    description: >-
+      Every orchestrate invocation MUST emit an exit marker. The marker uses
+      the canonical glyph ⎈ (SG12) in the format ⎈ orchestrate · <status>
+      where status is one of EX1-EX4.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains exit marker with glyph ⎈ (SG12)"
+      - "orchestrate instructions references exit signals EX1-EX4"
+  5:
+    id: V5
+    rule: orchestrator_read_only_artifacts
+    description: >-
+      The orchestrator updates plan task statuses and TODO.md blocked entries.
+      During terminal-open closure only, it writes the typed limited-scope
+      health record before plan completion. It does NOT write progress or
+      changelog. This rule verifies the artifacts schema reflects this
+      constraint.
+    severity: warning
+    checks:
+      - "progress is consumes only (not produces)"
+      - "health is produces_and_consumes for terminal-open closure only"
+      - "decisions is consumes only (not produces)"
+      - "vision is consumes only (not produces)"
+  6:
+    id: V6
+    rule: orchestration_context_first
+    description: >-
+      Orchestrate startup and evaluation MUST use
+      `agentera prime --context orchestrate --format json` and the
+      returned orchestration context before raw plan, progress, health, TODO,
+      or decisions artifact reads.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains agentera prime --context orchestrate --format json"
+      - "orchestrate instructions contains complete_for_orchestration_context"
+      - "orchestrate instructions contains no raw plan, progress, health, TODO, or decisions reads"
+  7:
+    id: V7
+    rule: cli_fallback_before_raw_read
+    description: >-
+      When orchestration context is incomplete, Orchestrate MUST run listed
+      fallback commands before any raw artifact read.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains run listed fallback commands"
+      - "orchestrate instructions contains last-resort diagnostics"
+  8:
+    id: V8
+    rule: caveats_preserved_for_evaluation
+    description: >-
+      Orchestrate MUST preserve compacted-decision, stale health/profile/app,
+      missing-state, and retry-state provenance caveats when handing a task to
+      audit.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains compacted decision caveats"
+      - "orchestrate instructions contains stale health/profile/app caveats"
+      - "orchestrate instructions contains retry-state provenance"
+  9:
+    id: V9
+    rule: satisfaction_authority_boundary
+    description: >-
+      When Orchestrate touches decision satisfaction, it may pass through or request
+      provisional satisfaction with evidence but MUST NOT user-confirm satisfaction.
+      Missing, compacted, open, provisional, or review-needed satisfaction state
+      remains a caveat and review pressure; automation must not reconstruct hidden
+      outcomes or claim it proved user intent.
+    severity: critical
+    checks:
+      - "Provisional satisfaction requires evidence"
+      - "Only the user confirms final satisfaction"
+      - "Missing or compacted satisfaction caveats are preserved"
+  10:
+    id: V10
+    rule: audit_citation_required
+    description: >-
+      Orchestrate Step 3 Surface 2 audit delegation MUST require a
+      citation: <file>:<line> (or not-applicable: <reason>) for every FAIL
+      finding, and require verify_command for FAIL rows with file:line
+      citations. Authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains citation: `<file>:<line>` OR `not-applicable: <reason>`"
+      - "orchestrate instructions contains verify_command"
+      - "orchestrate instructions contains evaluator_handoff.output_requirements"

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

@@ -0,0 +1,63 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact: plan
+    local_role: produces_and_consumes
+    description: >-
+      Current plan with tasks, dependencies, and behavioral acceptance criteria.
+      Its active position is derived from the docs-mapped current-plan path,
+      not persisted lifecycle status. Plan writes this during the planning
+      session and may read existing plan context before replacing or refining it.
+  2:
+    id: A2
+    artifact: plan_archive
+    local_role: produces
+    description: >-
+      Immutable, non-executable history created when a plan is complete or
+      explicitly force-archived. Forced archival preserves an unfinished
+      plan's open status rather than claiming completion.
+  3:
+    id: A3
+    artifact: vision
+    local_role: consumes
+    description: >-
+      Plan reads this during Orient to understand project direction and
+      align the plan with the vision.
+  4:
+    id: A4
+    artifact: decisions
+    local_role: consumes
+    description: >-
+      Plan reads firm (DL1) entries only as hard constraints for planning.
+  5:
+    id: A5
+    artifact: todo
+    local_role: consumes
+    description: >-
+      Plan reads this to identify related known
+      issues that the plan should address.
+  6:
+    id: A6
+    artifact: health
+    local_role: consumes
+    description: >-
+      Plan reads this to factor structural issues into the plan.
+  7:
+    id: A7
+    artifact: progress
+    local_role: consumes
+    description: >-
+      Plan reads this to understand what was built recently.
+  8:
+    id: A8
+    artifact: profile
+    local_role: consumes
+    description: >-
+      Plan reads this to calibrate planning depth and pattern preferences.
+  9:
+    id: A9
+    artifact: docs
+    local_role: consumes
+    description: >-
+      Plan reads this first to resolve project-local artifact mappings and
+      reads the versioning block for version bump task generation.

package/bundle/skills/agentera/capabilities/{planera → plan}/schemas/exit.yaml

@@ -4,8 +4,8 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       PLAN.md was written and approved (or skip level confirmed), the
-      adversarial review ran for full plans, and the handoff to realisera
-      or orkestrera was suggested.
+      adversarial review ran for full plans, and the handoff to build
+      or orchestrate was suggested.
     exit_signal: complete
   2:
     id: E2

package/bundle/skills/agentera/capabilities/plan/schemas/triggers.yaml

@@ -0,0 +1,23 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: Requests to structure work into a plan before implementation.
+    priority: high
+  2:
+    id: T2
+    description: Create a plan, break work down, or specify requirements before building.
+    priority: high
+    disambiguates_against:
+      - capability: build
+        hint: "plan structures work into tasks before coding; build implements the work"
+      - capability: discuss
+        hint: "plan structures committed work; discuss explores an undecided choice or tradeoff"
+      - capability: vision
+        hint: "plan structures work toward known direction; vision defines the direction itself"
+  3:
+    id: T3
+    description: Plan a multi-step feature or approach too large for one development cycle.
+    priority: medium
+    disambiguates_against:
+      - capability: build
+        hint: "plan sizes work before implementation; build runs the development cycle"

package/bundle/skills/agentera/capabilities/plan/schemas/validation.yaml

@@ -0,0 +1,89 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: behavioral_acceptance_criteria
+    description: >-
+      All acceptance criteria MUST be behavioral (Given/When/Then format)
+      and MUST NOT reference implementation details (class names, API
+      endpoints, database tables, function names, line numbers).
+    severity: critical
+    checks:
+      - "Acceptance criteria use Given/When/Then format"
+      - "No implementation details in acceptance criteria"
+  2:
+    id: V2
+    rule: coherent_lifecycle_scope
+    description: >-
+      Full plans MUST keep all tasks within a coherent lifecycle boundary.
+      Split plans only when work crosses a real lifecycle or coherence boundary.
+    severity: critical
+    checks:
+      - "Tasks stay within one coherent lifecycle boundary"
+      - "Splits follow real lifecycle or coherence boundaries"
+  3:
+    id: V3
+    rule: adversarial_review_required
+    description: >-
+      Full plans MUST undergo adversarial review. The critic MUST find at
+      least one issue. "Looks good" is not acceptable. Skip level and
+      light plans are exempt.
+    severity: critical
+    checks:
+      - "Adversarial review ran for full plans"
+  4:
+    id: V4
+    rule: plan_final_state_sync
+    description: >-
+      Every full plan MUST end with a "final state sync" task that depends
+      on all prior tasks. This ensures aggregate plan-level CHANGELOG.md,
+      PROGRESS.md, and TODO.md updates.
+    severity: critical
+    checks:
+      - "Full plan has final state sync task as last task"
+  5:
+    id: V5
+    rule: test_proportionality_target
+    description: >-
+      Tasks that include writing tests MUST have a proportionality target
+      in their acceptance criteria. Default: one pass + one fail per
+      testable unit. Override only with explicit rationale.
+    severity: warning
+    checks:
+      - "Test tasks state proportionality target"
+  6:
+    id: V6
+    rule: skip_level_for_trivial_work
+    description: >-
+      Plan MUST detect skip level for trivial work (single-file change,
+      localized defect fix, or config tweak that touches no shared
+      abstraction) and route directly to /build without producing a
+      PLAN.md. LOC count is not a skip signal because small changes to
+      shared exports can ripple across many consumers.
+    severity: critical
+    checks:
+      - "Trivial work routed to /build without plan"
+  7:
+    id: V7
+    rule: full_plan_unknowns_required
+    description: >-
+      Every full plan MUST surface at least one planning-time known-unknown
+      in the `unknowns:` field. Each entry MUST include question,
+      affects_task, and resolve_by. Skip level and light plans are exempt
+      because they do not decompose work into interdependent tasks.
+    severity: warning
+    checks:
+      - "Full plans have a non-empty `unknowns:` list"
+      - "Each unknown entry has question, affects_task, resolve_by fields"
+  8:
+    id: V8
+    rule: adversarial_review_dismissals_persisted
+    description: >-
+      Full plans MUST persist dismissed adversarial-review findings in the
+      artifact's `rejected:` field, each with issue text and rationale, so
+      downstream consumers (build, orchestrate, audit) inherit the
+      adjudication rather than relitigating. V3 enforces the review ran;
+      V8 enforces the dismissal provenance persists.
+    severity: warning
+    checks:
+      - "Full plans with dismissed critic findings have `rejected:` entries"
+      - "Each rejection has issue and rationale fields"

package/bundle/skills/agentera/capabilities/{profilera → profile}/schemas/artifacts.yaml

@@ -1,18 +1,18 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: profile
+    artifact: profile
     local_role: produces_and_consumes
     description: >-
       Decision profile with per-entry confidence scoring, permanence
-      classification, and temporal metadata. Profilera writes this in both Full
+      classification, and temporal metadata. Profile writes this in both Full
       and Validate modes, then reads it for validation and update context.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Profilera treats this as a high-signal source for extraction scripts.
+      Profile treats this as a high-signal source for extraction scripts.
       Each decision entry captures
       reasoning, tradeoffs, and confidence, making deliberation sessions
       one of the richest inputs for decision profile generation.

package/bundle/skills/agentera/capabilities/{profilera → profile}/schemas/exit.yaml

@@ -12,7 +12,8 @@ EXIT_CONDITIONS:
     condition: flagged
     description: >-
       Profile generation or validation completed but with data quality
-      issues: extraction failed for one or more sources, prediction
+      issues: available runtime history was skipped without explicit
+      acceptance, extraction failed for one or more sources, prediction
       accuracy was below 3/5, or significant unresolved tensions were
       found.
     exit_signal: flagged
@@ -21,8 +22,7 @@ EXIT_CONDITIONS:
     condition: stuck
     description: >-
       Cannot generate or validate a profile because extraction scripts
-      failed entirely, Python is unavailable, or session data sources
-      are unreadable.
+      failed entirely or session data sources are unreadable.
     exit_signal: stuck
   4:
     id: E4

package/bundle/skills/agentera/capabilities/profile/schemas/triggers.yaml

@@ -0,0 +1,20 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: Create, maintain, or analyze a reusable decision profile.
+    priority: high
+  2:
+    id: T2
+    description: Build, generate, or regenerate a decision profile.
+    priority: high
+    disambiguates_against:
+      - capability: build
+        hint: "profile builds a reusable decision profile; build implements a software task"
+  3:
+    id: T3
+    description: Update, validate, or refresh an existing decision profile.
+    priority: medium
+  4:
+    id: T4
+    description: Analyze personal decision patterns or review decision history.
+    priority: medium

package/bundle/skills/agentera/capabilities/profile/schemas/validation.yaml

@@ -0,0 +1,85 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: evidence_grounded
+    description: >-
+      Every profile entry MUST be grounded in observed evidence from session
+      history, memory files, configs, or conversation data. Fabricated
+      decision patterns are never acceptable. Synthesis reads the bounded
+      signal tier; a claim's source identity is verified by resolving its
+      evidence_anchor to a retained full-evidence shard rather than re-scanning
+      unbounded history.
+    severity: critical
+    checks:
+      - "Each profile entry traces to a source record"
+      - "No profile entry is fabricated without evidence"
+      - "Each claim's evidence_anchor resolves to a retained full-evidence shard"
+  2:
+    id: V2
+    rule: confidence_calibration
+    description: >-
+      Confidence scores MUST match the evidence tier (protocol CS1-CS5).
+      A single data point is 30-49 (CS4), not 70+. Bias check: confidence
+      is earned through evidence, not assigned by how insightful the
+      decision sounds. When bounded_signals.sufficiency is insufficient,
+      affected categories are capped to CS4 (30-49) or below.
+    severity: critical
+    checks:
+      - "Confidence values fall within protocol tier boundaries"
+      - "Single-source entries are capped at CS4 (30-49)"
+      - "Insufficient families cap affected categories to CS4 or below"
+  3:
+    id: V3
+    rule: tension_honesty
+    description: >-
+      Contradictions MUST be recorded as tensions, not smoothed into a
+      coherent narrative. When evidence conflicts, the tension section
+      captures the divergence explicitly.
+    severity: critical
+    checks:
+      - "Conflicting evidence produces tension entries"
+      - "No smoothing over contradictions"
+  4:
+    id: V4
+    rule: read_only_sources
+    description: >-
+      Profile MUST NOT modify session history, memory files, or config
+      files. It reads these sources for extraction but never writes to them.
+      The only artifact profile produces is PROFILE.md. Profile MUST NOT
+      load the monolithic corpus.json whole: synthesis reads the bounded
+      signal tier and retrieves full evidence one shard at a time via
+      evidence_anchor. Legacy/missing tiers require a refresh to publish
+      bounded tiers first, never a whole-corpus load.
+    severity: critical
+    checks:
+      - "No writes to session history files"
+      - "No writes to memory or config files"
+      - "Monolithic corpus.json is never loaded whole"
+      - "Full-evidence records are retrieved one shard at a time"
+  5:
+    id: V5
+    rule: prediction_accuracy
+    description: >-
+      Full mode MUST validate predictions against 5 decision-rich prompts
+      not used to create the profile. Accuracy below 3/5 triggers a flag
+      noting categories needing more signal.
+    severity: warning
+    checks:
+      - "5 predictions tested against held-out prompts"
+      - "Accuracy below 3/5 is flagged in profile header"
+  6:
+    id: V6
+    rule: bounded_signal_sufficiency
+    description: >-
+      Profile synthesis MUST consume the bounded signal tier published by
+      extraction, not all full evidence. The sufficiency gate reports
+      underrepresented source families with their retained and intended
+      counts and surfaces the limitation in the profile output and exit
+      signal rather than silently reducing confidence. Sufficiency is
+      assessed per family against the contract minimum_family_retention
+      threshold; a family with zero intended signals is not a violation.
+    severity: warning
+    checks:
+      - "Signal tier state, count, and sufficiency are read before synthesizing"
+      - "Underrepresented families are surfaced with retained and intended counts"
+      - "No high-confidence claims are fabricated from sparse or missing evidence"

package/bundle/skills/agentera/capabilities/research/schemas/artifacts.yaml

@@ -0,0 +1,24 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact: todo
+    local_role: produces
+    description: >-
+      Open problems by severity. Research writes actionable findings here
+      (with user confirmation), classifying each by severity per protocol
+      SF1-SF3. Build picks up changes automatically in its next cycle.
+  2:
+    id: A2
+    artifact: vision
+    local_role: produces
+    description: >-
+      Research may refine project direction with user confirmation when the
+      analysis shifts thinking about the project's direction.
+  3:
+    id: A3
+    artifact: profile
+    local_role: consumes
+    description: >-
+      Research reads the profile via research_context.profile from the prime
+      context to weight applicability judgments. If missing, research proceeds
+      without persona grounding.

package/bundle/skills/agentera/capabilities/research/schemas/triggers.yaml

@@ -0,0 +1,16 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: Research requests that analyze external sources, repositories, or approaches.
+    priority: high
+  2:
+    id: T2
+    description: Assess an external source's relevance, applicability, or adoption.
+    priority: high
+  3:
+    id: T3
+    description: Review an external library, repository, or pattern for ideas.
+    priority: high
+    disambiguates_against:
+      - capability: audit
+        hint: "research reviews external resources for ideas; audit reviews the local codebase for health"

package/bundle/skills/agentera/capabilities/{inspirera → research}/schemas/validation.yaml

@@ -3,8 +3,8 @@ VALIDATION:
     id: V1
     rule: read_only_target
     description: >-
-      Inspirera MUST NOT modify code in the target project. It analyzes
-      and maps concepts; other capabilities (realisera, optimera)
+      Research MUST NOT modify code in the target project. It analyzes
+      and maps concepts; other capabilities (build, optimize)
       implement changes. The only writes are to TODO.md and VISION.md,
       and only with explicit user confirmation.
     severity: critical

package/bundle/skills/agentera/capabilities/status/schemas/artifacts.yaml

@@ -0,0 +1,72 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact: vision
+    local_role: consumes
+    description: >-
+      Status reads this for the briefing's project context.
+  2:
+    id: A2
+    artifact: decisions
+    local_role: consumes
+    description: >-
+      Status reads this to identify unresolved decisions requiring follow-up.
+  3:
+    id: A3
+    artifact: plan
+    local_role: consumes
+    description: >-
+      Status reads this to identify the next executable task and plan progress.
+  4:
+    id: A4
+    artifact: progress
+    local_role: consumes
+    description: >-
+      Status reads this for the briefing's "what shipped" context.
+  5:
+    id: A5
+    artifact: todo
+    local_role: consumes
+    description: >-
+      Status reads this to identify high-severity open items for routing.
+  6:
+    id: A6
+    artifact: health
+    local_role: consumes
+    description: >-
+      Status reads this for the health status line and attention items.
+  7:
+    id: A7
+    artifact: objective
+    local_role: consumes
+    description: >-
+      Status reads this to check for active optimization objectives.
+  8:
+    id: A8
+    artifact: experiments
+    local_role: consumes
+    description: >-
+      Status reads this alongside the active optimization target to determine
+      optimization status.
+  9:
+    id: A9
+    artifact: docs
+    local_role: consumes
+    description: >-
+      Status reads this first to resolve project-local artifact mappings before
+      reading other artifacts.
+  10:
+    id: A10
+    artifact: design
+    local_role: consumes
+    description: >-
+      Status reads this for project design status metadata (exists, stale, missing).
+      Suite chrome styling uses protocol.yaml, prime --context capability prose,
+      and v2 app-home DESIGN.md when present — not the host project's design
+      artifact.
+  11:
+    id: A11
+    artifact: profile
+    local_role: consumes
+    description: >-
+      Status reads this to report profile status (loaded/not found) in the briefing.

package/bundle/skills/agentera/capabilities/status/schemas/triggers.yaml

@@ -0,0 +1,22 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: Explicit status requests and orientation for the current project.
+    priority: high
+  2:
+    id: T2
+    description: Session-start requests seeking orientation before choosing work.
+    priority: high
+  3:
+    id: T3
+    description: Current project state, briefing, attention, or progress requests.
+    priority: medium
+  4:
+    id: T4
+    description: Resume-work and “what's next?” requests with no separate requested outcome.
+    priority: high
+  5:
+    id: T5
+    description: Fallback orientation when no capability fits the request.
+    fallback: true
+    priority: low

package/bundle/skills/agentera/capabilities/{hej → status}/schemas/validation.yaml

@@ -3,8 +3,8 @@ VALIDATION:
     id: V1
     rule: read_only
     description: >-
-      Hej MUST NOT produce or modify any artifacts. It is strictly read-only.
-      All artifacts consumed by hej are produced by other capabilities.
+      Status MUST NOT produce or modify any artifacts. It is strictly read-only.
+      All artifacts consumed by status are produced by other capabilities.
       This rule verifies that no artifact entry has produces: true.
     severity: critical
     checks:
@@ -25,9 +25,9 @@ VALIDATION:
     id: V3
     rule: exit_marker_required
     description: >-
-      Every hej invocation MUST emit an exit marker after the briefing or
+      Every status invocation MUST emit an exit marker after the briefing or
       welcome. The marker uses the canonical glyph ⌂ (SG1) in the format
-      ⌂ hej · <status> where status is one of EX1-EX4.
+      ⌂ status · <status> where status is one of EX1-EX4.
     severity: critical
     checks:
       - "Exit marker present after closing code fence"
@@ -48,7 +48,7 @@ VALIDATION:
     id: V5
     rule: single_clarifying_question
     description: >-
-      If the routing target is unclear, hej MUST ask exactly one clarifying
+      If the routing target is unclear, status MUST ask exactly one clarifying
       question. Compound questions are not allowed.
     severity: critical
     checks: