agentera 3.0.0-dev.8 → 3.0.0-dev.81

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

@@ -1,54 +1,66 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
       Orchestrate consumes plan task queue state through
-      `agentera prime --context orchestrate --format json` before raw
-      artifact access, then updates status (pending -> complete/blocked) only
-      when resolving a task.
+      `npx -y agentera@next prime --context orchestrate --format json` before raw
+       artifact access, then updates status (pending -> complete/blocked) only
+       when resolving a task. Superseded tasks are terminal dependency
+       satisfiers and stay out of ready and blocked queues. Failed evaluator results are recorded through the
+      retry-safe typed `record-evaluation` mutation before retry or blocking.
   2:
     id: A2
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Orchestrate consumes progress verification state from the returned
-      orchestration context first, then routine CLI fallback output before any
-      last-resort raw artifact read for the Step 3 presence check.
+      orchestration context first, then bounded `npx -y agentera@next state progress list
+      --limit 20 --format json` fallback output. Exact detail uses `state
+      progress get --id ID`; raw reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   3:
     id: A3
-    artifact_id: health
-    local_role: consumes
+    artifact: health
+    local_role: produces_and_consumes
     description: >-
-      Orchestrate consumes returned health state first after plan completion to
-      decide whether to start a new plan cycle; raw reads are last-resort after
-      listed CLI fallbacks.
+      For an active plan whose tasks are all terminal, Orchestrate consumes
+      returned health state and delegates a limited staleness closure check.
+      On PASS it publishes one typed `artifact_freshness` health record through
+      `npx -y agentera@next state health append --input PATH --format json` before setting
+      the still-open plan complete. WARN or FAIL leaves the plan open and
+      surfaces the finding. Bounded `npx -y agentera@next state health list --limit 20
+      --format json` and exact `state health get --id ID` are fallback
+      contracts. Raw reads are diagnostic-only for corruption or CLI-defect
+      investigation.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces
     description: >-
       Orchestrate consumes TODO caveats from CLI startup context and writes
       blocked task logging only when a task exhausts its retry budget.
   5:
     id: A5
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Orchestrate consumes included decision context or the listed
-      `agentera decisions --format json` fallback before raw access, preserving
-      firm constraints, exploratory uncertainties, and compacted-entry caveats.
+      Orchestrate consumes included decision context or bounded
+      `npx -y agentera@next state decisions list --limit 20 --format json` discovery and
+      exact `state decisions get --id ID` retrieval, preserving firm
+      constraints, exploratory uncertainties, and compacted-entry caveats.
+      Raw reads are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Orchestrate consumes returned vision state or missing-state caveats during
       bootstrap when chaining research for vision-gap analysis.
   7:
     id: A7
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Orchestrate consumes returned profile status and caveats first for persona
@@ -56,9 +68,9 @@ ARTIFACTS:
       state and preserves the caveat.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Orchestrate uses docs mapping from CLI startup context first to resolve
-      project-local artifact mappings before any last-resort raw artifact read
-      or artifact write.
+      project-local artifact mappings before any diagnostic-only raw artifact
+      read or artifact write.

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

@@ -3,8 +3,9 @@ EXIT_CONDITIONS:
     id: E1
     condition: complete
     description: >-
-      All PLAN.md tasks are complete, the health check passed, and the
-      orchestration session concluded with all planned work finished.
+      All plan tasks are complete or validly superseded, the limited post-plan
+      health check passed, its typed health record was published, and the
+      still-open plan was then set complete without invoking archive.
     exit_signal: complete
   2:
     id: E2
@@ -18,7 +19,7 @@ EXIT_CONDITIONS:
     id: E3
     condition: stuck
     description: >-
-      Cannot proceed. PLAN.md has circular dependencies preventing any task
+      Cannot proceed. The plan has circular dependencies preventing any task
       from becoming eligible, no target capabilities are available to
       delegate, or file access prevents reading or updating artifacts.
       The exit marker explains what is blocking progress.
@@ -27,8 +28,9 @@ EXIT_CONDITIONS:
     id: E4
     condition: waiting
     description: >-
-      No PLAN.md exists and the bootstrap chain cannot proceed because
-      VISION.md is absent and the user has not confirmed how to create one,
-      or a dispatched capability returned waiting status requiring user input.
-      The waiting bullet identifies the specific decision needed.
+      No plan exists and the bootstrap chain cannot proceed because the
+      vision artifact is absent and the user has not confirmed how to
+      create one, or a dispatched capability returned waiting status
+      requiring user input. The waiting bullet identifies the specific
+      decision needed.
     exit_signal: waiting

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

@@ -1,55 +1,23 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests orchestrate.
+    description: Execute an entire plan or coordinate multiple tasks and capabilities.
     priority: high
-    patterns:
-      - "orchestrate"
-      - "/orchestrate"
-    confidence_threshold: 60
-    borderline_band: 10
-    patterns_regex:
-      - "\\b/orchestrate\\b"
   2:
     id: T2
-    description: >-
-      Multi-cycle execution signals. Matches when the user wants to execute
-      an entire plan autonomously or run tasks through evaluation gating.
-    priority: medium
-    patterns:
-      - "run the plan"
-      - "execute the plan"
-      - "run all tasks"
-      - "keep going until done"
-      - "run through the plan"
-      - "build everything"
-    confidence_threshold: 55
+    description: Run every task in a plan or execute a full plan autonomously.
+    priority: high
     disambiguates_against:
       - capability: build
         hint: "orchestrate runs the whole plan autonomously; build executes one development cycle"
   3:
     id: T3
-    description: >-
-      Orchestration and delegation signals. Matches when the user wants to
-      chain multiple capabilities, delegate work, or coordinate multi-step
-      execution.
+    description: Coordinate multiple tasks or capability handoffs through completion.
     priority: medium
-    patterns:
-      - "orchestrate"
-      - "orchestrate skills"
-      - "multi-cycle"
-    confidence_threshold: 50
   4:
     id: T4
-    description: >-
-      Autonomous plan execution signals. Matches when the user wants
-      evaluated, plan-driven development without manual intervention.
+    description: Run evaluated, plan-driven development across multiple tasks without manual sequencing.
     priority: medium
-    patterns:
-      - "autonomous plan execution"
-    confidence_threshold: 50
     disambiguates_against:
       - capability: build
         hint: "orchestrate chains multi-cycle execution; build runs a single cycle"

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

@@ -1,36 +1,36 @@
 VALIDATION:
   1:
     id: V1
-    rule: never_read_source
+    rule: must_not_read_source
     description: >-
-      Orchestrate MUST NEVER read implementation source code. It dispatches
-      capabilities; it does not implement. Artifact files (PLAN.md, HEALTH.md,
-      DECISIONS.md, PROGRESS.md, etc.) are not source code and are expected
-      to be read. This rule verifies the prose explicitly states the
-      source-code read prohibition.
+      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 prose (packages/cli/src/capabilities/orchestrate/instructions.ts) contains NEVER read implementation source code"
+      - "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 prose contains the never-skip-evaluation safety rail.
+      the instructions contain the must-not-skip-evaluation safety rail.
     severity: critical
     checks:
-      - "orchestrate prose contains NEVER skip evaluation"
+      - "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 prose and safety rails.
+      is stated in the instructions and safety rails.
     severity: critical
     checks:
-      - "orchestrate prose contains retry budget of 2"
+      - "orchestrate instructions contains retry a task more than 2 times"
   4:
     id: V4
     rule: exit_marker_required
@@ -40,45 +40,46 @@ VALIDATION:
       where status is one of EX1-EX4.
     severity: critical
     checks:
-      - "orchestrate prose contains exit marker with glyph ⎈ (SG12)"
-      - "orchestrate prose references exit signals EX1-EX4"
+      - "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 reads artifacts and updates PLAN.md task statuses and
-      TODO.md blocked entries. It does NOT write to PROGRESS.md, CHANGELOG.md,
-      or any other capability-owned artifact. This rule verifies the
-      artifacts schema reflects this constraint.
+      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.md is consumes only (not produces)"
-      - "HEALTH.md is consumes only (not produces)"
-      - "DECISIONS.md is consumes only (not produces)"
-      - "VISION.md is consumes only (not produces)"
+      - "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
+      `npx -y agentera@next prime --context orchestrate --format json` and the
       returned orchestration context before raw plan, progress, health, TODO,
       or decisions artifact reads.
     severity: critical
     checks:
-      - "orchestrate prose contains agentera prime --context orchestrate --format json"
-      - "orchestrate prose contains Use the returned `orchestration_context` before raw plan, progress, health, TODO, or decisions artifacts"
-      - "orchestrate prose contains If `source_contract.complete_for_orchestration_context` is true, do not read raw plan, progress, health, TODO, or decisions artifacts"
+      - "orchestrate instructions contains npx -y agentera@next 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
-      routine CLI fallback commands before any last-resort raw artifact read.
+      fallback commands before any raw artifact read.
     severity: critical
     checks:
-      - "orchestrate prose contains run the listed routine CLI fallback commands"
-      - "orchestrate prose contains Read a raw artifact only as a last-resort diagnostic"
+      - "orchestrate instructions contains run listed fallback commands"
+      - "orchestrate instructions contains last-resort diagnostics"
   8:
     id: V8
     rule: caveats_preserved_for_evaluation
@@ -88,9 +89,9 @@ VALIDATION:
       audit.
     severity: critical
     checks:
-      - "orchestrate prose contains compacted decision caveats"
-      - "orchestrate prose contains stale health/profile/app caveats"
-      - "orchestrate prose contains retry-state provenance"
+      - "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
@@ -107,14 +108,14 @@ VALIDATION:
       - "Missing or compacted satisfaction caveats are preserved"
   10:
     id: V10
-    rule: inspektera_citation_required
+    rule: audit_citation_required
     description: >-
       Orchestrate Step 3 Surface 2 audit delegation MUST require a
-      citation: <file>:<line> (or not-applicable: <reason>) for every WARN and
-      FAIL finding, and require verify_command for WARN rows with file:line
+      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 prose contains citation: `<file>:<line>` OR `not-applicable: <reason>`"
-      - "orchestrate prose contains verify_command"
-      - "orchestrate prose contains evaluator_handoff.output_requirements"
+      - "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

@@ -1,61 +1,65 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
-      Active plan with tasks, dependencies, and behavioral acceptance criteria.
-      Plan writes this during the planning session and may read existing
-      plan context before replacing or refining it.
+      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_id: plan_archive
+    artifact: plan_archive
     local_role: produces
     description: >-
-      Created when a plan is fully
-      executed or explicitly discarded by the user. Preserved for historical
-      reference.
+      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_id: vision
+    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_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Plan reads firm (DL1) entries only as hard constraints for planning.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: consumes
     description: >-
       Plan reads this to identify related known
       issues that the plan should address.
   6:
     id: A6
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Plan reads this to factor structural issues into the plan.
   7:
     id: A7
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Plan reads this to understand what was built recently.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
-      Plan reads this to calibrate planning depth and pattern preferences.
+      Plan reads only sanitized non-glossary content from `npx -y agentera@next report
+      profile-grounding --format json` to calibrate planning depth and pattern
+      preferences. It never direct-reads the profile path and uses content only
+      for shared validity `valid`; absent and repair-needed results fail closed.
   9:
     id: A9
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Plan reads this first to resolve project-local artifact mappings and

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

@@ -1,46 +1,23 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests plan for structured planning.
+    description: Requests to structure work into a plan before implementation.
     priority: high
-    patterns:
-      - "plan"
-      - "/plan"
-    confidence_threshold: 60
-    borderline_band: 10
-    patterns_regex:
-      - "\\b/plan\\b"
   2:
     id: T2
-    description: >-
-      Planning requests. Matches when the user wants to create a plan,
-      break work down, or specify requirements before building.
-    priority: medium
-    patterns:
-      - "plan this"
-      - "write a plan"
-      - "break this down"
-      - "decompose this"
-      - "spec this out"
-      - "plan before building"
-    confidence_threshold: 50
+    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: >-
-      Architectural planning signals. Matches when the user is asking how
-      to approach building something or when the work is too large for a
-      single development cycle.
+    description: Plan a multi-step feature or approach too large for one development cycle.
     priority: medium
-    patterns:
-      - "how should we build this"
-      - "multi-step feature"
-      - "this is too big for one cycle"
-    confidence_threshold: 50
     disambiguates_against:
       - capability: build
         hint: "plan sizes work before implementation; build runs the development cycle"

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

@@ -12,13 +12,14 @@ VALIDATION:
       - "No implementation details in acceptance criteria"
   2:
     id: V2
-    rule: max_8_tasks
+    rule: coherent_lifecycle_scope
     description: >-
-      Full plans MUST NOT exceed 8 tasks. If work requires more, it must
-      be split into sequential plans.
+      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:
-      - "Task count ≤ 8 in full plans"
+      - "Tasks stay within one coherent lifecycle boundary"
+      - "Splits follow real lifecycle or coherence boundaries"
   3:
     id: V3
     rule: adversarial_review_required
@@ -54,8 +55,67 @@ VALIDATION:
     rule: skip_level_for_trivial_work
     description: >-
       Plan MUST detect skip level for trivial work (single-file change,
-      bug fix, config tweak, < 50 lines) and route directly to /build
-      without producing a PLAN.md.
+      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"
+  9:
+    id: V9
+    rule: sanitized_profile_grounding
+    description: >-
+      Plan MUST ground only from the `content` returned by `npx -y agentera@next report
+      profile-grounding --format json` when shared validity is valid; it MUST
+      preserve absent/repair-needed recovery and MUST NOT direct-read PROFILE.md.
+    severity: critical
+    checks:
+      - "Sanitized grounding command used during Orient"
+      - "Prime and report validity objects agree before content use"
+      - "Raw profile path not read"
+  10:
+    id: V10
+    rule: governed_terminology_advice
+    description: >-
+      Plan MUST consume terminology advice through the shared glossary consumer
+      authority at governed meaning-sensitive user events. Interactive review
+      MUST precede fixing affected requirements. Autonomous unresolved review
+      MUST abstain, defer the affected requirements, and emit at most one bounded
+      current writer intent without delivering or storing it or writing plan
+      conflict or progress state.
+    severity: critical
+    checks:
+      - "Advice refreshes only for authority-declared Plan events"
+      - "Mode follows explicit authority precedence and unknown mode waits"
+      - "Interactive review precedes affected requirements and acceptance"
+      - "Autonomous unresolved meaning remains deferred without a Plan write"
+      - "Emitted-only handoff intent contains exactly event=current, reason, and ownership state"
+      - "Writer owns caveat identity, Build capability, and transition fields"
+      - "Exact project authority suppresses personal-unavailable durable handoff"
+      - "Plan artifacts exclude private glossary content"

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

@@ -1,15 +1,24 @@
 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. Profile writes this in both Full
-      and Validate modes, then reads it for validation and update context.
+      classification, and temporal metadata. After writing the base profile,
+      Profile Full consumes one existing consent-bound user-local personal
+       glossary generation. Only complete current coverage reaches bounded
+       classification and current explicit CLI decisions can replace its
+       deterministic owned Glossary section; inferred or ambiguous candidates
+       use the bounded review lifecycle. Unavailable, stale, or degraded coverage
+       preserves the base and owned section and requires explicit refresh. Lookup remains deferred. Profile writes
+      this in both Full and Validate modes, then reads it for validation and
+      update context. Prime exposes its canonical resolved path only inside
+      `prime --context profile`; no other Prime context or profile-grounding
+      failure may serialize that path.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Profile treats this as a high-signal source for extraction scripts.

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

@@ -4,8 +4,11 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       PROFILE.md was written (Full mode) or updated (Validate mode).
-      Metadata changes were applied, prediction accuracy was assessed
-      (Full mode), and changes were summarized.
+      In Full mode the base profile was written first, then any existing personal
+      glossary generation produced only current authorized explicit publication;
+      remaining review work was queued or bounded for a question channel.
+      Metadata changes were applied, prediction accuracy was assessed, and
+      changes were summarized.
     exit_signal: complete
   2:
     id: E2
@@ -15,15 +18,15 @@ EXIT_CONDITIONS:
       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.
+      found. Full mode is also flagged when its existing consent-bound personal
+      glossary generation is unavailable, stale, degraded, or review-only.
     exit_signal: flagged
   3:
     id: E3
     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