agentera 3.0.0-dev.7 → 3.0.0-dev.74

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

@@ -1,54 +1,20 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests discuss for structured deliberation.
+    description: Structured deliberation about a choice, decision, or tradeoff.
     priority: high
-    patterns:
-      - "discuss"
-      - "/discuss"
-    confidence_threshold: 60
-    borderline_band: 10
   2:
     id: T2
-    description: >-
-      Decision-oriented requests. Matches when the user wants help thinking
-      through a decision or evaluating tradeoffs.
-    priority: medium
-    patterns:
-      - "deliberate"
-      - "help me think through"
-      - "help me decide"
-      - "think this through with me"
-      - "let's deliberate"
-      - "what are the tradeoffs"
-      - "brainstorm"
-      - "rubber duck"
-    confidence_threshold: 50
+    description: Help decide, think through alternatives, or evaluate tradeoffs.
+    priority: high
   3:
     id: T3
-    description: >-
-      Option-comparison signals. Matches when the user is torn between
-      choices or wants to evaluate competing approaches.
-    priority: medium
-    patterns:
-      - "should I"
-      - "I'm torn between"
-      - "what's the right approach"
-      - "let's reason about"
-    confidence_threshold: 50
+    description: Compare competing options before committing to an approach.
+    priority: high
   4:
     id: T4
-    description: >-
-      Pre-build scoping signals. Matches when the user wants to scope or
-      reason about work before starting implementation.
+    description: Explore uncertain scope or approach before committing to implementation.
     priority: medium
-    patterns:
-      - "scope this out"
-      - "before I build this"
-      - "talk me through"
-    confidence_threshold: 50
     disambiguates_against:
       - capability: plan
         hint: "discuss explores options before committing; plan structures committed work"

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

@@ -13,16 +13,17 @@ VALIDATION:
     id: V2
     rule: user_approval_for_artifact_writes
     description: >-
-      Discuss MUST NOT modify VISION.md, OBJECTIVE.md, or TODO.md without
-      explicit user confirmation. Present drafts and get approval.
+      Discuss MUST NOT modify vision, objective, or todo artifacts (the
+      protected_write_boundaries) without explicit user confirmation. Present
+      drafts and get approval.
     severity: critical
     checks:
-      - "User confirmation obtained before writing to VISION.md, OBJECTIVE.md, or TODO.md"
+      - "User confirmation obtained before writing to vision, objective, or todo artifacts"
   3:
     id: V3
     rule: decision_confidence_required
     description: >-
-      Every DECISIONS.md entry MUST have a Confidence field with one of the
+      Every decision entry MUST have a Confidence field with one of the
       protocol-defined labels: firm (DL1), provisional (DL2), or
       exploratory (DL3).
     severity: critical
@@ -33,7 +34,7 @@ VALIDATION:
     id: V4
     rule: preserved_decision_fields
     description: >-
-      DECISIONS.md entries MUST preserve the canonical top-level fields:
+      Decision entries MUST preserve the canonical top-level fields:
       Question, Context, Alternatives, Choice, Reasoning, Confidence,
       Feeds into. Win conditions stay inside Alternatives bullets.
     severity: critical
@@ -75,3 +76,69 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  8:
+    id: V8
+    rule: sanitized_profile_grounding
+    description: >-
+      Discuss 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 at session start"
+      - "Prime and report validity objects agree before content use"
+      - "Raw profile path not read"
+  9:
+    id: V9
+    rule: governed_glossary_advice_events
+    description: >-
+      Discuss MUST invoke `npx -y agentera@next report glossary-advice --input <file|->
+      --format json` for initial meaning-sensitive user input and later
+      user-authored premise changes or affected clarification answers that can
+      change meaning. It MUST NOT invoke advice for unchanged replay, rendering,
+      unrelated turns, tool output, background rereads, or Done-only control,
+      and MUST NOT use an unbounded or persistent transcript scan.
+    severity: critical
+    checks:
+      - "Initial and changed meaning-sensitive user events refresh advice"
+      - "Incidental, unchanged, and Done-only events do not refresh advice"
+      - "Only current user-authored meaning-sensitive input is inspected"
+  10:
+    id: V10
+    rule: glossary_review_before_reliance
+    description: >-
+      When advice requires inferred-equivalence review, Discuss MUST ask one
+      focused clarification with Done before meaning-sensitive reasoning or
+      decision framing relies on either meaning. It MUST NOT silently infer
+      equivalence, and the clarification MUST NOT count as decision confirmation.
+    severity: critical
+    checks:
+      - "Focused review question precedes reliance"
+      - "One-question-per-turn and Done behavior are preserved"
+      - "Clarification is not decision confirmation"
+  11:
+    id: V11
+    rule: glossary_authority_and_disclosure
+    description: >-
+      Discuss MUST use only the transient applicable meaning and owner. Project
+      meaning governs a divergent exact collision and the divergence appears as
+      a concise scratchpad tension or Crux; Discuss MUST NOT ask the user to
+      choose project versus personal authority or quote unrelated entries.
+    severity: critical
+    checks:
+      - "Applicable project or proven personal fallback meaning is used"
+      - "Divergence appears as tension or Crux without an authority-choice question"
+      - "Unrelated glossary content is not disclosed"
+  12:
+    id: V12
+    rule: glossary_consumer_mutation_isolation
+    description: >-
+      Advice, divergence, and consumer clarification are transient. Discuss MUST
+      NOT write glossary, approval, publication consent, progress caveat, plan
+      conflict, or decision conflict state, and MUST NOT call glossary publish.
+      Unavailable or no-applicable advice adds no glossary facts.
+    severity: critical
+    checks:
+      - "No glossary or consumer-caveat mutation occurs"
+      - "No approval, consent, or conflict bookkeeping occurs"
+      - "Unavailable advice does not fabricate glossary grounding"

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

@@ -1,71 +1,78 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: docs
+    artifact: docs
     local_role: produces_and_consumes
     description: >-
       Documentation contract with conventions, artifact mapping, and
       documentation index. Document writes and reads doc root, style
       conventions, auto-generated doc tracking, project-local artifact mappings,
       and a status index (current/stale/missing) for tracked docs. During
-      closeout, Document consumes docs state through CLI `closeout_context`
-      before raw artifact fallback.
+      closeout, Document consumes docs state through CLI `closeout_context`;
+      raw reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Document reads this to understand who the documentation is for
       and what tone to use.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode to understand
       recent project context. During closeout, latest progress evidence and
-      verification pointers are consumed through CLI `closeout_context` before
-      raw artifact fallback.
+      verification pointers are consumed through CLI `closeout_context`, then
+      bounded `npx -y agentera@next state progress list --limit 20 --format json` discovery
+       or exact `state progress get --id ID` retrieval. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   4:
     id: A4
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode for project
-      context and decision awareness.
+      context and decision awareness through bounded `npx -y agentera@next state decisions
+      list --limit 20 --format json` discovery or exact `state decisions get
+       --id ID` retrieval. Raw reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   5:
     id: A5
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
-      Document reads this to discover documentation gaps surfaced
-      during health audits.
+      Document reads this to discover documentation gaps surfaced during health
+      audits through bounded `npx -y agentera@next state health list --limit 20 --format
+       json` discovery or exact `state health get --id ID` retrieval. Raw reads
+      are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Document writes to this when code diverges from docs (per DTC,
       the code is wrong). Also reads for context during documentation work;
       closeout blocker state is consumed through CLI `closeout_context` before
-      raw artifact fallback.
+      any diagnostic-only raw TODO read.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Document reads this to respect the declared aesthetic and voice
       when generating user-facing documentation.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Document reads this to calibrate documentation style preferences:
       detail level, tone, format.
   9:
     id: A9
-    artifact_id: changelog
+    artifact: changelog
     local_role: consumes
     description: >-
       Document reads this during closeout synchronization through CLI

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

@@ -1,46 +1,16 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests document.
+    description: Create, maintain, or assess project documentation.
     priority: high
-    patterns:
-      - "document"
-      - "/document"
-    confidence_threshold: 60
-    borderline_band: 10
-    patterns_regex:
-      - "\\b/document\\b"
   2:
     id: T2
-    description: >-
-      Documentation creation requests. Matches when the user wants to
-      write or create documentation, including DTC-first workflows.
-    priority: medium
-    patterns:
-      - "write docs"
-      - "document this"
-      - "create README"
-      - "write CLAUDE.md"
-      - "write AGENTS.md"
-      - "docs first"
-      - "document before building"
-    confidence_threshold: 50
+    description: Write or create project documentation, including README and agent guidance.
+    priority: high
   3:
     id: T3
-    description: >-
-      Documentation maintenance and audit requests. Matches when the user
-      wants to update, check, or verify existing documentation.
-    priority: medium
-    patterns:
-      - "update the docs"
-      - "audit docs"
-      - "check documentation"
-      - "docs out of sync"
-    confidence_threshold: 50
+    description: Update, verify, or audit documentation, including “audit the docs”.
+    priority: high
     disambiguates_against:
       - capability: audit
         hint: "document maintains project docs; audit reviews codebase health"
-    patterns_regex:
-      - "\\baudit\\s+docs?\\b"

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

@@ -85,12 +85,13 @@ VALIDATION:
     id: V9
     rule: closeout_context_first
     description: >-
-      During final synchronization, Document MUST use `agentera prime
-      --context document --format json` and its `closeout_context`
-      before reading TODO, docs, changelog, or progress artifacts directly.
-      Complete closeout context is the normal source for mappings, version
-      policy, blockers, boundaries, progress evidence, benchmark evidence,
-      caveats, fallback commands, raw-read policy, and completeness.
+       During final synchronization, Document MUST use `npx -y agentera@next prime
+       --context document --format json` and its `closeout_context`
+       before using bounded state list/get contracts for TODO, docs, changelog,
+       or progress. Raw artifact access is diagnostic-only or a write target.
+        Complete closeout context is the normal source for mappings, version
+        policy, blockers, boundaries, progress evidence, benchmark evidence,
+        caveats, fallback commands, raw-read policy, and completeness.
     severity: critical
     checks:
       - "Closeout starts from status capability context"
@@ -100,15 +101,14 @@ VALIDATION:
     id: V10
     rule: closeout_fallback_before_raw
     description: >-
-      If closeout context is incomplete or caveated, Document MUST run the
-      listed existing CLI fallback commands before any last-resort raw artifact
-      read. No unsupported capability-name command or new closeout command may
-      be introduced.
+       If closeout context is incomplete or caveated, Document MUST run the
+       listed bounded CLI fallback commands before any diagnostic-only raw
+       artifact read. No unsupported capability-name command or new closeout command may
+        be introduced.
     severity: critical
     checks:
-      - "Listed CLI fallback commands run before raw artifact reads"
-      - "Raw reads are last-resort diagnostics or write targets only"
-      - "No unsupported capability-name command is introduced"
+       - "Listed bounded CLI fallback commands run before diagnostic-only raw reads"
+       - "Raw reads are diagnostic-only or write targets"
   11:
     id: V11
     rule: closeout_caveat_preservation

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: objective
+    artifact: objective
     local_role: produces_and_consumes
     description: >-
       Optimization target definition: metric, current value, target, constraints,
@@ -10,7 +10,7 @@ ARTIFACTS:
       canonical closure.
   2:
     id: A2
-    artifact_id: optimera_harness
+    artifact: optimize_harness
     local_role: produces
     description: >-
       Eval script that measures the metric and outputs structured JSON. Written
@@ -18,7 +18,7 @@ ARTIFACTS:
       Never modified during optimization cycles.
   3:
     id: A3
-    artifact_id: experiments
+    artifact: experiments
     local_role: produces_and_consumes
     description: >-
       Log of every experiment: hypothesis, method, change, metric before/after,
@@ -26,44 +26,44 @@ ARTIFACTS:
       suggestion. Optimize appends to this each cycle.
   4:
     id: A4
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Optimize inspects the last 3 entries to detect 3 consecutive failures
       before reporting exit status.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: produces
     description: >-
       Optimize writes to this when logging a failure pattern after 3
       consecutive failures.
   6:
     id: A6
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Optimize reads this during Orient for context on prior deliberations
       about the optimization objective.
   7:
     id: A7
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Optimize reads this to modulate experiment aggressiveness and constraint
       tolerance based on user preferences.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Optimize reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   9:
     id: A9
-    artifact_id: benchmark_context
+    artifact: benchmark_context
     local_role: consumes
     description: >-
-      CLI-provided startup benchmark summary from `agentera prime --context
+      CLI-provided startup benchmark summary from `npx -y agentera@next prime --context
       optimize --format json`. Optimize consumes this before any direct
       latest-report.json, latest-report.md, or runs.jsonl diagnostic read.

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

@@ -5,7 +5,7 @@ EXIT_CONDITIONS:
     description: >-
       One experiment completed the full cycle: hypothesis formulated,
       implementation dispatched, regression check passed, metric measured,
-      decision made (kept or discarded), and EXPERIMENTS.md updated.
+      decision made (kept or discarded), and experiments.yaml updated.
     exit_signal: complete
   2:
     id: E2
@@ -20,7 +20,7 @@ EXIT_CONDITIONS:
     id: E3
     condition: stuck
     description: >-
-      Cannot proceed because OBJECTIVE.md is missing and the brainstorm cannot
+      Cannot proceed because objective.yaml is missing and the brainstorm cannot
       be completed without user input, the eval harness is broken and cannot
       be repaired without user approval, or the regression check infrastructure
       is unavailable.

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

@@ -1,47 +1,16 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests optimize.
+    description: Improve an existing system against a measurable target.
     priority: high
-    patterns:
-      - "optimize"
-      - "/optimize"
-    confidence_threshold: 60
-    borderline_band: 20
     disambiguates_against:
       - capability: audit
         hint: "optimize tunes existing code; audit reviews codebase health"
   2:
     id: T2
-    description: >-
-      Metric-driven optimization requests. Matches when the user wants to
-      improve a concrete, quantifiable property of their codebase.
-    priority: medium
-    patterns:
-      - "optimize"
-      - "improve performance"
-      - "reduce latency"
-      - "increase test coverage"
-      - "lower bundle size"
-      - "speed up"
-      - "make faster"
-      - "make smaller"
-      - "get the score up"
-      - "hit the target"
-      - "improve the metric"
-    confidence_threshold: 50
-    borderline_band: 20
+    description: Improve a concrete metric such as startup time, latency, coverage, or size.
+    priority: high
   3:
     id: T3
-    description: >-
-      Iterative experimentation requests. Matches when the user wants to
-      run experiments, benchmark, or iterate on a measurable objective.
+    description: Benchmark, experiment, or iterate toward a measurable objective.
     priority: medium
-    patterns:
-      - "benchmark and iterate"
-      - "run experiments"
-      - "tune"
-      - "experiment until"
-    confidence_threshold: 50

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

@@ -24,12 +24,12 @@ VALIDATION:
     id: V3
     rule: objective_readonly_during_cycle
     description: >-
-      OBJECTIVE.md MUST NOT be modified during a cycle except for canonical
+      objective.yaml MUST NOT be modified during a cycle except for canonical
       closure when the target is met. Other edits only happen during
       brainstorm or refine.
     severity: critical
     checks:
-      - "OBJECTIVE.md only modified for closure during cycle"
+      - "objective.yaml only modified for closure during cycle"
   4:
     id: V4
     rule: one_experiment_per_invocation
@@ -65,7 +65,7 @@ VALIDATION:
     id: V7
     rule: benchmark_context_first
     description: >-
-      For benchmark-oriented startup, Optimize MUST start from `agentera prime
+      For benchmark-oriented startup, Optimize MUST start from `npx -y agentera@next prime
       --context optimize --format json` and consume complete
       benchmark_context before direct retained benchmark file reads. Direct
       latest-report.json, latest-report.md, or runs.jsonl reads are last-resort

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