agentera 3.0.0-dev.27 → 3.0.0-dev.29

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

@@ -1,62 +1,22 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests status.
+    description: Explicit status requests and orientation for the current project.
     priority: high
-    patterns:
-      - "status"
-      - "/status"
-    confidence_threshold: 60
-    borderline_band: 10
   2:
     id: T2
-    description: >-
-      Session-start signals. Matches explicit session-start or returning-to-project
-      requests from a user resuming work.
-    priority: medium
-    patterns:
-      - "start"
-      - "begin"
-      - "getting started"
-      - "onboard me"
-    confidence_threshold: 40
+    description: Session-start requests seeking orientation before choosing work.
+    priority: high
   3:
     id: T3
-    description: >-
-      Status and orientation requests. Matches when the user wants to know
-      the current state of the project or get a briefing.
+    description: Current project state, briefing, attention, or progress requests.
     priority: medium
-    patterns:
-      - "status"
-      - "dashboard"
-      - "pulse"
-      - "brief"
-      - "brief me"
-      - "update me"
-      - "what needs attention"
-    confidence_threshold: 45
   4:
     id: T4
-    description: >-
-      Returning-to-project signals. Matches when the user resumes work
-      on a known project and wants to pick up where they left off.
-    priority: medium
-    patterns:
-      - "where were we"
-      - "catch me up"
-      - "what should I work on"
-      - "what's next"
-    confidence_threshold: 45
+    description: Resume-work and “what's next?” requests with no separate requested outcome.
+    priority: high
   5:
     id: T5
-    description: >-
-      Fallback. Status is the default capability when no other capability's
-      trigger patterns match. This entry documents the fallback behavior
-      defined in the routing layer routing logic.
-    patterns:
-      - "*"
+    description: Fallback orientation when no capability fits the request.
     fallback: true
     priority: low
-    confidence_threshold: 0

package/bundle/skills/agentera/capabilities/vision/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 vision.
+    description: Requests to define or refine the project's vision and direction.
     priority: high
-    patterns:
-      - "vision"
-      - "/vision"
-    confidence_threshold: 60
-    borderline_band: 10
   2:
     id: T2
-    description: >-
-      Vision creation requests. Matches when the user wants to define or
-      create a project vision or north star direction.
-    priority: medium
-    patterns:
-      - "create a vision"
-      - "write the vision"
-      - "define the direction"
-      - "set the north star"
-      - "dream bigger"
-    confidence_threshold: 50
+    description: Define a new north star, product direction, or desired future.
+    priority: high
   3:
     id: T3
-    description: >-
-      Vision refinement requests. Matches when the user wants to evolve
-      or rethink an existing vision.
-    priority: medium
-    patterns:
-      - "rethink the vision"
-      - "refine the vision"
-      - "update the vision"
-    confidence_threshold: 50
+    description: Refine, rethink, or update an existing vision or north star.
+    priority: high
     disambiguates_against:
       - capability: build
         hint: "vision refines existing project direction; build implements code"
-    patterns_regex:
-      - "\\brefine\\s+the\\s+vision\\b"
-      - "update\\s+the\\s+vision"
   4:
     id: T4
-    description: >-
-      Project bootstrap. Matches when the user wants to bootstrap a new
-      project identity or define what a project should become.
-    priority: medium
-    patterns:
-      - "bootstrap the project"
-      - "what should this project become"
-    confidence_threshold: 50
+    description: Establish a new project's identity or decide what it should become.
+    priority: high
     disambiguates_against:
       - capability: plan
         hint: "vision defines what a project should become; plan structures the work"

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -48,8 +48,9 @@ ENTRY_SCHEMA:
       type: string
       required: false
       description: >-
-        Advisory relevance-precedence hint the LLM host reads alongside the
-        entry description. Required for all TRIGGERS entries.
+        Advisory relevance-precedence hint a host reads alongside the entry
+        description only after deterministic routing returns semantic_required.
+        Required for all TRIGGERS entries.
         Valid values: high, medium, low.
     deprecated:
       type: boolean
@@ -136,32 +137,34 @@ FIELD_RULES:
         - medium
         - low
       description: >-
-        Relevance-precedence hint the LLM host reads when ordering
-        candidate capabilities for a request. See
+        Relevance-precedence hint a host reads when ordering capability intent
+        after deterministic abstention. See
         references/cli/routing-model.md for routing semantics.
 
 TRIGGER_ENRICHMENT:
   description: >-
-    Optional trigger-entry intent-documentation fields. Every field is
-    OPTIONAL: a triggers.yaml entry that omits all enriched fields remains
-    valid. The LLM host consumes description and disambiguates_against at
-    runtime; confidence_threshold, borderline_band, and patterns_regex are
-    retained as shape-validated documentation so triggers.yaml files that
-    carry them still validate.
+    Optional trigger-entry fields. Every field is OPTIONAL: a triggers.yaml
+    entry that omits all enriched fields remains valid. A host consumes
+    disambiguates_against as semantic-phase intent documentation only after
+    deterministic abstention. patterns,
+    confidence_threshold, borderline_band, and patterns_regex are legacy
+    compatibility fields: they remain shape-validated only and never enter the
+    active semantic trigger model.
   spec: references/cli/trigger-schema-enrichment.md
-  contract_defaults:
-    # Default values for optional enriched fields.
-    confidence_threshold: 50
-    borderline_band: 15
   fields:
+    patterns:
+      type: list_of_strings
+      required: false
+      description: >-
+        Legacy matcher strings retained only so existing trigger files load and
+        validate. They are never matched or returned by the active model.
     confidence_threshold:
       type: integer
       required: false
       min: 0
       max: 100
-      default: 50
       description: >-
-        Optional integer 0-100. Not consumed by the LLM host; retained so
+        Legacy integer 0-100. Not consumed by the LLM host; retained so
         triggers.yaml files carrying the field still validate. A non-integer
         or value outside 0..100 fails V7 validation with the valid range
         and the offending entry ID.
@@ -170,25 +173,21 @@ TRIGGER_ENRICHMENT:
       required: false
       min: 0
       max: 100
-      default: 15
       description: >-
-        Optional integer 0-100. Not consumed by the LLM host; retained so
+        Legacy integer 0-100. Not consumed by the LLM host; retained so
         triggers.yaml files carrying the field still validate. A non-integer
         or value outside 0..100 fails V7 validation.
     patterns_regex:
       type: list_of_strings
       required: false
-      default: []
       each_must_be_valid_regex: true
       description: >-
-        Optional list of regex strings. Not consumed by the LLM host;
-        retained so triggers.yaml files carrying the field still validate.
-        The loader compiles each entry during validation; a compile failure
-        fails V7 validation naming the offending entry and pattern.
+        Legacy list of regex strings. Not consumed by the LLM host; retained
+        so triggers.yaml files carrying the field still validate. The loader
+        syntax-validates each entry but never returns a RegExp or matches it.
     disambiguates_against:
       type: list_of_mappings
       required: false
-      default: []
       description: >-
         Declares which other capabilities this trigger's intent could be
         confused with, with a hint the LLM host consults when a request could
@@ -497,13 +496,14 @@ VALIDATION:
     description: >-
       Trigger entries MAY carry the optional intent-documentation fields
       defined in TRIGGER_ENRICHMENT. Enrichment is opt-in per entry;
-      triggers omitting every enriched field remain valid.
-      confidence_threshold, borderline_band, and patterns_regex are
-      retained as shape-validated documentation; disambiguates_against
-      is consumed by the LLM host at runtime. Validating an entry with
-      enriched fields fails when the rules below are violated.
+      triggers omitting every enriched field remain valid. patterns,
+      confidence_threshold, borderline_band, and patterns_regex are legacy
+      compatibility fields only; disambiguates_against is consumed by the
+      LLM host at runtime. Validating an entry with enriched fields fails
+      when the rules below are violated.
     severity: error
     checks:
+      - "patterns, when present, is a list of strings"
       - "confidence_threshold, when present, is an integer in 0..100"
       - "borderline_band, when present, is an integer in 0..100"
       - "patterns_regex entries are strings that compile as regular expressions"

package/bundle/skills/agentera/route-phrases.yaml

@@ -0,0 +1,81 @@
+schema_version: agentera.route_phrase_registry.v1
+status: active_authority
+purpose: >-
+  Own the small, explicit inventory of deterministic leading phrases. Trigger
+  schemas remain semantic intent documentation and are not a phrase source.
+normalization: references/cli/hybrid-route-contract.yaml#phrase_matching
+rules:
+  stable_ids: Phrase IDs are permanent and never reassigned.
+  active_matching: Only entries with status active are eligible for matching.
+  global_collisions: >-
+    Normalized phrases must be unique across active and deprecated entries; a
+    collision is a validation error, never a precedence decision.
+  direct_route_collisions: >-
+    A phrase cannot duplicate or begin with a canonical capability name or a
+    primary alias under the direct-route grammar.
+  deprecation: >-
+    Remove no entry. Mark it deprecated, retain its ID and phrase, and set
+    replaced_by to an active registry ID. Deprecated phrases abstain.
+  prohibited_sources: [legacy_patterns, regexes, thresholds, bands, trigger_descriptions]
+
+phrases:
+  - id: RP_STATUS_PROJECT_BRIEFING
+    capability: status
+    phrase: show project briefing
+    status: active
+    evidence: [DEV-PHRASE-STATUS]
+  - id: RP_VISION_PRODUCT_DIRECTION
+    capability: vision
+    phrase: define product direction
+    status: active
+    evidence: [DEV-PHRASE-VISION]
+  - id: RP_DISCUSS_DECISION
+    capability: discuss
+    phrase: help me decide
+    status: active
+    evidence: [DEV-PHRASE-DISCUSS]
+  - id: RP_RESEARCH_EXTERNAL_PATTERNS
+    capability: research
+    phrase: study external patterns
+    status: active
+    evidence: [DEV-PHRASE-RESEARCH]
+  - id: RP_PLAN_IMPLEMENTATION
+    capability: plan
+    phrase: make an implementation plan
+    status: active
+    evidence: [DEV-PHRASE-PLAN]
+  - id: RP_BUILD_APPROVED_PLAN
+    capability: build
+    phrase: implement the approved plan
+    status: active
+    evidence: [DEV-PHRASE-BUILD]
+  - id: RP_OPTIMIZE_BOTTLENECK
+    capability: optimize
+    phrase: improve a measured bottleneck
+    status: active
+    evidence: [DEV-PHRASE-OPTIMIZE]
+  - id: RP_AUDIT_CODEBASE_HEALTH
+    capability: audit
+    phrase: check codebase health
+    status: active
+    evidence: [DEV-PHRASE-AUDIT]
+  - id: RP_DOCUMENT_PROJECT
+    capability: document
+    phrase: refresh project documentation
+    status: active
+    evidence: [DEV-PHRASE-DOCUMENT]
+  - id: RP_PROFILE_DECISION
+    capability: profile
+    phrase: save a decision profile
+    status: active
+    evidence: [DEV-PHRASE-PROFILE]
+  - id: RP_DESIGN_INTERFACE
+    capability: design
+    phrase: shape the interface
+    status: active
+    evidence: [DEV-PHRASE-DESIGN]
+  - id: RP_ORCHESTRATE_DELIVERY
+    capability: orchestrate
+    phrase: execute the approved plan
+    status: active
+    evidence: [DEV-PHRASE-ORCHESTRATE]

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

@@ -1,9 +1,10 @@
 # Health Artifact Schema
 #
-# 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.
+# Audit normally owns health records. Orchestrate may append only the limited
+# artifact_freshness record for terminal-plan closure after Audit passes. 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.
 #
 # The active authority is one health_audit entity per writer-owned file. The
 # numbered projection model below is retained only as an exact legacy migration
@@ -15,6 +16,7 @@
 # ─────────────────────────────────────────────────────────────────────
 # ## Audit N · date                     AUDIT.number           HA1
 # (date from heading)                   AUDIT.date             HA2
+# (CLI append time)                     AUDIT.appended_at      HA7
 # **Dimensions assessed**: <list>       AUDIT.dimensions       HA3
 # **Findings**: N crit, N warn, N info  AUDIT.findings_summary HA4
 # **Overall trajectory**: <text>        AUDIT.trajectory       HA5
@@ -50,12 +52,13 @@ meta:
   name: health
   version: "1.0.0"
   description: >-
-    Audit log maintained by audit. Consumed by capabilities that need
-    codebase health context.
+    Audit normally owns health records. Orchestrate may append only the
+    limited artifact_freshness record for terminal-plan closure after Audit
+    passes. Consumed by capabilities that need codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
   authority: legacy_migration_input_only
-  producer: audit
+  producer: [audit, orchestrate]
   consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
@@ -238,6 +241,21 @@ AUDIT:
     validation:
       - "Every assessed dimension has a grade"
       - "Grades are single characters A through F"
+  7:
+    id: HA7
+    field: appended_at
+    type: string
+    format: "YYYY-MM-DDTHH:mm:ss.sssZ"
+    required: false
+    cli_owned: true
+    description: >-
+      Canonical UTC timestamp assigned by the health append writer. Full records
+      with this field sort newest-first by append time, then stable ID. Legacy
+      records without it retain date-then-ID ordering; migration never fabricates
+      append chronology.
+    validation:
+      - "When present, must be canonical UTC ISO-8601 with millisecond precision"
+      - "Must be omitted from caller input and assigned by the CLI writer"
 
 DIMENSION:
   1:

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

@@ -609,6 +609,7 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/upgrade/doctor.ts
       - packages/cli/src/cli/commands/prime/v1Migration.ts
       - packages/cli/src/state/entityMigration*.ts
+      - packages/cli/src/state/canonicalMigrationRecord.ts
     schemas:
       - skills/agentera/schemas/artifacts/*.yaml
       - skills/agentera/capabilities/*/schemas/*.yaml
@@ -644,11 +645,9 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/capabilities/*/instructions.ts
       - packages/cli/README.md
       - skills/agentera/SKILL.md
-      - skills/agentera/agents/*
       - skills/agentera/references/*
       - references/**/*.md
       - docs/**
-      - packages/web/src/**
       - "*.md"
       - AGENTS.md
       - README.md

package/dist/capabilities/discuss/instructions.js

@@ -1,7 +1,7 @@
 // Capability instructions for discuss (canonical per D57; D65 relocated from .md to .ts)
 // Served via `agentera prime --context discuss --format json`. RFC 2119 modal vocab per D71.
 // Rewritten per Decision 82 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
-export const instructions = JSON.parse(String.raw `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nGlyph: **❈** (protocol ref: SG4). Structured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; discuss asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nOne deliberation per invocation. The user controls when it ends.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, run with a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nDiscuss reads prior decisions and profile for context, writes decisions as its primary product, and touches vision/objective/todo only as protected follow-through.\n\n| Artifact | Role | Source |\n|---|---|---|\n| decisions | produces/consumes | \u0060agentera state decisions list --limit 20 --format json\u0060 |\n| profile | consumes | \u0060deliberation_context.profile.path\u0060 (session start) |\n| vision, objective, todo | protected writes | \u0060protected_write_boundaries\u0060 (confirmation required) |\n| docs | consumes | \u0060deliberation_context.docs_mapping\u0060 (path resolution) |\n\n**Startup contract**: trust \u0060deliberation_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context discuss --format json\u0060. Use the included state families first; run listed \u0060fallback_commands\u0060 before any raw decisions artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH/DL) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### decisions.yaml\n\n\u0060\u0060\u0060yaml\ndecisions:\n  - number: N\n    date: \"YYYY-MM-DD\"\n    question: what was being decided\n    context: relevant constraints, triggers, or prior decisions\n    alternatives:\n      - name: Option A\n        description: Tradeoffs.\n        status: chosen\n      - name: Option B\n        description: Tradeoffs.\n        status: rejected\n    choice: what was chosen\n    reasoning: the key insight or tradeoff that resolved it\n    confidence: firm\n    feeds_into: [vision]\n\u0060\u0060\u0060\n\nPreserve the semantic top-level fields exactly (\u0060question\u0060, \u0060context\u0060, \u0060alternatives\u0060, \u0060choice\u0060, \u0060reasoning\u0060, \u0060confidence\u0060, \u0060feeds_into\u0060). Each alternative has \u0060name\u0060, \u0060status\u0060 (chosen or rejected), and optional \u0060description\u0060.\n\nNumbering, insertion order, validation, and compaction are writer-owned. Discover the live contract with \u0060agentera state decisions explain --verb append --format json\u0060; append with \u0060agentera state decisions append ... --format json\u0060.\n\n---\n\n## The deliberation loop\n\nConversational-loop shape: scratchpad plus per-turn question loop; no linear progression. The loop runs until the user picks Done.\n\n### Startup\n\n1. Read the served \u0060deliberation_context\u0060 from \u0060agentera prime --context discuss --format json\u0060 — prior decisions (avoid re-deliberation), profile path for high-confidence entries, docs mapping. If a needed family is missing or CLI state is incomplete, run the listed \u0060fallback_commands\u0060 before raw reads.\n2. If a topic was provided: name what reaching the end of this deliberation looks like — the decision to lock, the understood-shape, or the resolved tension. It fixes scope; every question serves it. Then read just enough codebase context to ask informed questions (not a research binge); acknowledge high-confidence profile entries so settled ground isn't re-litigated. Reflect understanding in 1-2 sentences, then ask the first question through the runtime-native question tool. For \u0060discuss <topic>\u0060, that question is the first user-facing action after the reflection.\n3. If no topic was provided: ask what's on their mind.\n\n### Per turn\n\nAsk every user-facing deliberation question through the runtime-native question tool; concrete tool availability belongs to the active host runtime. **One question per turn, no exceptions; every question includes a \u0060Done\u0060 option.** This overrides the routing layer's generic status/handoff question-tool gate. If the user asks for a recommendation, put a provisional recommendation in the question text, then offer accept / challenge / alternative / stop. Don't ask about \"depth\" or \"mode.\" Read the room.\n\nAfter each answer, show a short scratchpad:\n\n\u0060\u0060\u0060\n── scratchpad\n\nDecision: one-liner framing of what's being decided, updated as understanding evolves\n\nConstraints:\n▸ hard requirements that any option must satisfy\n\nRuled out:\n▸ what this decision is explicitly not about — fixed by the destination, not by sharpness\n\nOptions:\n▸ the options being considered · emerging pros/cons\n\nCrux: the key tension or uncertainty that needs to resolve for the decision to land\n\u0060\u0060\u0060\n\n5-8 bullets max. Drop items that stop being relevant.\n\n**Questions** should do one of these (≤15 words each): **Clarify** (\"When you say X, do you mean A or B?\"), **Dig deeper** (\"What's driving that?\"), **Reframe** (\"From the user's perspective instead?\"), **Challenge** (\"Is that actually true, or always been done?\"), **Connect** (\"That sounds like the same tension as Y.\"), **Unstick** (\"If you had to decide right now, what would you pick?\"), **Scope** (\"What's in and what's out?\"), **Constrain** (\"What must NOT happen?\"), **Tradeoff** (\"You can't have both X and Y. Which do you optimize for?\").\n\n**Steering**:\n- When more than one thread is open, fan across them before going deep on one — a tangent often hides the real crux off to the side.\n- When verbal exchange is slow on a visual/structural/API-shaped decision, ask the user to rough out a sketch, outline, or stub you can react to. You never produce the artifact — you ask for it and question what it reveals.\n\nWhen the decision involves code, read files or search the web for better questions — just enough context. When the profile has signal, skip settled ground.\n\n**Pushback discipline** — honest friction, don't let vague answers slide:\n- **Demand specifics.** \"What does 'better' look like? What would you measure?\"\n- **Name hidden assumptions.** \"That assumes X — based on something you've seen, or a hunch?\"\n- **Reframe imprecise framing.** \"I think the real question is Y, not X.\"\n- **Don't lower the bar.** \"Earlier you wanted Z. This gives half. Is half enough?\"\n\n**Pressure-test committed directions** — when the user leans toward a consequential direction, challenge before offering alternatives: (1) name 1-3 context-specific blind spots; (2) present serious alternatives with concrete win conditions; (3) make the call with explicit confidence (DL1-DL3).\n\n**Red-flag phrasing banned** (weakens the challenge): \"That sounds reasonable\", \"Either way is fine\", \"It depends\" without naming the variable, \"There is no wrong answer here\", \"Both options are valid\" when one conflicts with constraints.\n\n**Satisfaction authority** — when deliberation touches decision satisfaction, capture provisional satisfaction with evidence only. Only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in the scratchpad or decision note instead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### When the user picks \"Done\"\n\nProduce something actionable.\n\n1. **Summarize**: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n2. **Readiness check**: name any remaining fog — what's still unphrasable or unverified. A decision is ready to land when the remaining unknowns are sharp answerable questions, not fog you can't yet phrase. If fog remains and you're calling it firm (DL1), surface that as a tension to resolve before landing; provisional (DL2) or exploratory (DL3) may land with the fog named. The user still controls when to land — this names the tax, doesn't block the exit.\n3. **Offer to capture and connect** (relevant only): Log it → new numbered decision entry (always offered); Feed into vision (direction/scope/principles); Feed into objective (what to optimize); File to todo (surfaced tech debt); Just wrap up.\n4. **Pre-write self-audit**: run \u0060agentera check lint --artifact decisions --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to catch verbosity overruns, abstraction creep, and filler. Max 3 revision attempts; flag \u0060[post-audit-flagged]\u0060 if still failing.\n5. **Write artifacts**: append the chosen decision, confidence, and rationale through \u0060agentera state decisions append ... --format json\u0060. Update satisfaction only through \u0060agentera state decisions update --number N ...\u0060. vision / objective / todo — brief follow-up, draft presented for approval per \u0060protected_write_boundaries\u0060.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT make the decision for the user. Discuss helps them think; it does not decide.\n- MUST NOT skip to implementation. The pull to *just do the work* is the signal you've reached deliberation's edge — surface it and hand off to build, plan, or research. Discuss deliberates; it does not deliver.\n- MUST NOT modify vision, objective, or todo artifacts (the \u0060protected_write_boundaries\u0060) without explicit user confirmation. Present drafts; get approval.\n- MUST NOT ask compound questions. One question per turn, with a Done option.\n- MUST NOT fabricate or imply user-confirmed final decision satisfaction. Only the user confirms final satisfaction; provisional satisfaction requires evidence. Preserve compacted, missing, open, or review-needed satisfaction as caveats.\n- MUST NOT ignore the decision profile. Acknowledge high-confidence entries; treat low-confidence entries as hypotheses.\n- MUST NOT dismiss a user's stated concern. Explore it.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ❈ discuss · <status> ───\u0060 followed by a one-sentence summary. For flagged, stuck, and waiting, add a \u0060▸\u0060 (VT15) bullet below the summary naming what needs attention.\n\n- **complete** (EX1): Deliberation reached a conclusion the user acted on; artifacts written with approval; confidence captured.\n- **flagged** (EX2): Deliberation concluded but unresolved or provisional; significant tensions unresolved; or the conclusion contradicts prior decisions without acknowledgment.\n- **stuck** (EX3): Cannot proceed — topic requires inaccessible external research, or a protected write failed.\n- **waiting** (EX4): No topic provided and the user hasn't responded, or deliberation surfaced that a different capability is needed first and the user hasn't confirmed how to proceed.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n- **Feeds ⧉ build**: direction decisions captured in vision; decision entries whose \u0060feeds_into\u0060 names vision give build reasoning context.\n- **Feeds ⎘ optimize**: what-to-optimize decisions captured in the objective artifact, resolved via optimize's active-objective inference.\n- **Triggers ⬚ research**: during deliberation, if external research is needed — \"Sounds like we need to research X with ⬚ research?\"\n- **Informed by ♾ profile**: read at session start; high-confidence entries acknowledged, low-confidence treated as hypotheses.\n- **Feeds ♾ profile**: the decisions artifact is high-signal input for profile's extraction scripts.\n- **Feeds ≡ plan**: when deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n- **Triggered by ⛶ audit**: when audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n**When to invoke** (inverse of feeds-into): run \u0060/agentera discuss\u0060 before a build session (think through direction before vision), before an optimize session (which metric matters and why, before the objective artifact), after a research analysis (evaluate which recommendations to adopt), or standalone whenever something complex needs thinking through.\n"`);
+export const instructions = JSON.parse(String.raw `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nGlyph: **❈** (protocol ref: SG4). Structured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; discuss asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nOne deliberation per invocation. The user controls when it ends.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, run with a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nDiscuss reads prior decisions and profile for context, writes decisions as its primary product, and touches vision/objective/todo only as protected follow-through.\n\n| Artifact | Role | Source |\n|---|---|---|\n| decisions | produces/consumes | \u0060agentera state decisions list --limit 20 --format json\u0060 |\n| profile | consumes | \u0060deliberation_context.profile.path\u0060 (session start) |\n| vision, objective, todo | protected writes | \u0060protected_write_boundaries\u0060 (confirmation required) |\n| docs | consumes | \u0060deliberation_context.docs_mapping\u0060 (path resolution) |\n\n**Startup contract**: trust \u0060deliberation_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context discuss --format json\u0060. Use the included state families first; run listed \u0060fallback_commands\u0060 before any raw decisions artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH/DL) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### decisions.yaml\n\n\u0060\u0060\u0060yaml\ndecisions:\n  - number: N\n    date: \"YYYY-MM-DD\"\n    question: what was being decided\n    context: relevant constraints, triggers, or prior decisions\n    alternatives:\n      - name: Option A\n        description: Tradeoffs.\n        status: chosen\n      - name: Option B\n        description: Tradeoffs.\n        status: rejected\n    choice: what was chosen\n    reasoning: the key insight or tradeoff that resolved it\n    confidence: firm\n    feeds_into: [vision]\n\u0060\u0060\u0060\n\nPreserve the semantic top-level fields exactly (\u0060question\u0060, \u0060context\u0060, \u0060alternatives\u0060, \u0060choice\u0060, \u0060reasoning\u0060, \u0060confidence\u0060, \u0060feeds_into\u0060). Each alternative has \u0060name\u0060, \u0060status\u0060 (chosen or rejected), and optional \u0060description\u0060.\n\nNumbering, insertion order, validation, and compaction are writer-owned. Discover the live contract with \u0060agentera state decisions explain --verb append --format json\u0060; append with \u0060agentera state decisions append ... --format json\u0060.\n\n---\n\n## The deliberation loop\n\nConversational-loop shape: scratchpad plus per-turn question loop; no linear progression. The loop runs until the user picks Done.\n\n### Startup\n\n1. Read the served \u0060deliberation_context\u0060 from \u0060agentera prime --context discuss --format json\u0060 — prior decisions (avoid re-deliberation), profile path for high-confidence entries, docs mapping. If a needed family is missing or CLI state is incomplete, run the listed \u0060fallback_commands\u0060 before raw reads.\n2. If a topic was provided: name what reaching the end of this deliberation looks like — the decision to lock, the understood-shape, or the resolved tension. It fixes scope; every question serves it. Then read just enough codebase context to ask informed questions (not a research binge); acknowledge high-confidence profile entries so settled ground isn't re-litigated. Reflect understanding in 1-2 sentences, then ask the first question through the runtime-native question tool. For \u0060discuss <topic>\u0060, that question is the first user-facing action after the reflection.\n3. If no topic was provided: ask what's on their mind.\n\n### Per turn\n\nAsk every user-facing deliberation question through the runtime-native question tool; concrete tool availability belongs to the active host runtime. **One question per turn, no exceptions; every question includes a \u0060Done\u0060 option.** This overrides the routing layer's generic status/handoff question-tool gate. If the user asks for a recommendation, put a provisional recommendation in the question text, then offer accept / challenge / alternative / stop. Don't ask about \"depth\" or \"mode.\" Read the room.\n\nAfter each answer, show a short scratchpad:\n\n\u0060\u0060\u0060\n── scratchpad\n\nDecision: one-liner framing of what's being decided, updated as understanding evolves\n\nConstraints:\n▸ hard requirements that any option must satisfy\n\nRuled out:\n▸ what this decision is explicitly not about — fixed by the destination, not by sharpness\n\nOptions:\n▸ the options being considered · emerging pros/cons\n\nCrux: the key tension or uncertainty that needs to resolve for the decision to land\n\u0060\u0060\u0060\n\n5-8 bullets max. Drop items that stop being relevant.\n\n**Questions** should do one of these (≤15 words each): **Clarify** (\"When you say X, do you mean A or B?\"), **Dig deeper** (\"What's driving that?\"), **Reframe** (\"From the user's perspective instead?\"), **Challenge** (\"Is that actually true, or always been done?\"), **Connect** (\"That sounds like the same tension as Y.\"), **Unstick** (\"If you had to decide right now, what would you pick?\"), **Scope** (\"What's in and what's out?\"), **Constrain** (\"What must NOT happen?\"), **Tradeoff** (\"You can't have both X and Y. Which do you optimize for?\").\n\n**Steering**:\n- When more than one thread is open, fan across them before going deep on one — a tangent often hides the real crux off to the side.\n- When verbal exchange is slow on a visual/structural/API-shaped decision, ask the user to rough out a sketch, outline, or stub you can react to. You never produce the artifact — you ask for it and question what it reveals.\n\nWhen the decision involves code, read files or search the web for better questions — just enough context. When the profile has signal, skip settled ground.\n\n**Pushback discipline** — honest friction, don't let vague answers slide:\n- **Demand specifics.** \"What does 'better' look like? What would you measure?\"\n- **Name hidden assumptions.** \"That assumes X — based on something you've seen, or a hunch?\"\n- **Reframe imprecise framing.** \"I think the real question is Y, not X.\"\n- **Don't lower the bar.** \"Earlier you wanted Z. This gives half. Is half enough?\"\n\n**Pressure-test committed directions** — when the user leans toward a consequential direction, challenge before offering alternatives: (1) name 1-3 context-specific blind spots; (2) present serious alternatives with concrete win conditions; (3) make the call with explicit confidence (DL1-DL3).\n\n**Red-flag phrasing banned** (weakens the challenge): \"That sounds reasonable\", \"Either way is fine\", \"It depends\" without naming the variable, \"There is no wrong answer here\", \"Both options are valid\" when one conflicts with constraints.\n\n**Satisfaction authority** — when deliberation touches decision satisfaction, capture provisional satisfaction with evidence only. Only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in the scratchpad or decision note instead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### When the user picks \"Done\"\n\nProduce something actionable.\n\n1. **Summarize**: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n2. **Readiness check**: name anything still unclear or unverified. A decision is ready to land when every remaining unknown is a specific, answerable question. If anything is still unclear or unverified and you're calling it firm (DL1), surface that tension before landing; provisional (DL2) or exploratory (DL3) may land with the unknowns named. The user still controls when to land — this clarifies the confidence cost; it doesn't block the exit.\n3. **Offer to capture and connect** (relevant only): Log it → new numbered decision entry (always offered); Feed into vision (direction/scope/principles); Feed into objective (what to optimize); File to todo (surfaced tech debt); Just wrap up.\n4. **Pre-write self-audit**: run \u0060agentera check lint --artifact decisions --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to catch verbosity overruns, abstraction creep, and filler. Max 3 revision attempts; flag \u0060[post-audit-flagged]\u0060 if still failing.\n5. **Write artifacts**: append the chosen decision, confidence, and rationale through \u0060agentera state decisions append ... --format json\u0060. Update satisfaction only through \u0060agentera state decisions update --number N ...\u0060. vision / objective / todo — brief follow-up, draft presented for approval per \u0060protected_write_boundaries\u0060.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT make the decision for the user. Discuss helps them think; it does not decide.\n- MUST NOT skip to implementation. The pull to *just do the work* is the signal you've reached deliberation's edge — surface it and hand off to build, plan, or research. Discuss deliberates; it does not deliver.\n- MUST NOT modify vision, objective, or todo artifacts (the \u0060protected_write_boundaries\u0060) without explicit user confirmation. Present drafts; get approval.\n- MUST NOT ask compound questions. One question per turn, with a Done option.\n- MUST NOT fabricate or imply user-confirmed final decision satisfaction. Only the user confirms final satisfaction; provisional satisfaction requires evidence. Preserve compacted, missing, open, or review-needed satisfaction as caveats.\n- MUST NOT ignore the decision profile. Acknowledge high-confidence entries; treat low-confidence entries as hypotheses.\n- MUST NOT dismiss a user's stated concern. Explore it.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ❈ discuss · <status> ───\u0060 followed by a one-sentence summary. For flagged, stuck, and waiting, add a \u0060▸\u0060 (VT15) bullet below the summary naming what needs attention.\n\n- **complete** (EX1): Deliberation reached a conclusion the user acted on; artifacts written with approval; confidence captured.\n- **flagged** (EX2): Deliberation concluded but unresolved or provisional; significant tensions unresolved; or the conclusion contradicts prior decisions without acknowledgment.\n- **stuck** (EX3): Cannot proceed — topic requires inaccessible external research, or a protected write failed.\n- **waiting** (EX4): No topic provided and the user hasn't responded, or deliberation surfaced that a different capability is needed first and the user hasn't confirmed how to proceed.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n- **Feeds ⧉ build**: direction decisions captured in vision; decision entries whose \u0060feeds_into\u0060 names vision give build reasoning context.\n- **Feeds ⎘ optimize**: what-to-optimize decisions captured in the objective artifact, resolved via optimize's active-objective inference.\n- **Triggers ⬚ research**: during deliberation, if external research is needed — \"Sounds like we need to research X with ⬚ research?\"\n- **Informed by ♾ profile**: read at session start; high-confidence entries acknowledged, low-confidence treated as hypotheses.\n- **Feeds ♾ profile**: the decisions artifact is high-signal input for profile's extraction scripts.\n- **Feeds ≡ plan**: when deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n- **Triggered by ⛶ audit**: when audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n**When to invoke** (inverse of feeds-into): run \u0060/agentera discuss\u0060 before a build session (think through direction before vision), before an optimize session (which metric matters and why, before the objective artifact), after a research analysis (evaluate which recommendations to adopt), or standalone whenever something complex needs thinking through.\n"`);
 export default instructions
     .replace(/## State artifacts[\s\S]*?## The deliberation loop/, `## State artifacts
 

package/dist/capabilities/discuss/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../../../../home/jgabor/git/agentera/packages/cli/src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gzYAAgzY,CAAC,CAAC;AAC32Y,eAAe,YAAY;KACxB,OAAO,CAAC,oDAAoD,EAAE;;;;;;yBAMxC,CAAC;KACvB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,OAAO,CAAC,6BAA6B,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../../../../home/jgabor/git/agentera/packages/cli/src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,qyYAAqyY,CAAC,CAAC;AACh2Y,eAAe,YAAY;KACxB,OAAO,CAAC,oDAAoD,EAAE;;;;;;yBAMxC,CAAC;KACvB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,OAAO,CAAC,6BAA6B,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/capabilities/orchestrate/instructions.js

@@ -1,6 +1,6 @@
 // Capability instructions for orchestrate
 // Served via `agentera prime --context orchestrate --format json`. RFC 2119 modal vocab.
-export const instructions = JSON.parse(String.raw `"# ORCHESTRATE\n\n**Orchestration Runtime: Knowledge-coordinated Execution Strategy, Targeted Routing. Evaluate, Resolve, Adapt.**\n\nGlyph: ⎈ (protocol ref: SG12).\n\nA meta-orchestrator that delegates capabilities as subagents, evaluates each task with audit, and loops through plans until work is done. The thin orchestrator: reads plans, routes tasks, gates quality. Never touches code. All creativity happens in delegated capabilities; orchestrate follows a deterministic state machine.\n\nEach invocation = one orchestration session. Multiple plan cycles within a single session. In orchestrate only, \u0060dispatch\u0060 and \u0060chain\u0060 are autonomous verbs inside the approved orchestration flow; \u0060suggest\u0060 waits for user confirmation before invoking.\n\n---\n\n## State artifacts\n\nOrchestrate produces no new artifact files. It reads and updates existing artifacts. Normal startup begins from \u0060agentera prime --context orchestrate --format json\u0060.\n\nTrust \u0060orchestration_context.source_contract\u0060. When \u0060complete_for_orchestration_context\u0060 is true, the context is authoritative — no raw plan, progress, health, TODO, or decisions reads for task selection or evaluator handoff. When incomplete, run listed fallback commands before any raw artifact read. Raw reads are last-resort diagnostics, not normal startup.\n\nThe \u0060agentera\u0060 CLI is a state interface. Do not run capability-name commands such as \u0060agentera build\u0060 or \u0060agentera plan\u0060.\n\n| Artifact | Role | Purpose |\n|----------|------|---------|\n| \u0060plan\u0060 | produces_and_consumes | Task queue. Use \u0060orchestration_context.task_queue\u0060 and \u0060selected_next_task\u0060; update status (pending → complete/blocked) only after evaluation. |\n| \u0060progress\u0060 | consumes | Cross-cycle context. Use \u0060orchestration_context.progress_verification\u0060; dispatched capabilities write their own entries. |\n| \u0060health\u0060 | consumes | Health context after plan completion to decide whether to start a new plan. |\n| \u0060todo\u0060 | produces | Blocked task logging. Write when a task exhausts its retry budget. |\n| \u0060decisions\u0060 | consumes | Decision context. Use included caveats or \u0060agentera state decisions list --limit 20 --format json\u0060; preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060. |\n| \u0060vision\u0060 | consumes | Direction context for bootstrap. If missing from context, treat as a caveat. |\n| \u0060profile\u0060 | consumes | Persona context. Preserve stale or missing caveats; do not refresh profile during orchestration. |\n| \u0060docs\u0060 | consumes | Artifact path resolution for write targets. |\n\n### Decision satisfaction authority\n\nWhen orchestration touches decision satisfaction, agents may mark provisional satisfaction with evidence only. Orchestrate MUST NOT mark, infer, or user-confirm final satisfaction; only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in dispatch and evaluation context.\n\nVisual tokens: \u0060skills/agentera/protocol.yaml\u0060 (task states VT1-VT4, glyph SG12, exit signals EX1-EX4, severity SI1-SI4, decision labels DL1-DL3).\n\n---\n\n## The orchestration loop\n\nThe orchestrator follows a deterministic state machine. It does not reason creatively about orchestration; it follows the loop.\n\n### Step 0: Assess\n\nStart from \u0060agentera prime --context orchestrate --format json\u0060. Check \u0060orchestration_context.source_contract\u0060, the returned plan summary, and \u0060state_presence\u0060 before considering raw artifacts.\n\n- **No plan in returned state**: bootstrap mode. Delegate to research for vision-gap analysis, then plan for plan creation. If the vision artifact is also absent or caveated, suggest ⛥ vision first and wait for user confirmation.\n- **Plan exists, \u0060header.status: complete\u0060, and all tasks complete**: completed-plan closure. Run the staleness check, archive the plan, then spawn audit for a health check. If clean, chain research then plan for the next plan cycle. Include lineage, staleness findings, health issues, and source-contract caveats as context.\n- **Plan exists, but blocked or incomplete tasks remain**: do not archive it as successful completion. Route to the orchestration loop or replanning so incomplete evidence stays visible.\n- **Plan exists, tasks pending**: proceed to the loop using \u0060orchestration_context\u0060 task selection.\n\n**Staleness check** (plan completion): When all tasks are complete, check whether delegated capabilities updated their expected artifacts.\n\n1. **Identify delegated capabilities** from plan task history and progress summary in CLI context.\n2. **Compare modification dates**: for each expected artifact, check \u0060git log -1 --format=%aI -- <path>\u0060 against the plan's creation date. An artifact is stale if it was not modified since the plan's creation and the owning capability was delegated at least once during the plan.\n3. **Surface findings**: include stale artifact findings as informational context for the next plan cycle. Archive the plan with \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming and active-plan removal.\n\n---\n\nStep markers: display \u0060── task N · step M/5: verb\u0060 before each step in the loop. N is the task number from the selected orchestration context task.\n\n### Step 1: Select task\n\nUse \u0060orchestration_context.selected_next_task\u0060 when present. Otherwise, use \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060: pick the first task whose dependencies are complete. Treat \u0060orchestration_context.task_queue.blocked_tasks[*].blocked_reasons\u0060 as the dependency explanation.\n\nIf no tasks are eligible (all remaining tasks are blocked by incomplete dependencies), report \u0060stuck\u0060 with the dependency chain.\n\nUse decision state or caveats from the returned context first. If decisions are missing from startup context, run \u0060agentera state decisions list --limit 20 --format json\u0060. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in dispatch and evaluation context instead of filling gaps by reconstruction.\n\n### Step 2: Delegate\n\nInfer which capability handles the task based on its description:\n\n| Task signals | Target capability |\n|--------------|-------------------|\n| Implementation, building, coding, feature, fix, refactor | ⧉ build |\n| Documentation, docs, README, CHANGELOG | ▤ document |\n| Health audit, architecture review, code quality check | ⛶ audit |\n| Research, external patterns, library evaluation | ⬚ research |\n| Optimization, performance, metric improvement, benchmark | ⎘ optimize |\n| Visual identity, design tokens, DESIGN.md | ◰ design |\n| Version bump | ⧉ build (with bump instructions from docs artifact) |\n\nIf the task does not clearly map, default to ⧉ build.\n\nSpawn the target capability through the runtime-native subagent substrate. Do not run capability-name CLI commands; the \u0060agentera\u0060 CLI remains a state interface.\n\n\u0060\u0060\u0060\nYou are executing a planned task for [project].\n\n## Task\n[Task title and description from selected_next_task]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria from selected_next_task or evaluator_handoff]\n\n## Context\n[Any relevant context from orchestration_context: related decision entries or caveats,\nhealth/TODO findings, prior task results, stale app/profile caveats, retry-state\nprovenance. Keep brief.]\n\n## Constraints\n- Execute ONLY this task. No scope creep.\n- Follow existing code patterns and conventions.\n- Use the runtime-native subagent descriptor or Task surface for the selected capability.\n- Commit your changes with a conventional commit message.\n- You are working on a plan-driven task. Update the task status in the plan artifact\n  to ■ complete when done.\n\u0060\u0060\u0060\n\nWait for the task-notification result.\n\n### Step 3: Evaluate\n\nEvaluation has two surfaces in sequence: an orchestrator-side presence check using latest progress verification, then an audit delegation whose prompt is extended with an evidence audit. Both surfaces must run before the task can be resolved.\n\n**Surface 1: Presence check from progress verification**\n\nWhen the delegated capability was build (or any capability that produces progress cycle entries), perform a cheap evidence presence check before spawning audit:\n\n1. Start with \u0060orchestration_context.progress_verification\u0060 and its \u0060latest_progress_verification_pointer\u0060.\n2. If unavailable or incomplete, run \u0060agentera state progress list --limit 20 --format json\u0060 before any raw artifact read.\n3. Look for a non-empty \u0060verified\u0060 field in the latest relevant progress entry.\n4. **Present and non-empty**: proceed to Surface 2.\n5. **Missing or empty**: treat the task as a failed evaluation. Go straight into Step 4's FAIL branch with \"missing or empty \u0060verified\u0060 field in progress Cycle N\" as the failure reason.\n\n**Surface 2: Audit delegation with evidence audit**\n\nOnce the presence check passes, spawn audit as a subagent to verify the work:\n\n\u0060\u0060\u0060\nYou are evaluating a completed task for [project].\n\n## Task that was completed\n[Task title and description from evaluator_handoff]\n\n## Acceptance criteria to verify\n[The task's Given/When/Then criteria from evaluator_handoff]\n\n## What to check\n- Verify each acceptance criterion against the current codebase state.\n- Check for unintended side effects from the implementation.\n- Verify the project's test/build suite still passes.\n\n## Verification evidence audit\n- Use the latest progress verification pointer and \u0060verified\u0060 evidence supplied by\n  the orchestration context or \u0060agentera state progress list --limit 20 --format json\u0060.\n- Compare the recorded evidence to the task's acceptance criteria.\n- Report whether the evidence substantiates the criteria or is merely trivially\n  populated (e.g., \"tests pass\" without any observation of the actual feature\n  running counts as insufficient).\n- If the field is \u0060N/A: <tag>\u0060, confirm the tag is drawn from the allowlist\n  (\u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060,\n  \u0060chore-build-config\u0060, \u0060test-only\u0060) AND that the tag fits the nature of the work.\n- If the field is a free-form N/A rationale, confirm it is at least 8 words long AND\n  actually explains why the change has no observable behavior.\n- Flag the task as FAIL on the evidence audit if the recorded \u0060verified\u0060 content\n  does not substantiate the acceptance criteria.\n\n## Source-contract caveats to preserve\n- Include compacted decision caveats, stale health/profile/app caveats, missing\n  state-family caveats, and retry-state provenance exactly as supplied.\n- Do not treat missing retry attempts as an attempt count. If status is\n  \u0060not_recorded\u0060 or \u0060unavailable\u0060, keep that status in the evaluation report.\n\n## Output format\nFor each acceptance criterion, report:\n- status: PASS or FAIL\n- evidence: what you checked and what you found\n- citation: \u0060<file>:<line>\u0060 OR \u0060not-applicable: <reason>\u0060 — **required for every FAIL row**\n- verify_command: exact \u0060grep\u0060 or \u0060git show\u0060 invocation — **required for every FAIL row\n  with a file:line citation**; the command must reproduce the evidence at the cited line\n\nUse \u0060orchestration_context.evaluator_handoff.output_requirements\u0060 from prime context as\nthe machine-readable citation contract. FAIL rows without a valid citation are incomplete\nand must be treated as evaluation failures.\n\nThen report the verification evidence audit outcome (PASS or FAIL with reasoning).\n\nThen give an overall verdict: PASS (all criteria met and evidence audit passed) or FAIL\n(any criterion failed or evidence audit failed).\n\u0060\u0060\u0060\n\nWait for the audit verdict.\n\n### Step 4: Resolve\n\nBased on audit's verdict:\n\n**PASS**: Mark the task \u0060■ complete\u0060 (VT1) in the plan artifact (if the delegated capability did not already do so). Proceed to Step 5.\n\n**FAIL (retries < 2)**: Increment the retry count. Re-delegate to the same capability with audit's findings as additional context:\n\n\u0060\u0060\u0060\nYou are retrying a task that failed evaluation for [project].\n\n## Original task\n[Task title and description]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria]\n\n## Evaluation findings (what failed)\n[Audit's failure report with evidence]\n\n## What to fix\nAddress each failure point. All acceptance criteria must pass on re-evaluation.\n\u0060\u0060\u0060\n\nReturn to Step 3.\n\n**FAIL (retries = 2)**: The task has exhausted its retry budget. Mark the task \u0060▨ blocked\u0060 (VT4) in the plan artifact. Log the failure to TODO.md with audit's findings as context. Proceed to Step 5.\n\nWhen writing to the plan artifact or TODO.md, use the task identity and caveats from \u0060orchestration_context\u0060. Do not refresh installed app/profile state, edit the vision artifact, or invent retry attempt counts.\n\n### Step 5: Log and loop\n\nCheck the plan state:\n\n- **More pending tasks with satisfied dependencies?** Return to Step 1.\n- **All tasks complete?** Return to Step 0 for completed-plan closure.\n- **Complete + blocked or incomplete tasks?** Keep the plan active and route to replanning or TODO logging; do not archive as successful completion.\n- **Context approaching budget limit?** Stop the session, report current progress.\n- **User interrupt?** Stop the session, report current progress.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT read implementation source code. The orchestrator delegates; it does not implement. Artifact files (\u0060.agentera/*.yaml\u0060, \u0060TODO.md\u0060) are state records, not source code; raw reads are last-resort after CLI context and listed fallback commands.\n- MUST NOT run tests, builds, linters, or implementation project commands directly. Delegated capabilities handle all verification.\n- MUST NOT modify the vision artifact. The orchestrator reads direction; it does not set it.\n- MUST NOT delegate to a capability without an active plan task justifying it (except during bootstrap in Step 0).\n- MUST NOT push to any remote. Local operations only.\n- MUST NOT retry a task more than 2 times. After the second failure, mark blocked and move on.\n- MUST NOT skip evaluation. Every completed task must be verified by audit before being marked complete.\n- MUST NOT make implementation decisions. Delegate to the appropriate capability.\n- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries. Orchestrate changes plan lifecycle state only through \u0060agentera state plan set-status ...\u0060 and \u0060agentera state plan archive\u0060.\n- MUST NOT research external patterns or libraries. Delegate to research.\n- MUST NOT mark, infer, or user-confirm final decision satisfaction. Only the user confirms. Preserve caveats for missing, compacted, open, provisional, or review-needed satisfaction state.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⎈ orchestrate · <status>\u0060 on its own line, followed by a summary sentence. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what needs attention.\n\n- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.\n- **flagged** (EX2): The plan was executed but with issues: one or more tasks were blocked after exhausting retries, or the post-plan health check revealed problems. Each concern is listed explicitly.\n- **stuck** (EX3): Cannot proceed because 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.\n- **waiting** (EX4): 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 delegated capability returned \u0060waiting\u0060 status requiring user input.\n\n### Loop stop condition\n\nEach task gets max 2 retries before being blocked. Additionally, if 3 consecutive different tasks all fail evaluation (even after their retries), orchestrate stops the session and escalates:\n\n1. **Stop**: do not delegate more tasks.\n2. **Log**: file the pattern to TODO.md with what was attempted across the 3 tasks and what appears systematically wrong.\n3. **Surface**: tell the user and recommend a course of action (e.g., \"⛶ audit for a full audit\", \"❈ discuss to reconsider the plan\", \"the plan may need replanning via ≡ plan\").\n\n---\n\n## Cross-capability integration\n\nOrchestrate is the orchestration layer that chains all other capabilities together. Each active runtime provides its registry-declared subagent substrate: OpenCode: \u0060OpenCode .opencode/agents single primary agent (D73)\u0060; Codex CLI: \u0060Codex ~/.codex/agents TOML descriptors\u0060; Cursor IDE and cursor-agent are one Cursor identity: \u0060Cursor .cursor/agents single agent descriptor (D73)\u0060; Copilot CLI: \u0060Copilot CLI host-managed dispatch\u0060. Orchestrator-side instructions, retry logic, and audit evaluation gating stay unchanged across runtimes; only the concrete delegation surface differs.\n\n### Delegation targets\n\n- **⧉ build**: Implementation, feature, fix, refactor tasks. Build runs its full cycle as a subagent and writes progress and changelog entries.\n- **⛶ audit**: Two roles — evaluator after each task completion (verifying acceptance criteria), and health checker after plan completion (producing health grades). Audit is the discriminator in the evaluate-then-proceed pattern.\n- **▤ document**: Documentation tasks — docs updates, README changes, documentation coverage.\n- **⬚ research**: Research tasks. During bootstrap, orchestrate chains research for vision-gap analysis before plan creates a plan.\n- **⎘ optimize**: Optimization-shaped tasks (metric improvement, performance tuning) route to optimize.\n- **◰ design**: Visual identity tasks (DESIGN.md updates, design token changes).\n- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.\n\n### State consumers\n\n- **❈ discuss**: Decision state provides firm constraints during task selection. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 from returned decision entries.\n- **⛺ vision**: Direction context during bootstrap. If vision is missing, preserve the caveat and ask before creating direction.\n- **♾ profile**: Persona context for calibrating delegation. Do not refresh profile state during orchestration; if unavailable, proceed without persona grounding and preserve the caveat.\n\n### When to use orchestrate\n\nExecute an existing plan: create the plan first (\u0060/agentera plan\u0060), then run \u0060/agentera orchestrate\u0060 to execute it with evaluation gating.\n\nFull autonomous session: \u0060/agentera orchestrate\u0060 with no plan triggers bootstrap (research → plan → execute).\n\nAfter a deliberation: \u0060/agentera discuss\u0060 → \u0060/agentera plan\u0060 → \u0060/agentera orchestrate\u0060.\n\nUse orchestrate instead of a host loop for plan-aware, evaluated, multi-cycle execution. Use it when the user explicitly requests autonomous multi-task execution.\n"`);
+export const instructions = JSON.parse(String.raw `"# ORCHESTRATE\n\n**Orchestration Runtime: Knowledge-coordinated Execution Strategy, Targeted Routing. Evaluate, Resolve, Adapt.**\n\nGlyph: ⎈ (protocol ref: SG12).\n\nA meta-orchestrator that delegates capabilities as subagents, evaluates each task with audit, and loops through plans until work is done. The thin orchestrator: reads plans, routes tasks, gates quality. Never touches code. All creativity happens in delegated capabilities; orchestrate follows a deterministic state machine.\n\nEach invocation = one orchestration session. Multiple plan cycles within a single session. In orchestrate only, \u0060dispatch\u0060 and \u0060chain\u0060 are autonomous verbs inside the approved orchestration flow; \u0060suggest\u0060 waits for user confirmation before invoking.\n\n---\n\n## State artifacts\n\nOrchestrate produces no new artifact files. It reads and updates existing artifacts. Normal startup begins from \u0060agentera prime --context orchestrate --format json\u0060.\n\nTrust \u0060orchestration_context.source_contract\u0060. When \u0060complete_for_orchestration_context\u0060 is true, the context is authoritative — no raw plan, progress, health, TODO, or decisions reads for task selection or evaluator handoff. When incomplete, run listed fallback commands before any raw artifact read. Raw reads are last-resort diagnostics, not normal startup.\n\nThe \u0060agentera\u0060 CLI is a state interface. Do not run capability-name commands such as \u0060agentera build\u0060 or \u0060agentera plan\u0060.\n\n| Artifact | Role | Purpose |\n|----------|------|---------|\n| \u0060plan\u0060 | produces_and_consumes | Task queue. Use \u0060orchestration_context.task_queue\u0060 and \u0060selected_next_task\u0060; update status (pending → complete/blocked) only after evaluation. |\n| \u0060progress\u0060 | consumes | Cross-cycle context. Use \u0060orchestration_context.progress_verification\u0060; dispatched capabilities write their own entries. |\n| \u0060health\u0060 | consumes | Health context after plan completion to decide whether to start a new plan. |\n| \u0060todo\u0060 | produces | Blocked task logging. Write when a task exhausts its retry budget. |\n| \u0060decisions\u0060 | consumes | Decision context. Use included caveats or \u0060agentera state decisions list --limit 20 --format json\u0060; preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060. |\n| \u0060vision\u0060 | consumes | Direction context for bootstrap. If missing from context, treat as a caveat. |\n| \u0060profile\u0060 | consumes | Persona context. Preserve stale or missing caveats; do not refresh profile during orchestration. |\n| \u0060docs\u0060 | consumes | Artifact path resolution for write targets. |\n\n### Decision satisfaction authority\n\nWhen orchestration touches decision satisfaction, agents may mark provisional satisfaction with evidence only. Orchestrate MUST NOT mark, infer, or user-confirm final satisfaction; only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in dispatch and evaluation context.\n\nVisual tokens: \u0060skills/agentera/protocol.yaml\u0060 (task states VT1-VT4, glyph SG12, exit signals EX1-EX4, severity SI1-SI4, decision labels DL1-DL3).\n\n---\n\n## The orchestration loop\n\nThe orchestrator follows a deterministic state machine. It does not reason creatively about orchestration; it follows the loop.\n\n### Step 0: Assess\n\nStart from \u0060agentera prime --context orchestrate --format json\u0060. Check \u0060orchestration_context.source_contract\u0060, the returned plan summary, and \u0060state_presence\u0060 before considering raw artifacts.\n\n- **No plan in returned state**: bootstrap mode. Delegate to research for vision-gap analysis, then plan for plan creation. If the vision artifact is also absent or caveated, suggest ⛥ vision first and wait for user confirmation.\n- **Plan exists, \u0060header.status: complete\u0060, and all tasks complete**: completed-plan closure. Run the staleness check, archive the plan, then spawn audit for a health check. If clean, chain research then plan for the next plan cycle. Include lineage, staleness findings, health issues, and source-contract caveats as context.\n- **Plan exists, but blocked or incomplete tasks remain**: do not archive it as successful completion. Route to the orchestration loop or replanning so incomplete evidence stays visible.\n- **Plan exists, tasks pending**: proceed to the loop using \u0060orchestration_context\u0060 task selection.\n\n**Staleness check** (plan completion): When all tasks are complete, check whether delegated capabilities updated their expected artifacts.\n\n1. **Identify delegated capabilities** from plan task history and progress summary in CLI context.\n2. **Compare modification dates**: for each expected artifact, check \u0060git log -1 --format=%aI -- <path>\u0060 against the plan's creation date. An artifact is stale if it was not modified since the plan's creation and the owning capability was delegated at least once during the plan.\n3. **Surface findings**: include stale artifact findings as informational context for the next plan cycle. Archive the plan with \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming and active-plan removal.\n\n---\n\nStep markers: display \u0060── task N · step M/5: verb\u0060 before each step in the loop. N is the task number from the selected orchestration context task.\n\n### Step 1: Select task\n\nUse \u0060orchestration_context.selected_next_task\u0060 when present. Otherwise, use \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060: pick the first task whose dependencies are complete. Treat \u0060orchestration_context.task_queue.blocked_tasks[*].blocked_reasons\u0060 as the dependency explanation.\n\nIf no tasks are eligible (all remaining tasks are blocked by incomplete dependencies), report \u0060stuck\u0060 with the dependency chain.\n\nUse decision state or caveats from the returned context first. If decisions are missing from startup context, run \u0060agentera state decisions list --limit 20 --format json\u0060. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in dispatch and evaluation context instead of filling gaps by reconstruction.\n\n### Step 2: Delegate\n\nInfer which capability handles the task based on its description:\n\n| Task signals | Target capability |\n|--------------|-------------------|\n| Implementation, building, coding, feature, fix, refactor | ⧉ build |\n| Documentation, docs, README, CHANGELOG | ▤ document |\n| Health audit, architecture review, code quality check | ⛶ audit |\n| Research, external patterns, library evaluation | ⬚ research |\n| Optimization, performance, metric improvement, benchmark | ⎘ optimize |\n| Visual identity, design tokens, DESIGN.md | ◰ design |\n| Version bump | ⧉ build (with bump instructions from docs artifact) |\n\nIf the task does not clearly map, default to ⧉ build.\n\nSpawn the target capability through the host-provided worker facility. Do not run capability-name CLI commands; the \u0060agentera\u0060 CLI remains a state interface.\n\n\u0060\u0060\u0060\nYou are executing a planned task for [project].\n\n## Task\n[Task title and description from selected_next_task]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria from selected_next_task or evaluator_handoff]\n\n## Context\n[Any relevant context from orchestration_context: related decision entries or caveats,\nhealth/TODO findings, prior task results, stale app/profile caveats, retry-state\nprovenance. Keep brief.]\n\n## Constraints\n- Execute ONLY this task. No scope creep.\n- Follow existing code patterns and conventions.\n- Use the host-provided worker facility (for example, Task) for the selected capability.\n- Commit your changes with a conventional commit message.\n- You are working on a plan-driven task. Update the task status in the plan artifact\n  to ■ complete when done.\n\u0060\u0060\u0060\n\nWait for the task-notification result.\n\n### Step 3: Evaluate\n\nEvaluation has two surfaces in sequence: an orchestrator-side presence check using latest progress verification, then an audit delegation whose prompt is extended with an evidence audit. Both surfaces must run before the task can be resolved.\n\n**Surface 1: Presence check from progress verification**\n\nWhen the delegated capability was build (or any capability that produces progress cycle entries), perform a cheap evidence presence check before spawning audit:\n\n1. Start with \u0060orchestration_context.progress_verification\u0060 and its \u0060latest_progress_verification_pointer\u0060.\n2. If unavailable or incomplete, run \u0060agentera state progress list --limit 20 --format json\u0060 before any raw artifact read.\n3. Look for a non-empty \u0060verified\u0060 field in the latest relevant progress entry.\n4. **Present and non-empty**: proceed to Surface 2.\n5. **Missing or empty**: treat the task as a failed evaluation. Go straight into Step 4's FAIL branch with \"missing or empty \u0060verified\u0060 field in progress Cycle N\" as the failure reason.\n\n**Surface 2: Audit delegation with evidence audit**\n\nOnce the presence check passes, spawn audit as a subagent to verify the work:\n\n\u0060\u0060\u0060\nYou are evaluating a completed task for [project].\n\n## Task that was completed\n[Task title and description from evaluator_handoff]\n\n## Acceptance criteria to verify\n[The task's Given/When/Then criteria from evaluator_handoff]\n\n## What to check\n- Verify each acceptance criterion against the current codebase state.\n- Check for unintended side effects from the implementation.\n- Verify the project's test/build suite still passes.\n\n## Verification evidence audit\n- Use the latest progress verification pointer and \u0060verified\u0060 evidence supplied by\n  the orchestration context or \u0060agentera state progress list --limit 20 --format json\u0060.\n- Compare the recorded evidence to the task's acceptance criteria.\n- Report whether the evidence substantiates the criteria or is merely trivially\n  populated (e.g., \"tests pass\" without any observation of the actual feature\n  running counts as insufficient).\n- If the field is \u0060N/A: <tag>\u0060, confirm the tag is drawn from the allowlist\n  (\u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060,\n  \u0060chore-build-config\u0060, \u0060test-only\u0060) AND that the tag fits the nature of the work.\n- If the field is a free-form N/A rationale, confirm it is at least 8 words long AND\n  actually explains why the change has no observable behavior.\n- Flag the task as FAIL on the evidence audit if the recorded \u0060verified\u0060 content\n  does not substantiate the acceptance criteria.\n\n## Source-contract caveats to preserve\n- Include compacted decision caveats, stale health/profile/app caveats, missing\n  state-family caveats, and retry-state provenance exactly as supplied.\n- Do not treat missing retry attempts as an attempt count. If status is\n  \u0060not_recorded\u0060 or \u0060unavailable\u0060, keep that status in the evaluation report.\n\n## Output format\nFor each acceptance criterion, report:\n- status: PASS or FAIL\n- evidence: what you checked and what you found\n- citation: \u0060<file>:<line>\u0060 OR \u0060not-applicable: <reason>\u0060 — **required for every FAIL row**\n- verify_command: exact \u0060grep\u0060 or \u0060git show\u0060 invocation — **required for every FAIL row\n  with a file:line citation**; the command must reproduce the evidence at the cited line\n\nUse \u0060orchestration_context.evaluator_handoff.output_requirements\u0060 from prime context as\nthe machine-readable citation contract. FAIL rows without a valid citation are incomplete\nand must be treated as evaluation failures.\n\nThen report the verification evidence audit outcome (PASS or FAIL with reasoning).\n\nThen give an overall verdict: PASS (all criteria met and evidence audit passed) or FAIL\n(any criterion failed or evidence audit failed).\n\u0060\u0060\u0060\n\nWait for the audit verdict.\n\n### Step 4: Resolve\n\nBased on audit's verdict:\n\n**PASS**: Mark the task \u0060■ complete\u0060 (VT1) in the plan artifact (if the delegated capability did not already do so). Proceed to Step 5.\n\n**FAIL (retries < 2)**: Increment the retry count. Re-delegate to the same capability with audit's findings as additional context:\n\n\u0060\u0060\u0060\nYou are retrying a task that failed evaluation for [project].\n\n## Original task\n[Task title and description]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria]\n\n## Evaluation findings (what failed)\n[Audit's failure report with evidence]\n\n## What to fix\nAddress each failure point. All acceptance criteria must pass on re-evaluation.\n\u0060\u0060\u0060\n\nReturn to Step 3.\n\n**FAIL (retries = 2)**: The task has exhausted its retry budget. Mark the task \u0060▨ blocked\u0060 (VT4) in the plan artifact. Log the failure to TODO.md with audit's findings as context. Proceed to Step 5.\n\nWhen writing to the plan artifact or TODO.md, use the task identity and caveats from \u0060orchestration_context\u0060. Do not refresh installed app/profile state, edit the vision artifact, or invent retry attempt counts.\n\n### Step 5: Log and loop\n\nCheck the plan state:\n\n- **More pending tasks with satisfied dependencies?** Return to Step 1.\n- **All tasks complete?** Return to Step 0 for completed-plan closure.\n- **Complete + blocked or incomplete tasks?** Keep the plan active and route to replanning or TODO logging; do not archive as successful completion.\n- **Context approaching budget limit?** Stop the session, report current progress.\n- **User interrupt?** Stop the session, report current progress.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT read implementation source code. The orchestrator delegates; it does not implement. Artifact files (\u0060.agentera/*.yaml\u0060, \u0060TODO.md\u0060) are state records, not source code; raw reads are last-resort after CLI context and listed fallback commands.\n- MUST NOT run tests, builds, linters, or implementation project commands directly. Delegated capabilities handle all verification.\n- MUST NOT modify the vision artifact. The orchestrator reads direction; it does not set it.\n- MUST NOT delegate to a capability without an active plan task justifying it (except during bootstrap in Step 0).\n- MUST NOT push to any remote. Local operations only.\n- MUST NOT retry a task more than 2 times. After the second failure, mark blocked and move on.\n- MUST NOT skip evaluation. Every completed task must be verified by audit before being marked complete.\n- MUST NOT make implementation decisions. Delegate to the appropriate capability.\n- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries. Orchestrate changes plan lifecycle state only through \u0060agentera state plan set-status ...\u0060 and \u0060agentera state plan archive\u0060.\n- MUST NOT research external patterns or libraries. Delegate to research.\n- MUST NOT mark, infer, or user-confirm final decision satisfaction. Only the user confirms. Preserve caveats for missing, compacted, open, provisional, or review-needed satisfaction state.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⎈ orchestrate · <status>\u0060 on its own line, followed by a summary sentence. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what needs attention.\n\n- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.\n- **flagged** (EX2): The plan was executed but with issues: one or more tasks were blocked after exhausting retries, or the post-plan health check revealed problems. Each concern is listed explicitly.\n- **stuck** (EX3): Cannot proceed because 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.\n- **waiting** (EX4): 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 delegated capability returned \u0060waiting\u0060 status requiring user input.\n\n### Loop stop condition\n\nEach task gets max 2 retries before being blocked. Additionally, if 3 consecutive different tasks all fail evaluation (even after their retries), orchestrate stops the session and escalates:\n\n1. **Stop**: do not delegate more tasks.\n2. **Log**: file the pattern to TODO.md with what was attempted across the 3 tasks and what appears systematically wrong.\n3. **Surface**: tell the user and recommend a course of action (e.g., \"⛶ audit for a full audit\", \"❈ discuss to reconsider the plan\", \"the plan may need replanning via ≡ plan\").\n\n---\n\n## Cross-capability integration\n\nOrchestrate is the orchestration layer that chains all other capabilities together. It delegates through the host-provided worker facility. Every supported runtime discovers Agentera through the canonical shared skill and uses the CLI for behavior and state; Agentera ships no runtime-native delegation descriptors. Orchestrator-side instructions, retry logic, and audit evaluation gating stay unchanged across runtimes; only the host-provided worker facility differs.\n\n### Delegation targets\n\n- **⧉ build**: Implementation, feature, fix, refactor tasks. Build runs its full cycle as a subagent and writes progress and changelog entries.\n- **⛶ audit**: Two roles — evaluator after each task completion (verifying acceptance criteria), and health checker after plan completion (producing health grades). Audit is the discriminator in the evaluate-then-proceed pattern.\n- **▤ document**: Documentation tasks — docs updates, README changes, documentation coverage.\n- **⬚ research**: Research tasks. During bootstrap, orchestrate chains research for vision-gap analysis before plan creates a plan.\n- **⎘ optimize**: Optimization-shaped tasks (metric improvement, performance tuning) route to optimize.\n- **◰ design**: Visual identity tasks (DESIGN.md updates, design token changes).\n- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.\n\n### State consumers\n\n- **❈ discuss**: Decision state provides firm constraints during task selection. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 from returned decision entries.\n- **⛺ vision**: Direction context during bootstrap. If vision is missing, preserve the caveat and ask before creating direction.\n- **♾ profile**: Persona context for calibrating delegation. Do not refresh profile state during orchestration; if unavailable, proceed without persona grounding and preserve the caveat.\n\n### When to use orchestrate\n\nExecute an existing plan: create the plan first (\u0060/agentera plan\u0060), then run \u0060/agentera orchestrate\u0060 to execute it with evaluation gating.\n\nFull autonomous session: \u0060/agentera orchestrate\u0060 with no plan triggers bootstrap (research → plan → execute).\n\nAfter a deliberation: \u0060/agentera discuss\u0060 → \u0060/agentera plan\u0060 → \u0060/agentera orchestrate\u0060.\n\nUse orchestrate instead of a host loop for plan-aware, evaluated, multi-cycle execution. Use it when the user explicitly requests autonomous multi-task execution.\n"`);
 export default `${instructions
     .replace(/## State artifacts[\s\S]*?## The orchestration loop/, `## State artifacts
 
@@ -12,7 +12,27 @@ Advance tasks with \`agentera state plan set-status --id ID\` and persist evalua
     .replaceAll("--number N", "--id ID")
     .replaceAll("--task N", "--id ID")
     .replace("task N · step M/5", "task ID · step M/5")
-    .replace("N is the task number from the selected orchestration context task.", "ID is the bare ID from the selected orchestration context task.")}
+    .replace("N is the task number from the selected orchestration context task.", "ID is the bare ID from the selected orchestration context task.")
+    .replace(/- \*\*Plan exists, `header\.status: complete`, and all tasks complete\*\*:[\s\S]*?---\n\nStep markers/, () => [
+    "- **Plan exists, `active: true` and `complete_plan: true`**: terminal-open closure. This is not bootstrap. Keep the plan open while completing the closure sequence; do not call the archive route.",
+    "- **Plan exists, but blocked or incomplete tasks remain**: do not complete it as successful work. Route to the orchestration loop or replanning so incomplete evidence stays visible.",
+    "- **Plan exists, tasks pending**: proceed to the loop using `orchestration_context` task selection.",
+    "",
+    "**Terminal-open closure sequence**: complete every step while `active: true` and `complete_plan: true`.",
+    "",
+    "1. **Assess staleness**: identify delegated capabilities from plan task history and progress summary in CLI context. For each expected artifact, compare `git log -1 --format=%aI -- <path>` with the plan creation date. An artifact is stale only when its owner was delegated and it was not modified since that date.",
+    "2. **Delegate Audit**: request a limited post-plan health result covering the staleness assessment and closure evidence. Preserve source-contract caveats and require PASS or WARN/FAIL findings with evidence.",
+    "3. **PASS only — publish health before plan completion**: discover `agentera state health explain --verb append --format json`, then publish one typed health record with `agentera state health append --input PATH --format json`. Use only the canonical `artifact_freshness` dimension. Its summary and evidence state the terminal-task scope, staleness result, and Audit verdict; do not represent this limited closure check as a codebase-wide audit.",
+    "4. **PASS only — complete the open plan**: after the health writer confirms publication, run `agentera state plan set-plan-status --status complete --format json`. Do not call `agentera state plan archive`; archive history is not part of terminal-open closure.",
+    "5. **WARN or FAIL requiring follow-up**: keep the plan open, surface the cited finding and staleness context, and route it to the applicable task/replanning path. Do not publish a PASS closure record, complete the plan, or call an archive route.",
+    "",
+    "---",
+    "",
+    "Step markers",
+].join("\n"))
+    .replace("- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries. Orchestrate changes plan lifecycle state only through `agentera state plan set-status ...` and `agentera state plan archive`.", "- MUST NOT write to progress or changelog. Dispatched capabilities write their own entries. During terminal-open closure only, Orchestrate may publish the limited typed health record, then change plan lifecycle state through `agentera state plan set-plan-status --status complete --format json`; it MUST NOT invoke the archive route.")
+    .replace("- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.", "- **complete** (EX1): All plan tasks are terminal, the limited health check passed, its typed health record was published, and the open plan was set complete without archiving.")
+    .replace("- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.", "- **≡ plan**: When no plan exists, including after successful terminal-open closure removes the active plan from selection, orchestrate invokes plan to create the next plan.")}
 
 ## Evaluation Retry State
 

package/dist/capabilities/orchestrate/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../../../../home/jgabor/git/agentera/packages/cli/src/capabilities/orchestrate/instructions.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gtnBAAgtnB,CAAC,CAAC;AAC3wnB,eAAe,GAAG,YAAY;KAC3B,OAAO,CAAC,qDAAqD,EAAE;;;;;;0BAMxC,CAAC;KACxB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,OAAO,CAAC,mBAAmB,EAAE,oBAAoB,CAAC;KAClD,OAAO,CAAC,oEAAoE,EAAE,iEAAiE,CAAC;;;;;CAKlJ,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../../../../home/jgabor/git/agentera/packages/cli/src/capabilities/orchestrate/instructions.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ijnBAAijnB,CAAC,CAAC;AAC5mnB,eAAe,GAAG,YAAY;KAC3B,OAAO,CAAC,qDAAqD,EAAE;;;;;;0BAMxC,CAAC;KACxB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,OAAO,CAAC,mBAAmB,EAAE,oBAAoB,CAAC;KAClD,OAAO,CAAC,oEAAoE,EAAE,iEAAiE,CAAC;KAChJ,OAAO,CAAC,uGAAuG,EAAE,GAAG,EAAE,CAAC;IACtH,qMAAqM;IACrM,uLAAuL;IACvL,qGAAqG;IACrG,EAAE;IACF,yGAAyG;IACzG,EAAE;IACF,2TAA2T;IAC3T,iNAAiN;IACjN,gcAAgc;IAChc,sQAAsQ;IACtQ,uPAAuP;IACvP,EAAE;IACF,KAAK;IACL,EAAE;IACF,cAAc;CACf,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACZ,OAAO,CACN,8PAA8P,EAC9P,+UAA+U,CAChV;KACA,OAAO,CACN,uIAAuI,EACvI,kLAAkL,CACnL;KACA,OAAO,CACN,sHAAsH,EACtH,+KAA+K,CAChL;;;;;CAKF,CAAC"}