agentera 3.0.0-dev.14 → 3.0.0-dev.15

package/bundle/skills/agentera/SKILL.md

@@ -117,7 +117,8 @@ Proceed/Cancel handoff.
 - NEVER push to remote repos without explicit user instruction
 - NEVER modify `.agentera/vision.yaml` or objective state during execution cycles (only the user or the owning capability may change these)
 - NEVER commit secrets or credentials to any artifact or file
-- Respect artifact path resolution: check `.agentera/docs.yaml` for path overrides before accessing any agent-facing artifact
+- For supported mutations, use the state writer; it resolves `.agentera/docs.yaml` path overrides and validates the published bytes
+- For direct access to other agent-facing artifacts, respect `.agentera/docs.yaml` path overrides
 </critical>
 
 ---
@@ -141,9 +142,49 @@ Proceed/Cancel handoff.
 
 ---
 
+## Artifact writes
+
+The CLI state writer is the canonical mutation path for `progress`, `decisions`,
+`plan`, and `health`. Do not hand-edit those artifacts during normal capability
+execution. The writer assigns numbers, validates schema fields, honors docs-mapped
+paths, serializes concurrent writes, compacts where required, and supports
+filesystem-safe previews.
+
+Discover the live contract before constructing a write:
+
+```bash
+agentera state decisions explain --format json
+agentera state decisions explain --verb update --format json
+```
+
+The same pattern applies to every writable artifact:
+
+```bash
+agentera state <progress|decisions|plan|health> explain --verb <verb> --format json
+```
+
+Common mutations:
+
+- `agentera state progress append ... --format json`
+- `agentera state decisions append ... --format json`
+- `agentera state decisions update --number N ... --format json`
+- `agentera state plan create --input plan.yaml --format json`
+- `agentera state plan append|update|set-status ... --format json`
+- `agentera state plan archive --format json`
+- `agentera state health append --input audit.yaml --format json`
+
+Add `--dry-run` to preview any mutation without publishing it. Artifacts not
+listed above are outside the typed writer contract and remain governed by their
+owning capability's instructions and safety rails. `agentera schema --format
+json` exposes the machine-readable writer operation matrix under
+`state_writer` and on each writable `artifact_schemas[*].write_interface`.
+
+---
+
 ## Artifact path resolution
 
-Before reading or writing any artifact, check if `.agentera/docs.yaml` exists.
+The state writer resolves path mappings itself. Before directly reading or
+writing an artifact outside the writer contract, check if `.agentera/docs.yaml` exists.
 If it has an Artifact Mapping section, use the path specified for each canonical
 filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given
 artifact, use the default layout:

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

@@ -69,7 +69,7 @@ BUDGET:
 COMPACTION:
   1:
     id: DX1
-    rule: uniform_20_50_100
+    rule: uniform_10_40_50
     description: >-
       Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
       entries, 40 one-line archive entries, drop beyond 50 total.

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

@@ -75,7 +75,7 @@ BUDGET:
 COMPACTION:
   1:
     id: EX_CMP1
-    rule: uniform_20_50_100
+    rule: uniform_10_40_50
     description: >-
       Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
       entries, 40 one-line archive entries, drop beyond 50 total.

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

@@ -87,7 +87,7 @@ BUDGET:
 COMPACTION:
   1:
     id: HX1
-    rule: uniform_20_50_100
+    rule: uniform_10_40_50
     description: >-
       Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
       entries, 40 one-line archive entries, drop beyond 50 total.

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

@@ -72,7 +72,7 @@ BUDGET:
 COMPACTION:
   1:
     id: PX1
-    rule: uniform_20_50_100
+    rule: uniform_10_40_50
     description: >-
       Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
       entries, 40 one-line archive entries, drop beyond 50 total.

package/dist/capabilities/audit/instructions.js

@@ -1,4 +1,4 @@
 // Markdown instructions served via agentera prime --context audit --format json
-export const instructions = JSON.parse(String.raw `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger? Each invocation = one audit. Findings feed build's work selection via TODO.md.\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\nLean on \u0060evidence_context.source_contract\u0060 from \u0060agentera prime --context audit --format json\u0060 for evaluation startup. Do not re-encode its machine-readable rules in prose.\n\n---\n\n## State artifacts\n\n| Artifact | Role | Path |\n|----------|------|------|\n| health | produces_and_consumes | \u0060.agentera/health.yaml\u0060 |\n| todo | produces_and_consumes | TODO.md |\n| decisions | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| progress | consumes | \u0060.agentera/progress.yaml\u0060 |\n| plan | consumes | \u0060.agentera/plan.yaml\u0060 |\n| docs | consumes | \u0060.agentera/docs.yaml\u0060 |\n| vision | consumes (protected) | \u0060.agentera/vision.yaml\u0060 |\n| design | consumes (optional) | DESIGN.md |\n| profile | consumes | Profile state from \u0060evidence_context.residual_risks\u0060 |\n\n### health.yaml shape\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\nEvery finding MUST include \u0060location\u0060, \u0060evidence\u0060, \u0060impact\u0060, \u0060suggested_action\u0060, and \u0060confidence\u0060. WARN and FAIL findings MUST carry a reproducible anchor: \u0060location: <file>:<line>\u0060 (or \u0060not-applicable: <reason>\u0060). WARN rows with file:line citations SHOULD include \u0060verify_command\u0060 — the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line. Prose-only evidence for WARN/FAIL findings is incomplete.\n\n### Evidence context startup\n\nStart with \u0060agentera prime --context audit --format json\u0060. Use the returned \u0060evidence_context\u0060 for prior audit findings, known issues, decision caveats, protected-state boundaries, version checks, progress verification, and residual risks. If \u0060evidence_context\u0060 is absent or caveated for a state family you need, run the listed \u0060fallback_commands\u0060 first. Raw artifact reads are last-resort diagnostics, not normal startup behavior. Preserve caveats — they calibrate confidence, not approval to refresh state, read vision, edit objective state, or contact remotes.\n\n---\n\n## Workflow phases\n\nLinear: orient, select, assess, distill, report, connect.\n\n### Step 1: Orient\n\nUse \u0060evidence_context\u0060 for prior audits, decisions, TODO, and progress. Then project discovery: map directory structure, read dependency manifests, README, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060.\n\nDerive change magnitude: \u0060git log --stat\u0060 on commits since the last audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n\nList key structural facts (module boundaries, dependency patterns, test coverage gaps) in your response. These survive context compaction.\n\n**Exit-early stop condition**: if \u0060git diff\u0060 since the last audit timestamp shows no file changes, report \u0060─── ⛶ audit · complete ───\u0060 with \"no changes since last audit\" and stop.\n\n### Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI does not need the same audit as a monorepo.\n\n#### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| Architecture alignment | Does the code match stated architecture? Pattern mismatches, module boundary violations, layering breaks. | \u0060.agentera/vision.yaml\u0060 or README describes architecture |\n| Pattern consistency | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| Complexity hotspots | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing. | Project has tests |\n| Dependency health | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| Version health | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since last version bump. | \u0060.agentera/docs.yaml\u0060 has a \u0060versioning\u0060 convention block |\n| Artifact freshness | Are state artifacts current relative to plan activity or recent development? Detects artifacts that should have been updated but weren't. | Plan context available or progress has entries |\n| Prose health | Do artifact entries respect writing rules? Verbosity overruns, abstraction creep, filler. | Project has 3+ artifact files |\n| Security hygiene | Hardcoded secrets, dangerous calls, injection patterns. Lightweight regex scan. | Any codebase |\n\n#### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence depth.\n\nThese thresholds are guidelines, not hard rules. A 6-file change touching a critical security module warrants thorough depth.\n\n**User-specified dimensions**: audit only those. **Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n### Step 3: Assess\n\nFor each selected dimension, run analysis and produce structured findings. Every finding MUST include: specific file and line references, quoted code or structural observation, explanation of why it matters, and confidence score (0-100, protocol: CS1-CS5).\n\nFor parallel analysis, use subagents — one per dimension. Each agent receives the dimension definition, relevant context files, and instructions to return findings matching the health.yaml finding shape.\n\n#### Version health\n\nOnly run if \u0060.agentera/docs.yaml\u0060 contains a \u0060versioning\u0060 convention block. Skip entirely if absent.\n\n- Read the \u0060versioning\u0060 convention to identify version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits since the last bump, this dimension is healthy with no finding\n\n#### Artifact freshness\n\nEvaluates whether state artifacts are current relative to plan activity or recent development.\n\n**With plan context** (\u0060.agentera/plan.yaml\u0060 has a created date and task history):\n\n- Read the plan's \u0060Created\u0060 date from its metadata\n- Identify dispatched capabilities by scanning task entries and progress cycle logs\n- For each dispatched capability, look up its expected artifacts in the staleness convention\n- Check each expected artifact's last modification: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the owning capability was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context**:\n\n- Fall back to progress recency: an artifact is potentially stale if not modified since the most recent progress cycle entry date\n- If progress has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). Advisory, not authoritative.\n\nStale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n#### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules:\n\n- **Rule 1: Verbosity overrun** — approximate word count per entry. Entries exceeding their budget by 50%+ are findings.\n- **Rule 2: Abstraction creep** — scan each entry for ≥1 concrete anchor (file path, line number, commit hash 7+ hex chars, metric value with unit, identifier, direct quote). Entries with zero concrete anchors are findings.\n- **Rule 3: Filler accumulation** — flag entries with: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\nUse \u0060agentera state decisions --format json\u0060 for decision artifact prose context; preserve returned caveats. Read all project artifacts (\u0060.agentera/progress.yaml\u0060, \u0060.agentera/decisions.yaml\u0060, \u0060.agentera/plan.yaml\u0060, \u0060.agentera/health.yaml\u0060, TODO.md, CHANGELOG.md, \u0060.agentera/vision.yaml\u0060, DESIGN.md, \u0060.agentera/docs.yaml\u0060) when this dimension requires raw artifact prose inspection.\n\n#### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. Surface-level check, not a replacement for dedicated security analysis.\n\nScan for hardcoded secrets (API key patterns, token strings, private keys), dangerous function calls (\u0060eval()\u0060 on variables, \u0060exec()\u0060 with string concatenation, subprocess with unsanitized input), and injection patterns (SQL string concatenation, unsanitized shell construction). Use Grep across source files; exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060.\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\nEvery security hygiene finding MUST include a footer recommending dedicated security tools.\n\n### Step 4: Distill\n\nAfter analysis completes:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against \u0060.agentera/decisions.yaml\u0060 and TODO.md (via \u0060agentera state decisions --format json\u0060):\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension: **A** (no critical/warning), **B** (no critical, some warnings), **C** (1-2 critical or many warnings), **D** (multiple critical), **F** (pervasive critical).\n5. **Trajectory**: compare to prior audit — improving (VT12), degrading (VT13), stable. Calculate overall trajectory.\n\n### Step 5: Report\n\nRun \u0060agentera check lint --artifact health\u0060 on the draft entry before writing. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite grade, trajectory marker, and finding summary per dimension to \u0060.agentera/health.yaml\u0060 (append new audit, keep prior for trajectory history). No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nWhen updating existing entries, edit the specific YAML entry rather than rewriting unrelated history.\n\nApply compaction rules before writing if thresholds exceeded: keep 10 full audits, up to 40 one-line archive entries, drop beyond 50 total.\n\n#### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted — the \"what IS\" independent of what's stated.]\n\u0060\u0060\u0060\n\n### Step 6: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section. Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n2. **\u0060.agentera/vision.yaml\u0060**: if architecture has intentionally evolved past stated architecture, suggest updating via discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT modify source code. Audit audits; other capabilities fix.\n- MUST NOT file findings to TODO.md without explicit user confirmation.\n- MUST NOT present speculative findings (confidence < 50) as definitive problems.\n- MUST NOT flag findings that contradict deliberate decisions documented in \u0060.agentera/decisions.yaml\u0060. A deliberate decision is an implementation of intent, not a finding. Discard or downgrade.\n- MUST NOT report issues already tracked in TODO.md as new findings.\n- MUST NOT flag subjective style preferences as findings unless they violate stated principles in \u0060.agentera/vision.yaml\u0060, AGENTS.md, or the decision profile.\n- MUST NOT run destructive commands or install packages. Read-only assessment.\n- MUST NOT mark, infer, or user-confirm decision satisfaction — only the user confirms final satisfaction.\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─── ⛶ audit · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected dimensions assessed, findings synthesized, grades assigned, \u0060health\u0060 artifact updated, actionable results presented.\n- **flagged** (EX2): Completed with notable caveats — dimensions skipped due to missing tooling, confidence too low to grade reliably, or critical findings require urgent attention beyond audit scope.\n- **stuck** (EX3): Cannot complete — project inaccessible, required language tooling unavailable and manual analysis not feasible, or filing to TODO.md declined with no safe way to surface results.\n- **waiting** (EX4): The audit target is ambiguous — no project identified, codebase too incomplete to assess, or dimensions requested cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is the feedback loop: it tells build whether its work is making things better.\n\n### Feeds\n\n- **⧉ build**: Critical and warning findings filed to TODO.md become candidates for build's work selection. \"Patterns Observed\" helps build understand the codebase's de facto architecture when planning changes.\n- **❈ discuss**: When an architecture mismatch is found, suggest discuss before fixes begin.\n- **≡ plan**: When multiple related structural issues are found, suggest plan for a remediation plan.\n- **⎘ optimize**: When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), suggest optimize.\n\n### Reads\n\n- **⧉ build output**: \u0060.agentera/progress.yaml\u0060 tells audit what was built recently. Recent changes are higher-priority audit targets.\n- **❈ discuss output**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Findings that contradict deliberate decisions are not findings.\n- **◰ design output**: DESIGN.md provides identity constraints that audit can check for consistency.\n\n### Informed by\n\n- **♾ profile**: The decision profile calibrates what \"healthy\" means for this user. High-confidence quality preferences weight the grading.\n\n### Getting started\n\n**First audit**: \u0060/agentera audit\u0060 runs a full audit across all applicable dimensions, bootstraps \u0060health\u0060 artifact. Review findings, file critical ones to TODO.md, then \u0060/agentera build\u0060 picks them up.\n\n**Periodic health checks**: run audit every 5-10 build cycles, or when a major feature was added, significant refactoring occurred, the codebase feels harder to work in, or before a major architectural decision.\n\nStaleness detection: \u0060agentera prime\u0060 marks a health audit stale when \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10) since the last audit is exceeded. Either axis exceeding its threshold triggers staleness; when progress is absent, time-only evaluation still applies.\n\n**Targeted audits**: specify dimensions to narrow scope — \u0060/agentera audit architecture coupling\u0060.\n\n**After an audit**: Good grades (A/B) — keep building. Mixed (C) — file criticals, deliberate on warnings. Poor (D/F) — consider pausing feature work; use discuss for priorities, then build for structural fixes.\n\n### Orchestrate evaluation\n\nWARN and FAIL findings used by orchestrate evaluation reports MUST carry \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)."`);
+export const instructions = JSON.parse(String.raw `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger? Each invocation = one audit. Findings feed build's work selection via TODO.md.\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\nLean on \u0060evidence_context.source_contract\u0060 from \u0060agentera prime --context audit --format json\u0060 for evaluation startup. Do not re-encode its machine-readable rules in prose.\n\n---\n\n## State artifacts\n\n| Artifact | Role | Path |\n|----------|------|------|\n| health | produces_and_consumes | \u0060.agentera/health.yaml\u0060 |\n| todo | produces_and_consumes | TODO.md |\n| decisions | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| progress | consumes | \u0060.agentera/progress.yaml\u0060 |\n| plan | consumes | \u0060.agentera/plan.yaml\u0060 |\n| docs | consumes | \u0060.agentera/docs.yaml\u0060 |\n| vision | consumes (protected) | \u0060.agentera/vision.yaml\u0060 |\n| design | consumes (optional) | DESIGN.md |\n| profile | consumes | Profile state from \u0060evidence_context.residual_risks\u0060 |\n\n### health.yaml shape\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\nEvery finding MUST include \u0060location\u0060, \u0060evidence\u0060, \u0060impact\u0060, \u0060suggested_action\u0060, and \u0060confidence\u0060. WARN and FAIL findings MUST carry a reproducible anchor: \u0060location: <file>:<line>\u0060 (or \u0060not-applicable: <reason>\u0060). WARN rows with file:line citations SHOULD include \u0060verify_command\u0060 — the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line. Prose-only evidence for WARN/FAIL findings is incomplete.\n\n### Evidence context startup\n\nStart with \u0060agentera prime --context audit --format json\u0060. Use the returned \u0060evidence_context\u0060 for prior audit findings, known issues, decision caveats, protected-state boundaries, version checks, progress verification, and residual risks. If \u0060evidence_context\u0060 is absent or caveated for a state family you need, run the listed \u0060fallback_commands\u0060 first. Raw artifact reads are last-resort diagnostics, not normal startup behavior. Preserve caveats — they calibrate confidence, not approval to refresh state, read vision, edit objective state, or contact remotes.\n\n---\n\n## Workflow phases\n\nLinear: orient, select, assess, distill, report, connect.\n\n### Step 1: Orient\n\nUse \u0060evidence_context\u0060 for prior audits, decisions, TODO, and progress. Then project discovery: map directory structure, read dependency manifests, README, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060.\n\nDerive change magnitude: \u0060git log --stat\u0060 on commits since the last audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n\nList key structural facts (module boundaries, dependency patterns, test coverage gaps) in your response. These survive context compaction.\n\n**Exit-early stop condition**: if \u0060git diff\u0060 since the last audit timestamp shows no file changes, report \u0060─── ⛶ audit · complete ───\u0060 with \"no changes since last audit\" and stop.\n\n### Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI does not need the same audit as a monorepo.\n\n#### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| Architecture alignment | Does the code match stated architecture? Pattern mismatches, module boundary violations, layering breaks. | \u0060.agentera/vision.yaml\u0060 or README describes architecture |\n| Pattern consistency | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| Complexity hotspots | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing. | Project has tests |\n| Dependency health | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| Version health | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since last version bump. | \u0060.agentera/docs.yaml\u0060 has a \u0060versioning\u0060 convention block |\n| Artifact freshness | Are state artifacts current relative to plan activity or recent development? Detects artifacts that should have been updated but weren't. | Plan context available or progress has entries |\n| Prose health | Do artifact entries respect writing rules? Verbosity overruns, abstraction creep, filler. | Project has 3+ artifact files |\n| Security hygiene | Hardcoded secrets, dangerous calls, injection patterns. Lightweight regex scan. | Any codebase |\n\n#### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence depth.\n\nThese thresholds are guidelines, not hard rules. A 6-file change touching a critical security module warrants thorough depth.\n\n**User-specified dimensions**: audit only those. **Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n### Step 3: Assess\n\nFor each selected dimension, run analysis and produce structured findings. Every finding MUST include: specific file and line references, quoted code or structural observation, explanation of why it matters, and confidence score (0-100, protocol: CS1-CS5).\n\nFor parallel analysis, use subagents — one per dimension. Each agent receives the dimension definition, relevant context files, and instructions to return findings matching the health.yaml finding shape.\n\n#### Version health\n\nOnly run if \u0060.agentera/docs.yaml\u0060 contains a \u0060versioning\u0060 convention block. Skip entirely if absent.\n\n- Read the \u0060versioning\u0060 convention to identify version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits since the last bump, this dimension is healthy with no finding\n\n#### Artifact freshness\n\nEvaluates whether state artifacts are current relative to plan activity or recent development.\n\n**With plan context** (\u0060.agentera/plan.yaml\u0060 has a created date and task history):\n\n- Read the plan's \u0060Created\u0060 date from its metadata\n- Identify dispatched capabilities by scanning task entries and progress cycle logs\n- For each dispatched capability, look up its expected artifacts in the staleness convention\n- Check each expected artifact's last modification: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the owning capability was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context**:\n\n- Fall back to progress recency: an artifact is potentially stale if not modified since the most recent progress cycle entry date\n- If progress has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). Advisory, not authoritative.\n\nStale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n#### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules:\n\n- **Rule 1: Verbosity overrun** — approximate word count per entry. Entries exceeding their budget by 50%+ are findings.\n- **Rule 2: Abstraction creep** — scan each entry for ≥1 concrete anchor (file path, line number, commit hash 7+ hex chars, metric value with unit, identifier, direct quote). Entries with zero concrete anchors are findings.\n- **Rule 3: Filler accumulation** — flag entries with: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\nUse \u0060agentera state decisions --format json\u0060 for decision artifact prose context; preserve returned caveats. Read all project artifacts (\u0060.agentera/progress.yaml\u0060, \u0060.agentera/decisions.yaml\u0060, \u0060.agentera/plan.yaml\u0060, \u0060.agentera/health.yaml\u0060, TODO.md, CHANGELOG.md, \u0060.agentera/vision.yaml\u0060, DESIGN.md, \u0060.agentera/docs.yaml\u0060) when this dimension requires raw artifact prose inspection.\n\n#### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. Surface-level check, not a replacement for dedicated security analysis.\n\nScan for hardcoded secrets (API key patterns, token strings, private keys), dangerous function calls (\u0060eval()\u0060 on variables, \u0060exec()\u0060 with string concatenation, subprocess with unsanitized input), and injection patterns (SQL string concatenation, unsanitized shell construction). Use Grep across source files; exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060.\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\nEvery security hygiene finding MUST include a footer recommending dedicated security tools.\n\n### Step 4: Distill\n\nAfter analysis completes:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against \u0060.agentera/decisions.yaml\u0060 and TODO.md (via \u0060agentera state decisions --format json\u0060):\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension: **A** (no critical/warning), **B** (no critical, some warnings), **C** (1-2 critical or many warnings), **D** (multiple critical), **F** (pervasive critical).\n5. **Trajectory**: compare to prior audit — improving (VT12), degrading (VT13), stable. Calculate overall trajectory.\n\n### Step 5: Report\n\nRun \u0060agentera check lint --artifact health\u0060 on the draft entry before writing. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the audit entry with \u0060agentera state health append --input PATH --format json\u0060 (or \u0060--input -\u0060 for YAML/JSON stdin). The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nWhen updating existing entries, edit the specific YAML entry rather than rewriting unrelated history.\n\nCompaction is writer-owned; do not hand-compact the health artifact before or after the command.\n\n#### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted — the \"what IS\" independent of what's stated.]\n\u0060\u0060\u0060\n\n### Step 6: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section. Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n2. **\u0060.agentera/vision.yaml\u0060**: if architecture has intentionally evolved past stated architecture, suggest updating via discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT modify source code. Audit audits; other capabilities fix.\n- MUST NOT file findings to TODO.md without explicit user confirmation.\n- MUST NOT present speculative findings (confidence < 50) as definitive problems.\n- MUST NOT flag findings that contradict deliberate decisions documented in \u0060.agentera/decisions.yaml\u0060. A deliberate decision is an implementation of intent, not a finding. Discard or downgrade.\n- MUST NOT report issues already tracked in TODO.md as new findings.\n- MUST NOT flag subjective style preferences as findings unless they violate stated principles in \u0060.agentera/vision.yaml\u0060, AGENTS.md, or the decision profile.\n- MUST NOT run destructive commands or install packages. Read-only assessment.\n- MUST NOT mark, infer, or user-confirm decision satisfaction — only the user confirms final satisfaction.\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─── ⛶ audit · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected dimensions assessed, findings synthesized, grades assigned, \u0060health\u0060 artifact updated, actionable results presented.\n- **flagged** (EX2): Completed with notable caveats — dimensions skipped due to missing tooling, confidence too low to grade reliably, or critical findings require urgent attention beyond audit scope.\n- **stuck** (EX3): Cannot complete — project inaccessible, required language tooling unavailable and manual analysis not feasible, or filing to TODO.md declined with no safe way to surface results.\n- **waiting** (EX4): The audit target is ambiguous — no project identified, codebase too incomplete to assess, or dimensions requested cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is the feedback loop: it tells build whether its work is making things better.\n\n### Feeds\n\n- **⧉ build**: Critical and warning findings filed to TODO.md become candidates for build's work selection. \"Patterns Observed\" helps build understand the codebase's de facto architecture when planning changes.\n- **❈ discuss**: When an architecture mismatch is found, suggest discuss before fixes begin.\n- **≡ plan**: When multiple related structural issues are found, suggest plan for a remediation plan.\n- **⎘ optimize**: When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), suggest optimize.\n\n### Reads\n\n- **⧉ build output**: \u0060.agentera/progress.yaml\u0060 tells audit what was built recently. Recent changes are higher-priority audit targets.\n- **❈ discuss output**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Findings that contradict deliberate decisions are not findings.\n- **◰ design output**: DESIGN.md provides identity constraints that audit can check for consistency.\n\n### Informed by\n\n- **♾ profile**: The decision profile calibrates what \"healthy\" means for this user. High-confidence quality preferences weight the grading.\n\n### Getting started\n\n**First audit**: \u0060/agentera audit\u0060 runs a full audit across all applicable dimensions, bootstraps \u0060health\u0060 artifact. Review findings, file critical ones to TODO.md, then \u0060/agentera build\u0060 picks them up.\n\n**Periodic health checks**: run audit every 5-10 build cycles, or when a major feature was added, significant refactoring occurred, the codebase feels harder to work in, or before a major architectural decision.\n\nStaleness detection: \u0060agentera prime\u0060 marks a health audit stale when \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10) since the last audit is exceeded. Either axis exceeding its threshold triggers staleness; when progress is absent, time-only evaluation still applies.\n\n**Targeted audits**: specify dimensions to narrow scope — \u0060/agentera audit architecture coupling\u0060.\n\n**After an audit**: Good grades (A/B) — keep building. Mixed (C) — file criticals, deliberate on warnings. Poor (D/F) — consider pausing feature work; use discuss for priorities, then build for structural fixes.\n\n### Orchestrate evaluation\n\nWARN and FAIL findings used by orchestrate evaluation reports MUST carry \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)."`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,yrmBAAyrmB,CAAC,CAAC;AACpvmB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,uwmBAAuwmB,CAAC,CAAC;AACl0mB,eAAe,YAAY,CAAC"}

package/dist/capabilities/build/instructions.js

@@ -1,5 +1,5 @@
 // Capability instructions for build
 // Served via `agentera prime --context build --format json`. RFC 2119 modal vocab.
-export const instructions = JSON.parse(String.raw `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\n\nGlyph: \u29c9 (protocol ref: SG2).\n\nAn autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.\n\nEach invocation = one cycle. After completing a cycle (orient through log, exit signal reported), **stop**. The next cycle starts only when the user explicitly requests it or switches to \u2388 orchestrate for autonomous multi-task execution. A compaction-continue prompt is not consent to start a new cycle.\n\nWhen offering execution mode choices after plan completion, label \u0060build\u0060 as \"one task, then stop\" and \u2388 orchestrate as \"all tasks autonomously.\"\n\n---\n\n## State artifacts\n\nBuild reads project state and writes progress, TODO, and changelog. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060progress\u0060 | produces | \u0060.agentera/progress.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | produces_and_consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### progress.yaml\n\n\u0060\u0060\u0060yaml\ncycles:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    type: feat\n    phase: build\n    what: One-line summary of what shipped.\n    inspiration: External source, if any.\n    discovered: Issues or ideas found.\n    verified: Observed output, N/A tag, or rationale.\n    next: Most valuable next work.\n    context:\n      intent: Why this cycle happened.\n      constraints: What had to stay true.\n      unknowns: What remains uncertain.\n      scope: What changed.\narchive: []\n\u0060\u0060\u0060\n\nThe \u0060verified\u0060 field is mandatory for every cycle entry.\n\n### CHANGELOG.md\n\nPublic-facing change history. Keep-a-changelog format. Build appends entries under \u0060## [Unreleased]\u0060 based on commit type: \u0060feat\u0060 \u2192 Added, \u0060refactor/chore\u0060 \u2192 Changed, \u0060fix\u0060 \u2192 Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Workflow phases: The cycle\n\n### Vision bootstrap\n\nIf the vision artifact is absent and \u26e5 vision is not installed, ask the user for project direction inline (one question: \"What does this software make possible?\"). Write the answer to \u0060.agentera/vision.yaml\u0060 and proceed to the cycle. If \u26e5 vision is installed and the artifact is absent, suggest \u26e5 vision and wait for confirmation. In all other cases, skip straight to the cycle.\n\n### The cycle\n\nStep markers: display \u0060\u2500\u2500 step N/8: verb\u0060 before each step.\nSteps: orient, select, research, plan, dispatch, verify, commit, log.\n\n### Step 1: Orient\n\nStart from the Build execution-context seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context build --format json\n\u0060\u0060\u0060\n\nIf \u0060execution_context.source_contract.complete_for_execution_context\u0060 is true, use \u0060execution_context\u0060 and included \u0060capability_context.state\u0060 as normal startup context. Do not read raw plan, progress, TODO, docs, health, decisions, changelog, vision, profile, or design artifacts to re-check selected work, acceptance criteria, constraints, verification expectations, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the cycle report and run the listed \u0060execution_context.fallback_commands\u0060 before any last-resort raw artifact diagnostic.\n\n#### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents MAY mark provisional satisfaction with evidence only. Build MUST NOT mark or imply user-confirmed satisfaction; only the user confirms final satisfaction. Missing, compacted, open, provisional, or review-needed satisfaction state remains a caveat and review pressure in the cycle report \u2014 automation MUST NOT reconstruct hidden outcomes or claim it proved user intent.\n\n#### Context consumption\n\nConsume these \u0060execution_context\u0060 fields:\n\n- \u0060work_selection\u0060: selected task or no-plan/completed-plan mode\n- \u0060acceptance_criteria\u0060: exact criteria for this cycle\n- \u0060constraints\u0060: plan constraints and protected-action boundaries\n- \u0060verification_expectations\u0060: expected validation and latest progress evidence\n- \u0060artifact_update_requirements\u0060: plan, TODO, changelog, and progress update obligations\n- \u0060changelog_boundary\u0060: current public-history boundary or fallback\n- \u0060scope_boundary\u0060: artifact-family scope and conservative source-file scope\n\nUse \u0060status.profile\u0060 for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.\n\n#### Project discovery\n\nOn cycle 1 or when unfamiliar with the project:\n\n- Map the directory structure\n- Read dependency manifests and README.md, AGENTS.md\n- Identify build/test/lint commands\n- Read key source files to understand architecture\n\nRun \u0060git log --oneline -20\u0060 for recent changes.\n\nBefore proceeding, list the 3-5 facts that determine this cycle.\n\n**Exit-early stop condition (plan-driven mode only)**: If \u0060.agentera/plan.yaml\u0060 has \u0060header.status: complete\u0060 and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not complete and MUST remain visible for replanning.\n\nSweep checklist:\n\n1. **progress.yaml aggregate cycle entry**: insert a newest-first cycle entry summarizing the whole plan.\n2. **CHANGELOG.md plan-level entries**: verify \u0060## [Unreleased]\u0060 covers each completed task's user-facing impact.\n3. **TODO.md milestone advance**: mark each plan task as \u0060## \u2713 Resolved\u0060.\n4. **health.yaml cross-reference**: mention any resolved findings.\n\nAfter the sweep, archive the plan to \u0060.agentera/archive/PLAN-{date}-{slug}.yaml\u0060, preserve lineage/evidence in the archive or next plan's \u0060previous_plan_archived\u0060, remove the active \u0060.agentera/plan.yaml\u0060, and report exit signal \u0060complete: plan finished\u0060.\n\n### Step 2: Pick work\n\nChoose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.\n\nEach cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit does not block progress.\n\n**Building toward vision**: Read codebase and vision artifact, identify the gap, pick the smallest increment closing the most valuable part.\n\n**Fixing issues**: Pick from TODO.md by severity (critical > degraded > annoying).\n\n**Optimization-shaped work**: suggest \u2398 optimize for measurable metrics and wait for confirmation instead of silently delegating.\n\nWrite a 1-2 sentence rationale. Scope down aggressively.\n\nCompose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it \u226480 words.\n\n**Plan unknowns consumption**: If the selected task comes from \u2261 plan and the plan carries \u0060unknowns:\u0060, note in the cycle context which unknowns affect this task and what the execution resolved. Carry unresolved unknowns forward in the progress entry's \u0060context.unknowns\u0060 field.\n\n**Decision gate**: After selecting work, use \u0060agentera state decisions --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries relate to the selected work area. Preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure in the cycle context. If an exploratory decision is found: flag the uncertain foundation, suggest \u2748 discuss to firm up the decision, and wait for confirmation. In autonomous mode, proceed with the work but log the risk.\n\n### Step 3: Seek inspiration\n\nSearch for relevant external approaches before planning.\n\n1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.\n2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.\n3. **Analyze**: read promising finds deeply.\n4. **Integrate**: fold applicable patterns into the plan.\n\n### Step 4: Plan\n\nWrite a concrete plan: what changes in which files, expected behavior, verification approach.\n\nRead files you plan to modify before committing to the plan.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\nSpawn an implementation sub-agent in a git worktree for isolation. Commit pending artifact changes before branching so the subagent starts from current state (\u0060git status --porcelain\u0060; if empty, skip). Use the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) \u2014 never spawn by running \u0060agentera build\u0060 or other capability-name CLI commands.\n\nBefore spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch \u2014 fetch the diff and apply it to the main checkout.\n\nSubagent prompt:\n\n\u0060\u0060\u0060\nYou are implementing a focused change for [project].\n\n## Task\n[The plan]\n\n## Constraints\n- Implement ONLY what the plan describes. No scope creep.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Verify the change works as described, then run the project's test/build suite.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\n### Step 6: Verify\n\nVerification has two phases: structural and behavioral. Both MUST pass before commit.\n\n**Phase A, structural verification**:\n\n1. Check the diff: does it match the plan?\n2. Functional check: does the changed behavior work end-to-end?\n3. Run the project's verification suite (test/build/lint).\n\n**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:\n\n- CLI tool: invoke with realistic arguments\n- Library/SDK: run a smoke driver\n- Web service: send a request to a production-shaped endpoint\n- Skill repo: \u0060agentera check verify eval skills --skill <name>\u0060\n\nIf verification fails: diagnose, spawn a fix agent, re-verify.\n\n**N/A path**: If the cycle has no runnable behavior change, use \u0060N/A: <tag>\u0060 from the allowlist: \u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060.\n\n### Step 7: Commit\n\nCommit with a conventional commit message: \u0060type(scope): summary\u0060.\n\nTypes: \u0060feat\u0060, \u0060fix\u0060, \u0060docs\u0060, \u0060refactor\u0060, \u0060chore\u0060, \u0060test\u0060. Include all related files. MUST NOT commit partial or broken work.\n\nIf the current task is a version bump: read \u0060.agentera/docs.yaml\u0060 for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Log\n\n**Before writing**, run \u0060agentera check lint --artifact <artifact> --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n**Dual-write**: build maintains \u0060.agentera/progress.yaml\u0060 and root \u0060CHANGELOG.md\u0060.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## \u2713 Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary.\n- **progress.yaml**: insert the newest cycle entry before older active cycles. The \u0060verified\u0060 field is mandatory.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nAfter writing progress.yaml, apply the schema COMPACTION rules if thresholds are exceeded: keep 10 full entries, keep up to 40 one-line archive entries, and drop beyond 50 total. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT bypass the project's test/lint/build suite.\n- MUST NOT modify git config or skip git hooks.\n- MUST NOT force push, amend published commits, or run destructive git operations.\n- MUST NOT add placeholder data or functionality.\n- MUST NOT modify files outside the project directory.\n- MUST NOT modify the vision artifact during a cycle \u2014 only during vision bootstrap.\n- One cycle per invocation. MUST NOT attempt multiple cycles.\n\n</critical>\n\n---\n\n## Handling blocked work\n\nIf blocked:\n\n1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060\u2500\u2500\u2500 \u29c9 build \u00b7 <status> \u2500\u2500\u2500\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\u0060 bullet details below the summary.\n\n- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.\n- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.\n- **stuck** (EX3): Cannot complete: the vision artifact is missing and bootstrap can't proceed, all work blocked, or verification suite broken.\n- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.\n\nBefore reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.\n\nAfter reporting an exit signal, the cycle is over \u2014 the next cycle requires an explicit user request or \u2388 orchestrate.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to \u26e5 vision\n\nWhen \u26e5 vision is installed and the vision artifact doesn't exist, suggest \u26e5 vision for deep vision creation. If vision is NOT installed, the vision bootstrap (above) is the standalone fallback.\n\n### Delegates to \u2398 optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses \u2b1a research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads \u267e profile output\n\nEvery cycle runs the effective profile. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses \u2748 discuss for complex decisions\n\nWhen work selection surfaces a decision too complex for inline resolution, suggest \u2748 discuss.\n\n### Consumes \u2261 plan plans\n\nWhen the plan artifact exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When \u0060header.status: complete\u0060 and every task is complete, run the plan-completion sweep, archive the plan, and preserve lineage/evidence.\n\n### Reads \u25a4 document output\n\n\u0060.agentera/docs.yaml\u0060 provides artifact path resolution and versioning conventions.\n\n### Reads \u25f0 design output\n\n\u0060DESIGN.md\u0060 provides visual identity context respected when building user-facing features.\n\n### Audited by \u26f6 audit\n\n\u0060.agentera/health.yaml\u0060 findings become candidates for work selection. Run \u26f6 audit every 5-10 cycles.\n"`);
+export const instructions = JSON.parse(String.raw `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\n\nGlyph: \u29c9 (protocol ref: SG2).\n\nAn autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.\n\nEach invocation = one cycle. After completing a cycle (orient through log, exit signal reported), **stop**. The next cycle starts only when the user explicitly requests it or switches to \u2388 orchestrate for autonomous multi-task execution. A compaction-continue prompt is not consent to start a new cycle.\n\nWhen offering execution mode choices after plan completion, label \u0060build\u0060 as \"one task, then stop\" and \u2388 orchestrate as \"all tasks autonomously.\"\n\n---\n\n## State artifacts\n\nBuild reads project state and writes progress, TODO, and changelog. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060progress\u0060 | produces | \u0060.agentera/progress.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | produces_and_consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### progress.yaml\n\n\u0060\u0060\u0060yaml\ncycles:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    type: feat\n    phase: build\n    what: One-line summary of what shipped.\n    inspiration: External source, if any.\n    discovered: Issues or ideas found.\n    verified: Observed output, N/A tag, or rationale.\n    next: Most valuable next work.\n    context:\n      intent: Why this cycle happened.\n      constraints: What had to stay true.\n      unknowns: What remains uncertain.\n      scope: What changed.\narchive: []\n\u0060\u0060\u0060\n\nThe \u0060verified\u0060 field is mandatory for every cycle entry.\n\n### CHANGELOG.md\n\nPublic-facing change history. Keep-a-changelog format. Build appends entries under \u0060## [Unreleased]\u0060 based on commit type: \u0060feat\u0060 \u2192 Added, \u0060refactor/chore\u0060 \u2192 Changed, \u0060fix\u0060 \u2192 Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Workflow phases: The cycle\n\n### Vision bootstrap\n\nIf the vision artifact is absent and \u26e5 vision is not installed, ask the user for project direction inline (one question: \"What does this software make possible?\"). Write the answer to \u0060.agentera/vision.yaml\u0060 and proceed to the cycle. If \u26e5 vision is installed and the artifact is absent, suggest \u26e5 vision and wait for confirmation. In all other cases, skip straight to the cycle.\n\n### The cycle\n\nStep markers: display \u0060\u2500\u2500 step N/8: verb\u0060 before each step.\nSteps: orient, select, research, plan, dispatch, verify, commit, log.\n\n### Step 1: Orient\n\nStart from the Build execution-context seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context build --format json\n\u0060\u0060\u0060\n\nIf \u0060execution_context.source_contract.complete_for_execution_context\u0060 is true, use \u0060execution_context\u0060 and included \u0060capability_context.state\u0060 as normal startup context. Do not read raw plan, progress, TODO, docs, health, decisions, changelog, vision, profile, or design artifacts to re-check selected work, acceptance criteria, constraints, verification expectations, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the cycle report and run the listed \u0060execution_context.fallback_commands\u0060 before any last-resort raw artifact diagnostic.\n\n#### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents MAY mark provisional satisfaction with evidence only. Build MUST NOT mark or imply user-confirmed satisfaction; only the user confirms final satisfaction. Missing, compacted, open, provisional, or review-needed satisfaction state remains a caveat and review pressure in the cycle report \u2014 automation MUST NOT reconstruct hidden outcomes or claim it proved user intent.\n\n#### Context consumption\n\nConsume these \u0060execution_context\u0060 fields:\n\n- \u0060work_selection\u0060: selected task or no-plan/completed-plan mode\n- \u0060acceptance_criteria\u0060: exact criteria for this cycle\n- \u0060constraints\u0060: plan constraints and protected-action boundaries\n- \u0060verification_expectations\u0060: expected validation and latest progress evidence\n- \u0060artifact_update_requirements\u0060: plan, TODO, changelog, and progress update obligations\n- \u0060changelog_boundary\u0060: current public-history boundary or fallback\n- \u0060scope_boundary\u0060: artifact-family scope and conservative source-file scope\n\nUse \u0060status.profile\u0060 for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.\n\n#### Project discovery\n\nOn cycle 1 or when unfamiliar with the project:\n\n- Map the directory structure\n- Read dependency manifests and README.md, AGENTS.md\n- Identify build/test/lint commands\n- Read key source files to understand architecture\n\nRun \u0060git log --oneline -20\u0060 for recent changes.\n\nBefore proceeding, list the 3-5 facts that determine this cycle.\n\n**Exit-early stop condition (plan-driven mode only)**: If \u0060.agentera/plan.yaml\u0060 has \u0060header.status: complete\u0060 and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not complete and MUST remain visible for replanning.\n\nSweep checklist:\n\n1. **progress.yaml aggregate cycle entry**: run \u0060agentera state progress append ... --format json\u0060 with a summary of the whole plan.\n2. **CHANGELOG.md plan-level entries**: verify \u0060## [Unreleased]\u0060 covers each completed task's user-facing impact.\n3. **TODO.md milestone advance**: mark each plan task as \u0060## \u2713 Resolved\u0060.\n4. **health.yaml cross-reference**: mention any resolved findings.\n\nAfter the sweep, run \u0060agentera state plan archive --format json\u0060 and report exit signal \u0060complete: plan finished\u0060. The writer preserves immutable archive history and removes the active plan.\n\n### Step 2: Pick work\n\nChoose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.\n\nEach cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit does not block progress.\n\n**Building toward vision**: Read codebase and vision artifact, identify the gap, pick the smallest increment closing the most valuable part.\n\n**Fixing issues**: Pick from TODO.md by severity (critical > degraded > annoying).\n\n**Optimization-shaped work**: suggest \u2398 optimize for measurable metrics and wait for confirmation instead of silently delegating.\n\nWrite a 1-2 sentence rationale. Scope down aggressively.\n\nCompose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it \u226480 words.\n\n**Plan unknowns consumption**: If the selected task comes from \u2261 plan and the plan carries \u0060unknowns:\u0060, note in the cycle context which unknowns affect this task and what the execution resolved. Carry unresolved unknowns forward in the progress entry's \u0060context.unknowns\u0060 field.\n\n**Decision gate**: After selecting work, use \u0060agentera state decisions --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries relate to the selected work area. Preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure in the cycle context. If an exploratory decision is found: flag the uncertain foundation, suggest \u2748 discuss to firm up the decision, and wait for confirmation. In autonomous mode, proceed with the work but log the risk.\n\n### Step 3: Seek inspiration\n\nSearch for relevant external approaches before planning.\n\n1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.\n2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.\n3. **Analyze**: read promising finds deeply.\n4. **Integrate**: fold applicable patterns into the plan.\n\n### Step 4: Plan\n\nWrite a concrete plan: what changes in which files, expected behavior, verification approach.\n\nRead files you plan to modify before committing to the plan.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\nSpawn an implementation sub-agent in a git worktree for isolation. Commit pending artifact changes before branching so the subagent starts from current state (\u0060git status --porcelain\u0060; if empty, skip). Use the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) \u2014 never spawn by running \u0060agentera build\u0060 or other capability-name CLI commands.\n\nBefore spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch \u2014 fetch the diff and apply it to the main checkout.\n\nSubagent prompt:\n\n\u0060\u0060\u0060\nYou are implementing a focused change for [project].\n\n## Task\n[The plan]\n\n## Constraints\n- Implement ONLY what the plan describes. No scope creep.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Verify the change works as described, then run the project's test/build suite.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\n### Step 6: Verify\n\nVerification has two phases: structural and behavioral. Both MUST pass before commit.\n\n**Phase A, structural verification**:\n\n1. Check the diff: does it match the plan?\n2. Functional check: does the changed behavior work end-to-end?\n3. Run the project's verification suite (test/build/lint).\n\n**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:\n\n- CLI tool: invoke with realistic arguments\n- Library/SDK: run a smoke driver\n- Web service: send a request to a production-shaped endpoint\n- Skill repo: \u0060agentera check verify eval skills --skill <name>\u0060\n\nIf verification fails: diagnose, spawn a fix agent, re-verify.\n\n**N/A path**: If the cycle has no runnable behavior change, use \u0060N/A: <tag>\u0060 from the allowlist: \u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060.\n\n### Step 7: Commit\n\nCommit with a conventional commit message: \u0060type(scope): summary\u0060.\n\nTypes: \u0060feat\u0060, \u0060fix\u0060, \u0060docs\u0060, \u0060refactor\u0060, \u0060chore\u0060, \u0060test\u0060. Include all related files. MUST NOT commit partial or broken work.\n\nIf the current task is a version bump: read \u0060.agentera/docs.yaml\u0060 for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Log\n\n**Before writing**, run \u0060agentera check lint --artifact <artifact> --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n**Dual-write**: build maintains \u0060.agentera/progress.yaml\u0060 and root \u0060CHANGELOG.md\u0060.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## \u2713 Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary.\n- **progress.yaml**: run \u0060agentera state progress append --type TYPE --phase build --what TEXT --intent TEXT --verified TEXT --format json\u0060. The writer assigns the number, inserts newest-first, validates, compacts, and returns post-write state.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nProgress compaction is writer-owned. When a plan task closes, run \u0060agentera state plan set-status --task N --status complete --format json\u0060 rather than editing the plan directly. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT bypass the project's test/lint/build suite.\n- MUST NOT modify git config or skip git hooks.\n- MUST NOT force push, amend published commits, or run destructive git operations.\n- MUST NOT add placeholder data or functionality.\n- MUST NOT modify files outside the project directory.\n- MUST NOT modify the vision artifact during a cycle \u2014 only during vision bootstrap.\n- One cycle per invocation. MUST NOT attempt multiple cycles.\n\n</critical>\n\n---\n\n## Handling blocked work\n\nIf blocked:\n\n1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060\u2500\u2500\u2500 \u29c9 build \u00b7 <status> \u2500\u2500\u2500\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\u0060 bullet details below the summary.\n\n- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.\n- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.\n- **stuck** (EX3): Cannot complete: the vision artifact is missing and bootstrap can't proceed, all work blocked, or verification suite broken.\n- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.\n\nBefore reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.\n\nAfter reporting an exit signal, the cycle is over \u2014 the next cycle requires an explicit user request or \u2388 orchestrate.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to \u26e5 vision\n\nWhen \u26e5 vision is installed and the vision artifact doesn't exist, suggest \u26e5 vision for deep vision creation. If vision is NOT installed, the vision bootstrap (above) is the standalone fallback.\n\n### Delegates to \u2398 optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses \u2b1a research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads \u267e profile output\n\nEvery cycle runs the effective profile. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses \u2748 discuss for complex decisions\n\nWhen work selection surfaces a decision too complex for inline resolution, suggest \u2748 discuss.\n\n### Consumes \u2261 plan plans\n\nWhen the plan artifact exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When \u0060header.status: complete\u0060 and every task is complete, run the plan-completion sweep, archive the plan, and preserve lineage/evidence.\n\n### Reads \u25a4 document output\n\n\u0060.agentera/docs.yaml\u0060 provides artifact path resolution and versioning conventions.\n\n### Reads \u25f0 design output\n\n\u0060DESIGN.md\u0060 provides visual identity context respected when building user-facing features.\n\n### Audited by \u26f6 audit\n\n\u0060.agentera/health.yaml\u0060 findings become candidates for work selection. Run \u26f6 audit every 5-10 cycles.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,6zgBAA6zgB,CAAC,CAAC;AACx3gB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,25gBAA25gB,CAAC,CAAC;AACt9gB,eAAe,YAAY,CAAC"}

package/dist/capabilities/discuss/instructions.js

@@ -1,6 +1,6 @@
 // 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 --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: \u0060N = highest existing decision number + 1\u0060. Insert before the \u0060archive:\u0060 list if present; otherwise append. Active and archive entries remain ascending by \u0060number\u0060. Compaction (apply before writing when thresholds exceeded): keep 10 full decisions, up to 40 one-line archive entries, drop beyond 50 total.\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 (e.g., Claude Code \u0060AskUserQuestion\u0060, OpenCode \u0060question\u0060, Copilot \u0060ask_user\u0060, Codex \u0060request_user_input\u0060 — guidance examples, not schema authority). **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**: decisions — chosen decision, confidence, rationale; compute next number before writing; apply schema COMPACTION before writing if thresholds exceeded. 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 --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 (e.g., Claude Code \u0060AskUserQuestion\u0060, OpenCode \u0060question\u0060, Copilot \u0060ask_user\u0060, Codex \u0060request_user_input\u0060 — guidance examples, not schema authority). **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 default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../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,w7YAAw7Y,CAAC,CAAC;AACn/Y,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../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,85YAA85Y,CAAC,CAAC;AACz9Y,eAAe,YAAY,CAAC"}

package/dist/capabilities/orchestrate/instructions.js

@@ -1,5 +1,5 @@
 // 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 --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 to \u0060.agentera/archive/PLAN-{date}-{slug}.yaml\u0060, then remove the active \u0060.agentera/plan.yaml\u0060.\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 --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 --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 --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.\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 runtime provides its own subagent substrate (Claude Code: Task tool; OpenCode: \u0060~/.config/opencode/agents/*.md\u0060 descriptors; Codex CLI: \u0060~/.codex/agents/*.toml\u0060; Copilot CLI: user-driven \u0060/fleet\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 --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 --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 --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 --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 runtime provides its own subagent substrate (Claude Code: Task tool; OpenCode: \u0060~/.config/opencode/agents/*.md\u0060 descriptors; Codex CLI: \u0060~/.codex/agents/*.toml\u0060; Copilot CLI: user-driven \u0060/fleet\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 default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../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,u1mBAAu1mB,CAAC,CAAC;AACl5mB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../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,q/mBAAq/mB,CAAC,CAAC;AAChjnB,eAAe,YAAY,CAAC"}

package/dist/capabilities/plan/instructions.js

@@ -1,6 +1,6 @@
 // Source: skills/agentera/capabilities/plan/instructions.md (relocated D65)
 // Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
 // equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# PLAN\n\n**Planning Logic: Behavioral Requirements Decomposition. Enumerate, Refine, Assign**\n\nGlyph: **≡** (protocol ref: SG5). Scale-adaptive planning bridging deliberation and execution. PLAN artifact with behavioral acceptance criteria for build. Plan owns WHAT and WHY; build owns HOW. Three levels: skip (trivial work, route directly to build), light (single-cycle), full (multi-cycle with adversarial review).\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, use a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nOne write target and one archive directory in \u0060.agentera/\u0060.\n\n| Artifact | Role | Source |\n|---|---|---|\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 (or docs-mapped path) |\n| \u0060plan_archive\u0060 | produces | \u0060.agentera/archive/plan-{date}.yaml\u0060 |\n| \u0060vision\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060decisions\u0060 | consumes | firm (DL1) entries via \u0060agentera state decisions --format json\u0060 |\n| \u0060todo\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060health\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060progress\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060profile\u0060 | consumes | \u0060planning_context.profile.path\u0060 |\n| \u0060docs\u0060 | consumes | docs artifact mapping for path overrides and versioning block |\n\n**Read contract for PLAN artifact consumers**: tasks carry status from the \u0060status\u0060 enum (\u0060pending\u0060, \u0060in_progress\u0060, \u0060complete\u0060, \u0060skipped\u0060); surprises and unknowns land in their respective top-level lists. When all tasks are \u0060complete\u0060, the planner (or build at cycle closeout) archives the artifact to \u0060.agentera/archive/plan-{date}.yaml\u0060 and deletes \u0060.agentera/plan.yaml\u0060. The full consumption flow lives in build's and orchestrate's own instructions; plan declares only what the artifact shape guarantees.\n\n**Startup contract**: trust \u0060planning_context.startup_contract\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context plan --format json\u0060. When \u0060source_contract.complete_for_plan_artifact\u0060 is true, \u0060agentera state plan --format json\u0060 already serves summary, tasks, dependencies, acceptance, evidence, surprises, unknowns, and previous-plan archive references — do not reread the persisted artifact defensively. Raw plan artifact access is for writing, archiving, validation, corruption diagnostics, or after CLI fallbacks fail. The runtime owns the planning-level taxonomy, required step list, step-marker format, max full-plan tasks, cli-first-orientation policy, artifact access boundaries, and handoff expectations — do not re-encode them here. Artifact path resolution is owned by SKILL.md; visual-token families by \u0060skills/agentera/protocol.yaml\u0060.\n\nDirect invocation of ≡ plan on an already-complete plan: archiving before writing its replacement is implicit in the direct invocation and does not require separate pre-write confirmation. Human-initiated replacement plans still require plan approval before the write. Replacing, discarding, or archiving an active or incomplete plan is not implicit; ask for explicit confirmation.\n\n---\n\n## Workflow phases\n\nMode-split shape: Step 0 detects level (skip/light/full), then the mode-specific steps run. Step labels — orient, specify, review, audit, write, handoff — are owned by \u0060planning_context.startup_contract.required_steps\u0060; the runtime owns the step-marker format.\n\n### Step 0: Detect level\n\nAssess work complexity. Read the description (user, \u0060decisions\u0060 artifact, or \u0060todo\u0060 artifact). Scan codebase if needed.\n\n| Signal | Level |\n|---|---|\n| Single-file change, localized defect fix, or config tweak **and** touches no shared abstraction | **Skip** |\n| One module affected, clear scope, fits one build cycle | **Light** |\n| Multiple modules, multi-file changes, 3+ logical steps, new feature spanning architecture | **Full** |\n\n**Skip**: This doesn't need a plan. Suggest ⧉ build and wait for confirmation unless the user already asked to implement now. Stop here.\n\n**Light or Full**: Proceed to planning.\n\nIf uncertain between light and full, default to light.\n\n### Step 1: Orient\n\nTrust \u0060planning_context\u0060 from \u0060agentera prime --context plan --format json\u0060 and read state families by name (\u0060plan\u0060, \u0060vision\u0060, \u0060decisions\u0060, \u0060todo\u0060, \u0060health\u0060, \u0060progress\u0060, \u0060docs\u0060, \u0060profile\u0060). Use listed \u0060fallback_commands\u0060 for missing families before any last-resort raw artifact read.\n\n- **vision**: the north star (if present)\n- **decisions**: firm (DL1) entries are hard constraints for planning. Read via \u0060agentera state decisions --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n- **health**: latest codebase health grades (if present)\n- **todo**: related known issues (if present)\n- **progress**: what was built recently (if present)\n- **profile**: served via \u0060planning_context.profile.path\u0060 — read directly when \u0060status: loaded\u0060; if missing or stale, proceed without persona grounding. Staleness is a caveat, not approval to refresh profile state.\n\n**Project discovery** (if unfamiliar with the repo): map directory structure, read README.md and AGENTS.md, dependency manifests, identify build/test/lint commands.\n\nBefore decomposing: summarize the constraints from \u0060vision\u0060 and \u0060decisions\u0060.\n\n### Step 2: Specify\n\nDefine WHAT and WHY. Intent layer, not implementation details.\n\n#### Light plans\n\nBrief conversation (2-3 questions):\n\n- **What**: one-paragraph description of the change\n- **Why**: what value it delivers or what problem it solves\n- **Constraints**: what must NOT break, what's out of scope\n- **Acceptance criteria**: 3-5 behavioral criteria in Given/When/Then format\n\nWrite PLAN. Present for approval (human-initiated) or proceed (autonomous).\n\n#### Full plans\n\nDeeper conversation:\n\n- **What**: detailed description\n- **Why**: motivation, user impact, relationship to \u0060vision\u0060\n- **Constraints**: architectural boundaries, off-limits modules\n- **Scope**: what's in, out, deferred\n- **Design**: approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure; those belong in scope or task-level acceptance. Design SHOULD describe how subsystems interrelate and the order phases SHOULD run in.\n- **Task decomposition**: 3-8 ordered tasks, each one build cycle. Per task: description, dependencies, 3-5 behavioral Given/When/Then acceptance criteria\n- **Test proportionality**: for tasks with tests, add a proportionality target. Default: one pass + one fail per testable unit. Override only with explicit rationale.\n- **Plan-level current-state check**: every full plan ends with a final state sync task depending on all prior tasks.\n- **Version bump check**: add a bump task when the \u0060docs\u0060 artifact \u0060versioning\u0060 block exists and the plan includes \u0060feat\u0060/\u0060fix\u0060 work.\n- **Fog identification**: every full plan surfaces at least one known-unknown — a planning-time question whose answer determines whether downstream tasks are still needed as written. Each unknown lists the question, the task it affects, and how the answer resolves (\u0060resolve_by\u0060).\n- **Overall acceptance criteria**: behavioral criteria for the complete feature\n\nPresent for approval or proceed to adversarial review.\n\n### Step 3: Review (full plans only)\n\nSpawn an adversarial critic. The critic MUST find issues.\n\n\u0060\u0060\u0060\nYou are reviewing a development plan for [project]. Your job is to find problems.\n\n## The plan\n[Full PLAN artifact content]\n\n## Your mandate\nYou MUST identify at least one issue. \"Looks good\" is not acceptable.\n\nLook for:\n- Tasks too large for a single implementation cycle\n- Missing dependencies between tasks\n- Acceptance criteria too vague to verify\n- Acceptance criteria that leak implementation details\n- Scope gaps or scope creep\n- Ordering issues\n- Conflicting constraints\n- Unacknowledged risks\n- Fog treated as resolved\n\u0060\u0060\u0060\n\nAddress legitimate issues; dismiss false positives with rationale. Record each dismissal in the artifact's \u0060rejected:\u0060 list with the issue text and the rationale, so downstream consumers (build, orchestrate, audit) inherit the adjudication rather than relitigating.\n\nPresent reviewed plan.\n\n### Step 4: Pre-write self-audit\n\nRun the pre-write lint per \u0060planning_context.startup_contract.pre_write_self_audit_required\u0060. The capability-instruction contract owns the command shape (dispatch to \u0060agentera check lint\u0060 with the plan draft). The check inspects the draft for verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Step 5: Write PLAN\n\nWrite tasks with acceptance criteria. The conversation preserves reasoning; the artifact preserves the plan.\n\nWrite to \u0060.agentera/plan.yaml\u0060 (or docs-mapped path).\n\n#### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: YYYY-MM-DD\n  status: active\n  title: Short Title\nwhat: One paragraph.\nwhy: Motivation and value.\nconstraints: What must not break; what is out of scope.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\ntasks: []\n\u0060\u0060\u0060\n\n#### Full plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: YYYY-MM-DD\n  status: active\n  reviewed: YYYY-MM-DD\n  critic_issues: \"N found, N addressed, N dismissed\"\n  title: Short Title\nwhat: Detailed description.\nwhy: Motivation, user impact, relationship to vision.\nconstraints: Architectural boundaries and off-limits modules.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\nscope:\n  included: []\n  excluded: []\n  deferred: []\ndesign: Approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure.\nunknowns:\n  - question: \"Will X support Y in task 2's environment?\"\n    affects_task: 3\n    resolve_by: \"Build cycle 2 outcome; if X fails, task 3 becomes a refactor scope\"\nrejected:\n  - issue: \"Acceptance criterion on task 4 references a specific library\"\n    rationale: \"Library name is the test-fixture contract, not implementation guidance — kept.\"\ntasks:\n  - number: 1\n    name: Title\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN context WHEN action THEN expected outcome\nsurprises: []\n\u0060\u0060\u0060\n\n### Step 6: Handoff\n\n- **Single-task plan**: suggest ⧉ build to execute and wait for confirmation.\n- **Full plan**: suggest ⎈ orchestrate to execute the entire plan and wait for confirmation.\n\nIf \u0060unknowns:\u0060 lists fog at planning time, name the foreshadow in the handoff: \"Build will resolve unknowns; re-invoke ≡ plan if surprises on one task alter the acceptance criteria of downstream tasks.\"\n\n---\n\n## Safety rails\n\n<critical>\n- Plan MUST NOT include implementation details in the PLAN artifact. Plan owns WHAT and WHY; build owns HOW.\n- Plan MUST NOT write acceptance criteria that reference implementation. Use behavioral, domain-language criteria only.\n- Plan MUST NOT produce more than 8 tasks in a full plan. If work requires more, split it into sequential plans.\n- Plan MUST NOT modify the PLAN artifact during a build cycle except to update task status and add surprises.\n- Plan MUST NOT skip adversarial review for full plans.\n- Plan MUST NOT auto-approve plans when human-initiated. Present for approval.\n- Plan MUST NOT plan trivial work. If skip level, say so and route to build.\n- Plan MUST NOT invoke build, optimize, or orchestrate without the user's explicit consent. Suggest, don't dispatch.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion.\n\nFormat: \u0060─── ≡ plan · <status> ───\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060, \u0060stuck\u0060, and \u0060waiting\u0060, add a ▸ bullet below the summary identifying what needs attention.\n\n- **complete**: PLAN artifact written and approved, adversarial review ran for full plans, handoff suggested.\n- **flagged**: Plan produced with caveats — critic issues dismissed rather than resolved, scope larger than ideal, acceptance criteria not fully behavioral, or planning-time unknowns still open at handoff.\n- **stuck**: Cannot plan because the work description is too ambiguous to decompose, required context artifacts contradict, or the user declined to approve the plan with no clear revision path.\n- **waiting**: The feature or change is not specified with enough detail to produce acceptance criteria, or key architectural constraints are unknown and cannot be inferred from the codebase.\n\n---\n\n## Cross-capability integration\n\nPlan is the bridge between deliberation and execution.\n\n### Fed by ❈ discuss\n\nWhen discuss's deliberation concludes with a decision to build, plan is the next step. The \u0060decisions\u0060 artifact carries the \"why\" context as hard constraints.\n\n### Feeds ⧉ build\n\nPLAN tasks become build's work queue. Task acceptance criteria become cycle exit conditions. Build updates task status and logs surprises. The read contract is declared in §2; build's consumption flow lives in build's instructions.\n\n### Feeds ⎘ optimize\n\nWhen a plan includes optimization-shaped tasks (measurable changes with apply/rollback semantics), those tasks delegate to optimize.\n\n### Informed by ⛶ audit\n\n\u0060health\u0060 findings can trigger remediation plans. Audit reveals structural issues; plan produces a plan to address them.\n\n### Informed by ♾ profile\n\nDecision profile calibrates planning depth and pattern preferences.\n\n### Informed by ⬚ research\n\nWhen research recommends patterns or libraries, plan incorporates them into the plan's design section.\n\n### Reads ⛥ vision\n\n\u0060vision\u0060 provides the north star read during Orient.\n\n### Fed by ▤ document (docs-first workflow)\n\nIn the docs-first workflow, document writes intent docs first, then plan decomposes them into tasks.\n\n### Reads ▤ document versioning\n\nPlan reads the \u0060versioning\u0060 block from the \u0060docs\u0060 artifact. When the plan includes \u0060feat\u0060/\u0060fix\u0060 work, plan appends a version bump task.\n\n### Getting started\n\n**Planning a new feature**: ❈ discuss → ≡ plan → ⧉ build or ⎈ orchestrate.\n\n**Planning a remediation**: ⛶ audit → ≡ plan → ⧉ build.\n\n**Mid-feature replanning**: when surprises logged on one task alter the acceptance criteria of downstream tasks, re-invoke ≡ plan to reassess. Read the surprises, surface new unknowns, archive or amend, then resume ⧉ build. If surprises are isolated and acceptance criteria of downstream tasks remain intact, build can continue without replanning.\n\n**Skipping the plan**: trivial work (skip level) routes to ⧉ build directly.\n"`);
+export const instructions = JSON.parse(String.raw `"# PLAN\n\n**Planning Logic: Behavioral Requirements Decomposition. Enumerate, Refine, Assign**\n\nGlyph: **≡** (protocol ref: SG5). Scale-adaptive planning bridging deliberation and execution. PLAN artifact with behavioral acceptance criteria for build. Plan owns WHAT and WHY; build owns HOW. Three levels: skip (trivial work, route directly to build), light (single-cycle), full (multi-cycle with adversarial review).\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, use a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nOne write target and one archive directory in \u0060.agentera/\u0060.\n\n| Artifact | Role | Source |\n|---|---|---|\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 (or docs-mapped path) |\n| \u0060plan_archive\u0060 | produces | \u0060.agentera/archive/plan-{date}.yaml\u0060 |\n| \u0060vision\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060decisions\u0060 | consumes | firm (DL1) entries via \u0060agentera state decisions --format json\u0060 |\n| \u0060todo\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060health\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060progress\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060profile\u0060 | consumes | \u0060planning_context.profile.path\u0060 |\n| \u0060docs\u0060 | consumes | docs artifact mapping for path overrides and versioning block |\n\n**Read contract for PLAN artifact consumers**: tasks carry status from the \u0060status\u0060 enum (\u0060pending\u0060, \u0060in_progress\u0060, \u0060complete\u0060, \u0060skipped\u0060); surprises and unknowns land in their respective top-level lists. When all tasks are \u0060complete\u0060, the planner (or build at cycle closeout) runs \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming, crash-consistent closeout, and active-plan removal. The full consumption flow lives in build's and orchestrate's own instructions; plan declares only what the artifact shape guarantees.\n\n**Startup contract**: trust \u0060planning_context.startup_contract\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context plan --format json\u0060. When \u0060source_contract.complete_for_plan_artifact\u0060 is true, \u0060agentera state plan --format json\u0060 already serves summary, tasks, dependencies, acceptance, evidence, surprises, unknowns, and previous-plan archive references — do not reread the persisted artifact defensively. Raw plan artifact access is for writing, archiving, validation, corruption diagnostics, or after CLI fallbacks fail. The runtime owns the planning-level taxonomy, required step list, step-marker format, max full-plan tasks, cli-first-orientation policy, artifact access boundaries, and handoff expectations — do not re-encode them here. Artifact path resolution is owned by SKILL.md; visual-token families by \u0060skills/agentera/protocol.yaml\u0060.\n\nDirect invocation of ≡ plan on an already-complete plan: archiving before writing its replacement is implicit in the direct invocation and does not require separate pre-write confirmation. Human-initiated replacement plans still require plan approval before the write. Replacing, discarding, or archiving an active or incomplete plan is not implicit; ask for explicit confirmation.\n\n---\n\n## Workflow phases\n\nMode-split shape: Step 0 detects level (skip/light/full), then the mode-specific steps run. Step labels — orient, specify, review, audit, write, handoff — are owned by \u0060planning_context.startup_contract.required_steps\u0060; the runtime owns the step-marker format.\n\n### Step 0: Detect level\n\nAssess work complexity. Read the description (user, \u0060decisions\u0060 artifact, or \u0060todo\u0060 artifact). Scan codebase if needed.\n\n| Signal | Level |\n|---|---|\n| Single-file change, localized defect fix, or config tweak **and** touches no shared abstraction | **Skip** |\n| One module affected, clear scope, fits one build cycle | **Light** |\n| Multiple modules, multi-file changes, 3+ logical steps, new feature spanning architecture | **Full** |\n\n**Skip**: This doesn't need a plan. Suggest ⧉ build and wait for confirmation unless the user already asked to implement now. Stop here.\n\n**Light or Full**: Proceed to planning.\n\nIf uncertain between light and full, default to light.\n\n### Step 1: Orient\n\nTrust \u0060planning_context\u0060 from \u0060agentera prime --context plan --format json\u0060 and read state families by name (\u0060plan\u0060, \u0060vision\u0060, \u0060decisions\u0060, \u0060todo\u0060, \u0060health\u0060, \u0060progress\u0060, \u0060docs\u0060, \u0060profile\u0060). Use listed \u0060fallback_commands\u0060 for missing families before any last-resort raw artifact read.\n\n- **vision**: the north star (if present)\n- **decisions**: firm (DL1) entries are hard constraints for planning. Read via \u0060agentera state decisions --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n- **health**: latest codebase health grades (if present)\n- **todo**: related known issues (if present)\n- **progress**: what was built recently (if present)\n- **profile**: served via \u0060planning_context.profile.path\u0060 — read directly when \u0060status: loaded\u0060; if missing or stale, proceed without persona grounding. Staleness is a caveat, not approval to refresh profile state.\n\n**Project discovery** (if unfamiliar with the repo): map directory structure, read README.md and AGENTS.md, dependency manifests, identify build/test/lint commands.\n\nBefore decomposing: summarize the constraints from \u0060vision\u0060 and \u0060decisions\u0060.\n\n### Step 2: Specify\n\nDefine WHAT and WHY. Intent layer, not implementation details.\n\n#### Light plans\n\nBrief conversation (2-3 questions):\n\n- **What**: one-paragraph description of the change\n- **Why**: what value it delivers or what problem it solves\n- **Constraints**: what must NOT break, what's out of scope\n- **Acceptance criteria**: 3-5 behavioral criteria in Given/When/Then format\n\nWrite PLAN. Present for approval (human-initiated) or proceed (autonomous).\n\n#### Full plans\n\nDeeper conversation:\n\n- **What**: detailed description\n- **Why**: motivation, user impact, relationship to \u0060vision\u0060\n- **Constraints**: architectural boundaries, off-limits modules\n- **Scope**: what's in, out, deferred\n- **Design**: approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure; those belong in scope or task-level acceptance. Design SHOULD describe how subsystems interrelate and the order phases SHOULD run in.\n- **Task decomposition**: 3-8 ordered tasks, each one build cycle. Per task: description, dependencies, 3-5 behavioral Given/When/Then acceptance criteria\n- **Test proportionality**: for tasks with tests, add a proportionality target. Default: one pass + one fail per testable unit. Override only with explicit rationale.\n- **Plan-level current-state check**: every full plan ends with a final state sync task depending on all prior tasks.\n- **Version bump check**: add a bump task when the \u0060docs\u0060 artifact \u0060versioning\u0060 block exists and the plan includes \u0060feat\u0060/\u0060fix\u0060 work.\n- **Fog identification**: every full plan surfaces at least one known-unknown — a planning-time question whose answer determines whether downstream tasks are still needed as written. Each unknown lists the question, the task it affects, and how the answer resolves (\u0060resolve_by\u0060).\n- **Overall acceptance criteria**: behavioral criteria for the complete feature\n\nPresent for approval or proceed to adversarial review.\n\n### Step 3: Review (full plans only)\n\nSpawn an adversarial critic. The critic MUST find issues.\n\n\u0060\u0060\u0060\nYou are reviewing a development plan for [project]. Your job is to find problems.\n\n## The plan\n[Full PLAN artifact content]\n\n## Your mandate\nYou MUST identify at least one issue. \"Looks good\" is not acceptable.\n\nLook for:\n- Tasks too large for a single implementation cycle\n- Missing dependencies between tasks\n- Acceptance criteria too vague to verify\n- Acceptance criteria that leak implementation details\n- Scope gaps or scope creep\n- Ordering issues\n- Conflicting constraints\n- Unacknowledged risks\n- Fog treated as resolved\n\u0060\u0060\u0060\n\nAddress legitimate issues; dismiss false positives with rationale. Record each dismissal in the artifact's \u0060rejected:\u0060 list with the issue text and the rationale, so downstream consumers (build, orchestrate, audit) inherit the adjudication rather than relitigating.\n\nPresent reviewed plan.\n\n### Step 4: Pre-write self-audit\n\nRun the pre-write lint per \u0060planning_context.startup_contract.pre_write_self_audit_required\u0060. The capability-instruction contract owns the command shape (dispatch to \u0060agentera check lint\u0060 with the plan draft). The check inspects the draft for verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Step 5: Write PLAN\n\nWrite tasks with acceptance criteria. The conversation preserves reasoning; the artifact preserves the plan.\n\nSave the approved complete plan document to temporary YAML/JSON input and run \u0060agentera state plan create --input PATH --format json\u0060 (or \u0060--input -\u0060). The writer validates it, archives a complete predecessor, injects lineage, and publishes to the docs-mapped path. Replacing an incomplete predecessor requires the approved \u0060--force\u0060 override.\n\n#### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: YYYY-MM-DD\n  status: active\n  title: Short Title\nwhat: One paragraph.\nwhy: Motivation and value.\nconstraints: What must not break; what is out of scope.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\ntasks: []\n\u0060\u0060\u0060\n\n#### Full plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: YYYY-MM-DD\n  status: active\n  reviewed: YYYY-MM-DD\n  critic_issues: \"N found, N addressed, N dismissed\"\n  title: Short Title\nwhat: Detailed description.\nwhy: Motivation, user impact, relationship to vision.\nconstraints: Architectural boundaries and off-limits modules.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\nscope:\n  included: []\n  excluded: []\n  deferred: []\ndesign: Approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure.\nunknowns:\n  - question: \"Will X support Y in task 2's environment?\"\n    affects_task: 3\n    resolve_by: \"Build cycle 2 outcome; if X fails, task 3 becomes a refactor scope\"\nrejected:\n  - issue: \"Acceptance criterion on task 4 references a specific library\"\n    rationale: \"Library name is the test-fixture contract, not implementation guidance — kept.\"\ntasks:\n  - number: 1\n    name: Title\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN context WHEN action THEN expected outcome\nsurprises: []\n\u0060\u0060\u0060\n\n### Step 6: Handoff\n\n- **Single-task plan**: suggest ⧉ build to execute and wait for confirmation.\n- **Full plan**: suggest ⎈ orchestrate to execute the entire plan and wait for confirmation.\n\nIf \u0060unknowns:\u0060 lists fog at planning time, name the foreshadow in the handoff: \"Build will resolve unknowns; re-invoke ≡ plan if surprises on one task alter the acceptance criteria of downstream tasks.\"\n\n---\n\n## Safety rails\n\n<critical>\n- Plan MUST NOT include implementation details in the PLAN artifact. Plan owns WHAT and WHY; build owns HOW.\n- Plan MUST NOT write acceptance criteria that reference implementation. Use behavioral, domain-language criteria only.\n- Plan MUST NOT produce more than 8 tasks in a full plan. If work requires more, split it into sequential plans.\n- Plan MUST NOT modify the PLAN artifact during a build cycle except to update task status and add surprises.\n- Plan MUST NOT skip adversarial review for full plans.\n- Plan MUST NOT auto-approve plans when human-initiated. Present for approval.\n- Plan MUST NOT plan trivial work. If skip level, say so and route to build.\n- Plan MUST NOT invoke build, optimize, or orchestrate without the user's explicit consent. Suggest, don't dispatch.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion.\n\nFormat: \u0060─── ≡ plan · <status> ───\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060, \u0060stuck\u0060, and \u0060waiting\u0060, add a ▸ bullet below the summary identifying what needs attention.\n\n- **complete**: PLAN artifact written and approved, adversarial review ran for full plans, handoff suggested.\n- **flagged**: Plan produced with caveats — critic issues dismissed rather than resolved, scope larger than ideal, acceptance criteria not fully behavioral, or planning-time unknowns still open at handoff.\n- **stuck**: Cannot plan because the work description is too ambiguous to decompose, required context artifacts contradict, or the user declined to approve the plan with no clear revision path.\n- **waiting**: The feature or change is not specified with enough detail to produce acceptance criteria, or key architectural constraints are unknown and cannot be inferred from the codebase.\n\n---\n\n## Cross-capability integration\n\nPlan is the bridge between deliberation and execution.\n\n### Fed by ❈ discuss\n\nWhen discuss's deliberation concludes with a decision to build, plan is the next step. The \u0060decisions\u0060 artifact carries the \"why\" context as hard constraints.\n\n### Feeds ⧉ build\n\nPLAN tasks become build's work queue. Task acceptance criteria become cycle exit conditions. Build updates task status and logs surprises. The read contract is declared in §2; build's consumption flow lives in build's instructions.\n\n### Feeds ⎘ optimize\n\nWhen a plan includes optimization-shaped tasks (measurable changes with apply/rollback semantics), those tasks delegate to optimize.\n\n### Informed by ⛶ audit\n\n\u0060health\u0060 findings can trigger remediation plans. Audit reveals structural issues; plan produces a plan to address them.\n\n### Informed by ♾ profile\n\nDecision profile calibrates planning depth and pattern preferences.\n\n### Informed by ⬚ research\n\nWhen research recommends patterns or libraries, plan incorporates them into the plan's design section.\n\n### Reads ⛥ vision\n\n\u0060vision\u0060 provides the north star read during Orient.\n\n### Fed by ▤ document (docs-first workflow)\n\nIn the docs-first workflow, document writes intent docs first, then plan decomposes them into tasks.\n\n### Reads ▤ document versioning\n\nPlan reads the \u0060versioning\u0060 block from the \u0060docs\u0060 artifact. When the plan includes \u0060feat\u0060/\u0060fix\u0060 work, plan appends a version bump task.\n\n### Getting started\n\n**Planning a new feature**: ❈ discuss → ≡ plan → ⧉ build or ⎈ orchestrate.\n\n**Planning a remediation**: ⛶ audit → ≡ plan → ⧉ build.\n\n**Mid-feature replanning**: when surprises logged on one task alter the acceptance criteria of downstream tasks, re-invoke ≡ plan to reassess. Read the surprises, surface new unknowns, archive or amend, then resume ⧉ build. If surprises are isolated and acceptance criteria of downstream tasks remain intact, build can continue without replanning.\n\n**Skipping the plan**: trivial work (skip level) routes to ⧉ build directly.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/plan/instructions.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,+0eAA+0e,CAAC,CAAC;AAC14e,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/plan/instructions.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,0qfAA0qf,CAAC,CAAC;AACruf,eAAe,YAAY,CAAC"}

package/dist/cli/capabilityContext/contract.js

@@ -6,6 +6,7 @@ import { capabilityStartupCommand } from "../../capabilities/index.js";
 import { PLAN_COMPLETED_PLAN_ARCHIVE_CONFIRMATION, PLAN_INSTRUCTIONS_AUTHORITY_EXCEPTIONS, PLAN_PLANNING_LEVELS, PLAN_RAW_PLAN_ACCESS_ALLOWED_FOR, PLAN_STARTUP_CONTRACT_VERSION, PLAN_STEP_VERBS, STARTUP_ENVELOPE_STATE_FAMILIES, STATE_FAMILY_FALLBACK_COMMANDS, } from "./types.js";
 import { CAPABILITY_INSTRUCTIONS, capabilityInstructionModulePath } from "../../capabilities/index.js";
 import { isFile, pyRepr, appendUnique } from "./shared.js";
+import { stateWriterContract } from "../../state/write/operations.js";
 export function capabilityInstructionContractPath() {
     const model = activeAppModel();
     const active = path.join(String(model.authoritativeRoot ?? model.activeBundleRoot), "references", "cli", "capability-instruction-contract.yaml");
@@ -173,6 +174,7 @@ export function capabilityContext(capability) {
         first_invocation_read: firstInvocationReadMetadata(capability),
         declared_state_needs: needs,
         declared_write_targets: writeTargets,
+        write_contract: stateWriterContract(writeTargets),
         artifact_inventory: inventory,
         included_state_families: needs.filter((name) => STARTUP_ENVELOPE_STATE_FAMILIES.has(name)),
         missing_state_families: missing,