agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/capabilities/document/instructions.js

@@ -0,0 +1,11 @@
+// Markdown instructions served via agentera prime --context document --format json
+export const instructions = JSON.parse(String.raw `"# DOCUMENT\n\n**Documentation Origin: Knowledge Unified, Methodology Enforced, Notation Traced. Encode, Record, Archive**\n\nOwns the docs-first workflow (DTC: Document, Test, Code): document intended behavior before tests and code, generate docs for existing code, maintain docs as projects evolve, verify docs against implementation.\n\nGlyph: **▤** (protocol ref: SG8). Used in the mandatory exit marker.\n\nTwo modes: **create** and **update**. Context-detected: no feature yet = intent-first; code exists = explore and generate.\n\nRead \u0060capability_context.startup.outcome\u0060 and use bounded \u0060closeout_context\u0060 from \u0060agentera prime --context document --format json\u0060 for closeout synchronization startup. For deferred detail, use the matching availability row\u0027s exact \u0060detail_command\u0060. Do not re-encode machine-readable rules in prose. Artifact path resolution is owned by SKILL.md.\n\n---\n\n## State artifacts\n\nDocument writes and reads the docs index and individual doc files across the project.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060docs\u0060 | produces_and_consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060progress\u0060 | consumes | \u0060.agentera/progress.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### docs.yaml shape\n\n\u0060\u0060\u0060yaml\nlast_audit: YYYY-MM-DD\nconventions:\n  doc_root: .\n  style: technical, concise\n  auto_gen: []\n  version_files: []\n  semver_policy:\n    feat: minor\n    fix: patch\n    docs/chore/test: no bump\nmapping:\n  - artifact: VISION.md\n    path: .agentera/vision.yaml\n    producers: [vision, build]\nindex:\n  - document: README\n    path: README.md\n    last_updated: YYYY-MM-DD\n    status: current\n\u0060\u0060\u0060\n\n### Closeout context\n\nStart from \u0060agentera prime --context document --format json\u0060. Read \u0060capability_context.startup.outcome\u0060 and use bounded \u0060closeout_context\u0060 for artifact mappings, version policy, TODO blockers, changelog boundary, progress evidence, and benchmark evidence. Preserve every caveat; for deferred detail, use the matching \u0060capability_context.startup.availability\u0060 row\u0027s exact \u0060detail_command\u0060 before any raw artifact read. Raw artifacts are write targets or last-resort diagnostics, not normal closeout inputs.\n\n---\n\n## Workflow phases\n\nMode-split: detect context first, then run the matching workflow.\n\n| Context | Mode |\n|---------|------|\n| No \u0060.agentera/docs.yaml\u0060 exists | First-run survey |\n| Feature doesn't exist yet, user wants to document intent | Intent-first |\n| Code exists, docs don't | Explore-and-generate |\n| Docs exist, may be stale | Update-and-verify |\n| Broad \"audit the docs\" / \"are docs up to date\" | Update-and-verify |\n\nFor final documentation or metadata synchronization, follow the closeout context startup contract above before reading TODO, docs, changelog, or progress artifacts directly.\n\n### First-run survey (convention detection)\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: explore, propose, write.\n\n### Step 1: Explore structure\n\nDetect documentation conventions:\n\n1. **Doc root**: check docs/, doc/, documentation/, wiki/, or root. Default to root.\n2. **Existing docs**: README, AGENTS.md, CONTRIBUTING.md, API docs, guides\n3. **Auto-generated docs**: TypeDoc, Storybook, OpenAPI/Swagger, GoDoc, Rustdoc, Javadoc. Record each with output path.\n4. **Style**: infer tone, structure patterns, formatting conventions from existing docs\n5. **Version files**: package.json, Cargo.toml, pyproject.toml, etc. Note files and current values. None found = omit versioning from \u0060.agentera/docs.yaml\u0060.\n\n### Step 2: Propose conventions\n\nDraft \u0060.agentera/docs.yaml\u0060 from the artifact schema and observed repository conventions:\n\n1. **Conventions**: doc_root, style, auto_gen from observations. If version files found, populate \u0060version_files\u0060 and ask about semver policy. No version files = omit block.\n2. **Artifact mapping**: paths consistent with project's doc organization\n3. **Index**: all discovered docs (auto-generated = \u0060generated\u0060, existing = \u0060current\u0060)\n\nPresent for user approval. If artifacts exist at root but mapping places them elsewhere, offer to relocate via \u0060git mv\u0060; if declined, update mapping to match actual locations.\n\n### Step 3: Write docs.yaml\n\n**Before writing**, run \u0060agentera check lint --artifact docs --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\nWrite the approved convention map to \u0060.agentera/docs.yaml\u0060. After writing, proceed to the originally requested mode, or stop if the survey was the entire request.\n\n### Intent-first mode (docs before code)\n\nDocs-first workflow: document what a feature SHOULD do before building. Docs become the spec.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: understand, write, update, suggest.\n\n### Step 1: Understand the intent\n\nBrief conversation (2-4 questions): what, who reads it, what format, what detail level.\n\nRead \u0060.agentera/vision.yaml\u0060 for direction/audience. Use decision profile per protocol confidence scale (CS1-CS5) for doc style preferences if available.\n\n### Step 2: Write the documentation\n\nWrite docs in the appropriate location: project-level (README, AGENTS.md) to standard paths, feature docs to the project's docs directory, inline docs to source files.\n\n**Principles**: follow \u0060.agentera/docs.yaml\u0060 style conventions, infer details from existing docs. Write as intended steady state (evergreen, non-temporal). Primary audience first. Concrete examples. DRY across doc files.\n\nWhen presenting drafts, introduce what you wrote and why: what choices you made, what you left out on purpose, what you'd want feedback on. Present draft for approval before writing.\n\n### Step 3: Update docs index\n\nAdd or update the relevant entry in \u0060.agentera/docs.yaml\u0060:\n\n- Document name and path\n- Date written\n- Status: \u0060current\u0060\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) 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### Step 4: Suggest next steps\n\n- Feature docs: suggest ≡ plan to plan implementation\n- Standalone docs: suggest update-and-verify mode later for verification\n\n### Explore-and-generate mode (docs for existing code)\n\nCode exists, docs don't. Read codebase and generate.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: explore, gaps, generate, update.\n\n### Step 1: Explore\n\n1. Map directory structure, read dependency manifests\n2. Read existing docs to see what's already documented\n3. Read key source files: architecture, public APIs, patterns\n4. Read \u0060.agentera/vision.yaml\u0060 for direction/audience. Use \u0060agentera state progress list --limit 20 --format json\u0060 and \u0060agentera state decisions list --limit 20 --format json\u0060 for recent project context; carry returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure into documentation scope instead of raw-reading missing historical context.\n5. \u0060git log --oneline -20\u0060 for context\n\n**Exit-early stop condition**: If \u0060.agentera/docs.yaml\u0060 exists with coverage at 100% and no files have changed since the last document audit (\u0060git log --since\u0060 the last audit date shows no changes), report exit signal \u0060complete\u0060 (EX1): documentation current, and stop.\n\n### Step 2: Identify gaps\n\nCompare what exists against what should be documented: README.md accuracy, AGENTS.md presence, API docs, CLI docs with usage, configuration docs, architectural decision docs.\n\n### Step 3: Generate\n\nWrite docs for gaps, prioritized: (1) README, (2) AGENTS.md, (3) API/CLI docs, (4) architecture docs. Follow \u0060.agentera/docs.yaml\u0060 style conventions.\n\nWhen presenting drafts, introduce what you wrote and why: what you learned from the code, what design choices the doc reflects, what you're less sure about. Present drafts for approval.\n\n### Step 4: Update docs index\n\nCreate or update \u0060.agentera/docs.yaml\u0060 with all items. Edit specific YAML entries when updating status/dates. If \u0060.agentera/docs.yaml\u0060 doesn't exist, run first-run survey first.\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) 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### Update-and-verify mode (audit-driven)\n\nDocs exist but may be out of sync with implementation.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: discover, verify, report, update.\n\n### Step 1: Discover\n\nIdentify all doc files: root (README, AGENTS.md, etc.), directories (docs/, .github/), config comments. Read \u0060.agentera/docs.yaml\u0060 for current index. Track auto-generated docs as \u0060generated\u0060. Skip node_modules/, .git/, vendor/.\n\n### Step 2: Verify\n\nCheck each doc file on two dimensions — content accuracy and prose quality.\n\n**Content accuracy** (per doc file):\n\n- **Gaps**: documented features/APIs/behaviors that don't exist in code\n- **Staleness**: changed signatures, removed features, outdated setup instructions\n- **Redundancies**: duplicated content across doc files\n- **Misalignments**: docs contradict actual code behavior\n\nFor each finding: quote the doc section, reference code location (file:line), explain the discrepancy.\n\n**Prose quality**: run \u0060agentera check lint --artifact docs --file <path>\u0060 on each tracked doc. Report any \u0060[post-audit-flagged]\u0060 markers from prior runs. Skip entries with \u0060generated\u0060 or \u0060missing\u0060 status.\n\n### Step 3: Report and fix\n\nSurface findings at standard severity levels (protocol: SF1-SF3):\n\n- **critical** (SF1): doc section contradicts code, or instructions that would cause user errors\n- **warning** (SF2): verbosity above budgets, abstraction creep, accumulated filler patterns, pre-existing \u0060[post-audit-flagged]\u0060 markers\n- **info** (SF3): minor style issues, single banned pattern in an otherwise clean entry\n\nFor each finding, offer to: fix the doc, file to TODO.md (code is wrong per the docs-first workflow), or skip.\n\n### Step 4: Update docs index\n\nUpdate \u0060.agentera/docs.yaml\u0060 with:\n- Audit date\n- Status changes (■ current / ▣ stale / □ missing)\n- Coverage numbers\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) 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---\n\n## Safety rails\n\n<critical>\n- MUST NOT write or modify documentation without explicit user approval. Present drafts and get confirmation.\n- MUST NOT update docs to match broken code. Per the docs-first workflow, if code diverges from docs, the code is wrong. Document the divergence as an issue in TODO.md.\n- MUST NOT write temporal documentation (changelogs, \"we recently added...\"). Write as the intended steady state: evergreen and non-temporal.\n- MUST NOT duplicate information across doc files. Keep it DRY: reference, don't repeat.\n- MUST NOT write generic filler documentation. Every sentence MUST be specific to this project. If there's nothing useful to say about a section, omit it.\n- MUST NOT skip the verification step in update mode. Every doc claim MUST be checked against code.\n- MUST NOT auto-generate documentation without reading the code it describes. Understanding precedes documentation.\n- MUST NOT mark or imply user-confirmed decision satisfaction — only the user confirms final satisfaction.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060▤ document · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): Documentation was written, updated, or audited successfully; docs index is current, and all drafted content received user approval before writing.\n- **flagged** (EX2): Documentation tasks completed but gaps remain (e.g., some doc files could not be verified against code, coverage is partial, or the audit found issues that were logged but not yet fixed).\n- **stuck** (EX3): Cannot proceed because a user approval step was declined, a required artifact is missing or inaccessible, or a contradicting doc-vs-code situation requires a decision the capability should not make autonomously.\n- **waiting** (EX4): The documentation intent is unclear: the target audience, format, or scope of what to document was not specified and cannot be inferred from the codebase or the docs index.\n\n---\n\n## Cross-capability integration\n\nDocument is part of a twelve-capability suite. It is the documentation layer and owns the docs-first workflow.\n\n### Feeds\n\n- **≡ plan**: In the docs-first workflow, document writes intent docs first, then plan breaks them into implementation tasks. The docs become the spec that plan's acceptance criteria verify against. When the plan includes documentation tasks, document handles them.\n- **⧉ build**: When document writes intent-first docs for a feature that doesn't exist yet, build implements code to match those docs. The docs are the target state; if code diverges from docs, the code is wrong per the docs-first workflow.\n- **♾ profile**: Documentation decisions (what to document, how, at what depth) are signal for profile's extraction scripts.\n\n### Informed by\n\n- **❈ discuss**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Document reads it to understand project context.\n- **⛶ audit**: Health findings may include documentation gaps. Audit's architecture alignment dimension can surface undocumented modules or APIs.\n- **⛥ vision**: \u0060.agentera/vision.yaml\u0060 sets the project's direction and audience. Document reads it to understand who the documentation is for and what tone to use.\n- **◰ design**: \u0060DESIGN.md\u0060 provides visual identity context that document respects when generating user-facing documentation, ensuring docs match the project's declared aesthetic and voice.\n- **♾ profile**: The decision profile calibrates documentation style: the user's preferences for detail level, tone, format, and which docs they consider essential.\n\n### Getting started\n\n**Docs-first workflow**: document before building.\n1. ▤ document: write intent docs for the feature (what it should do, how it should work)\n2. ≡ plan: plan the implementation with acceptance criteria derived from the docs\n3. ⧉ build: build to match the docs\n4. ▤ document: update-and-verify mode to verify docs still match implementation\n\n**Document existing code**: explore-and-generate mode reads the codebase and writes docs for what exists. Review generated docs for accuracy and completeness.\n\n**Project bootstrap**: ⛥ vision → ▤ document (README, AGENTS.md) → ≡ plan → ⧉ build.\n"`);
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Documentation inventory entries, progress cycles, decisions, and health audits use entity authority: every record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through bounded list or exact \`get --id ID\` commands. Start from \`agentera prime --context document --format json\`; read \`capability_context.startup.outcome\` and use a deferred availability row's exact \`detail_command\` for detail. Discover documentation-inventory mutations with \`agentera state docs explain --format json\` and use the typed entity writer; never edit entity paths directly. The docs mapping and policy, vision, changelog, design, and profile remain intentional singletons.
+
+## Workflow phases`)
+    .replaceAll("`.agentera/decisions.yaml`", "the decisions entity view")
+    .replaceAll("`.agentera/progress.yaml`", "the progress entity view")
+    .replaceAll("`.agentera/health.yaml`", "the health entity view");

package/dist/capabilities/index.js

@@ -3,36 +3,38 @@
 // CAPABILITY_INSTRUCTIONS lookup keyed by capability name. The CLI loader
 // imports this barrel from `../capabilities/index.js` so source-mode (vitest)
 // and dist-mode (npm install) resolve the same path.
-import { instructions as hejInstructions } from "./hej/instructions.js";
-import { instructions as visioneraInstructions } from "./visionera/instructions.js";
-import { instructions as resoneraInstructions } from "./resonera/instructions.js";
-import { instructions as inspireraInstructions } from "./inspirera/instructions.js";
-import { instructions as planeraInstructions } from "./planera/instructions.js";
-import { instructions as realiseraInstructions } from "./realisera/instructions.js";
-import { instructions as optimeraInstructions } from "./optimera/instructions.js";
-import { instructions as inspekteraInstructions } from "./inspektera/instructions.js";
-import { instructions as dokumenteraInstructions } from "./dokumentera/instructions.js";
-import { instructions as profileraInstructions } from "./profilera/instructions.js";
-import { instructions as visualiseraInstructions } from "./visualisera/instructions.js";
-import { instructions as orkestreraInstructions } from "./orkestrera/instructions.js";
-export const CAPABILITY_INSTRUCTIONS = {
-    hej: hejInstructions,
-    visionera: visioneraInstructions,
-    resonera: resoneraInstructions,
-    inspirera: inspireraInstructions,
-    planera: planeraInstructions,
-    realisera: realiseraInstructions,
-    optimera: optimeraInstructions,
-    inspektera: inspekteraInstructions,
-    dokumentera: dokumenteraInstructions,
-    profilera: profileraInstructions,
-    visualisera: visualiseraInstructions,
-    orkestrera: orkestreraInstructions,
+import statusInstructions from "./status/instructions.js";
+import { statusStartupInstructions } from "./status/startupInstructions.js";
+import visionInstructions from "./vision/instructions.js";
+import discussInstructions from "./discuss/instructions.js";
+import { instructions as researchInstructions } from "./research/instructions.js";
+import planInstructions from "./plan/instructions.js";
+import buildInstructions from "./build/instructions.js";
+import optimizeInstructions from "./optimize/instructions.js";
+import auditInstructions from "./audit/instructions.js";
+import documentInstructions from "./document/instructions.js";
+import profileInstructions from "./profile/instructions.js";
+import { instructions as designInstructions } from "./design/instructions.js";
+import orchestrateInstructions from "./orchestrate/instructions.js";
+import { preCutoverCommand, preCutoverInstructionBody } from "../cli/preCutoverCommand.js";
+const canonicalInstructions = {
+    status: statusStartupInstructions(statusInstructions),
+    vision: visionInstructions,
+    discuss: discussInstructions,
+    research: researchInstructions,
+    plan: planInstructions,
+    build: buildInstructions,
+    optimize: optimizeInstructions,
+    audit: auditInstructions,
+    document: documentInstructions,
+    profile: profileInstructions,
+    design: designInstructions,
+    orchestrate: orchestrateInstructions,
 };
+export const CAPABILITY_INSTRUCTIONS = Object.fromEntries(Object.entries(canonicalInstructions).map(([capability, body]) => [capability, preCutoverInstructionBody(body)]));
 export function capabilityInstructionModulePath(capability) {
     return `packages/cli/src/capabilities/${capability}/instructions.ts`;
 }
 export function capabilityStartupCommand(capability) {
-    return `agentera prime --context ${capability} --format json`;
+    return preCutoverCommand(`prime --context ${capability} --format json`);
 }
-//# sourceMappingURL=index.js.map

package/dist/capabilities/optimize/instructions.js

@@ -0,0 +1,14 @@
+// Capability instructions for optimize
+// Served via `agentera prime --context optimize --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# OPTIMIZE\n\n**Objective Pursuit: Targeted Iterative Measurement. Experiment, Record, Advance.**\n\nGlyph: ⎘ (protocol ref: SG7).\n\nMetric-driven optimization: improve any measurable property one experiment at a time. User defines the objective, agent writes an eval harness, harness becomes the immutable judge. Improve + pass regression = keep; everything else is discarded.\n\nEach invocation = one experiment. After completing a cycle (orient through log, exit signal reported), **stop**. The next experiment starts only when the user explicitly requests it or switches to ⎈ orchestrate for autonomous multi-experiment execution. A compaction-continue prompt is not consent to start a new experiment.\n\n---\n\n## State artifacts\n\nOptimize reads project state and writes experiment logs. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060objective\u0060 | produces_and_consumes | \u0060.agentera/optimize/<name>/objective.yaml\u0060 |\n| \u0060optimize_harness\u0060 | produces | \u0060.agentera/optimize/<name>/harness\u0060 |\n| \u0060experiments\u0060 | produces_and_consumes | \u0060.agentera/optimize/<name>/experiments.yaml\u0060 |\n| \u0060progress\u0060 | consumes | \u0060.agentera/progress.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060benchmark_context\u0060 | consumes | \u0060agentera prime --context optimize --format json\u0060 |\n| \u0060todo\u0060 | produces | \u0060TODO.md\u0060 |\n\n\u0060objective.yaml\u0060 and \u0060experiments.yaml\u0060 always live under \u0060.agentera/optimize/<objective-name>/\u0060 for the active objective; they are NOT resolved via docs.yaml mapping. Use the selected objective's stable \u0060header.id\u0060 as \u0060OBJECTIVE_ID\u0060. Read experiment history with \u0060agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json\u0060, fetch exact detail with \u0060agentera state experiments get --objective OBJECTIVE_ID --number N --format json\u0060, and publish only through \u0060agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json\u0060. Lists use opaque snapshot cursors, report whole-entry omissions, and preserve full, summary-only, or unavailable detail without fabricating archive history.\n\n### objective.yaml\n\nEvergreen. Created via brainstorm on first run, refined only when the user explicitly asks. Outside those two cases, the agent reads it but never writes it.\n\n\u0060\u0060\u0060yaml\ntarget: Optimization target name\nstatus: active\nobjective: >-\n  Precise metric, current value, and target value, for example reduce p95\n  latency of /api/search from 320ms to under 100ms.\nwhy: >-\n  What changes when the target is hit, who benefits, and what tradeoffs matter.\nmeasurement:\n  command: .agentera/optimize/<objective-name>/harness\n  metric: p95_latency_ms\n  direction: lower\n  baseline: 320\n  target: 100\n  budget:\n    runs: 5\n    time_limit: 10m\nconstraints:\n  - Existing tests must pass.\n  - Public API must not change.\nscope:\n  included: [api/search]\n  excluded: [public_api]\n\u0060\u0060\u0060\n\nThe objective MUST be precise enough to measure, constraints clear enough to enforce, and scope defined enough to prevent wandering. Fixed budgets are part of the measurement contract — keep them in objective.yaml and the locked harness.\n\n### harness\n\nEval script that measures the metric and outputs structured JSON. Written during brainstorm, approved by the user, then **locked**. MUST NOT be modified during optimization cycles.\n\nWraps the project's own tooling (test runners, benchmarks, linters) and translates output into a consistent format. Before writing a harness, inspect the project's existing test, benchmark, lint, or measurement commands.\n\n**Output contract** (minimal):\n\n\u0060\u0060\u0060json\n{\"metric\": <number>, \"direction\": \"higher\"|\"lower\"}\n\u0060\u0060\u0060\n\n**Output contract** (with optional fields for richer signal):\n\n\u0060\u0060\u0060json\n{\"metric\": 85.5, \"direction\": \"higher\", \"unit\": \"%\", \"detail\": \"42/50 tests passing\", \"breakdown\": [{\"name\": \"unit\", \"value\": 95.0}, {\"name\": \"integration\", \"value\": 60.0}]}\n\u0060\u0060\u0060\n\nThe harness is the **immutable ground truth**, separating measurement from optimization. If wrong, the user MUST explicitly ask to rebuild it.\n\n### experiments.yaml\n\n\u0060\u0060\u0060yaml\nexperiments:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    hypothesis: What we expected to improve and why.\n    method: The approach taken to test the hypothesis.\n    change: One-line summary of the code change.\n    metric:\n      before: 320\n      after: 250\n      direction: lower\n      verdict: better\n    regression: pass\n    status: kept\n    commit: <hash>\n    inspiration: External source, if any.\n    conclusion: What the experiment taught.\n    next: What the result suggests trying next.\n    context:\n      intent: Why this experiment was chosen.\n      constraints: Which objective constraints were in play.\n      unknowns: What was uncertain before running it.\n      scope: What scope boundaries were applied.\n\u0060\u0060\u0060\n\nObjective closure is recorded once in \u0060objective.yaml\u0060; do not hand-edit \u0060experiments.yaml\u0060 or append a separate closure record. The last published experiment already records the result that met the target.\n\nThe \"Next\" field from the previous experiment is a suggestion, not a mandate. Re-evaluate fresh each cycle based on the full experiment history.\n\n---\n\n## Workflow phases: The cycle\n\n### Brainstorm\n\nRuns when objective.yaml doesn't exist (first run) or when the user explicitly asks to refine the objective. In all other cases, skip straight to the cycle.\n\n1. **Objective**: \"What metric, current value, target?\" If code exists, run existing test/bench/lint commands first.\n2. **Motivation**: \"Why does this matter? What breaks at current value? What's possible at target?\"\n3. **Constraints**: \"What must NOT break? Off-limits files? Resource limits?\" If a decision profile exists, propose constraints from it.\n4. **Scope**: \"Which parts to focus on? Where are the biggest gains?\" Read codebase to propose informed boundaries.\n\nSynthesize into a precise charter. Before writing objective.yaml, run \u0060agentera check lint --artifact objective --text \"<draft>\"\u0060 to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing. Write to \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060. Present for approval.\n\nWrite the eval harness using the project's own tooling and the objective's measurement fields. The harness MUST output JSON with at least \u0060metric\u0060 and \u0060direction\u0060. Present, explain, get approval, run once to establish baseline.\n\nWhen **refining**, read current objective.yaml, show proposed changes with rationale, get confirmation. If the harness changes, the user MUST approve the new version. After brainstorm, proceed to experiment 1.\n\n### The cycle\n\nStep markers: display \u0060── step N/7: verb\u0060 before each step.\nSteps: orient, analyze, hypothesize, implement, measure, decide, log.\n\n### Step 1: Orient\n\n**Benchmark context**: for benchmark-oriented work, read \u0060capability_context.startup.outcome\u0060 and use bounded \u0060benchmark_context\u0060 from \u0060agentera prime --context optimize --format json\u0060 before direct retained benchmark files. Consume the bounded fields (\u0060latest_report\u0060, \u0060history_summary\u0060, \u0060runtime_coverage\u0060, \u0060state_access_metrics\u0060, \u0060token_impact\u0060, \u0060comparison\u0060, \u0060recommendation\u0060, \u0060manual_refresh\u0060). Do not read \u0060latest-report.json\u0060, \u0060latest-report.md\u0060, or \u0060runs.jsonl\u0060 during normal startup. If incomplete, preserve the caveat and use \u0060capability_context.startup.availability\u0060: run the matching \u0060deferred\u0060 row\u0027s exact \u0060detail_command\u0060 before any direct benchmark diagnostic. Direct benchmark file reads are last-resort diagnostics only. Never run \u0060mage bench:startupState\u0060 automatically; manual-only.\n\nWhen reporting benchmark evidence, preserve caveats about manual-only execution, missing or malformed retained evidence, empty local history, runtime coverage degradation, missing token estimates, non-comparable previous rows, and privacy boundaries. Do not expose raw transcripts, corpus files, intermediates, runtime store paths, session IDs, private salts, generated salted hashes, raw benchmark report bodies, or full local benchmark paths.\n\n**Active-objective inference**: before reading any per-objective artifact, determine which objective is active by inspecting \u0060.agentera/optimize/\u0060:\n\n- No objective subdirectories exist → run the brainstorm.\n- For each subdirectory with an objective.yaml, classify it as closed when \u0060status: closed\u0060. Do not reopen closed objectives.\n- User explicitly names a closed objective → load its artifacts read-only, summarize that it is closed, ask before defining successor work.\n- All subdirectories closed → ask the user for a successor objective.\n- One non-closed subdirectory → use it.\n- Multiple non-closed subdirectories → run \u0060git log -1 --format=%aI -- .agentera/optimize/<name>/experiments.yaml\u0060 for each and pick the most recent.\n- Ambiguous → ask the user to specify.\n\n1. **Experiment history**: run \u0060agentera state experiments list --objective OBJECTIVE_ID --limit 5 --format json\u0060; use exact \u0060get\u0060 only when full detail is needed and preserve returned compatibility, provenance, omission, and detail-availability fields.\n2. **objective.yaml**: the metric, target, constraints, and scope\n3. **Decision profile**: use \u0060status.profile\u0060 from prime. Apply confidence thresholds per protocol.yaml. If missing, proceed without persona grounding but flag it.\n4. **Project discovery** (experiment 1 or when unfamiliar): map directory structure within scope, read dependency manifests, and read README.md, AGENTS.md.\n5. \u0060git log --oneline -20\u0060 for recent changes\n\nBefore experimenting: in your response, list the current baseline, target, status, and constraints from objective.yaml.\n\n**Objective closure procedure**: when closing an objective, update objective.yaml with canonical closed state: \u0060status: closed\u0060, \u0060closed_at: <ISO-8601 UTC timestamp>\u0060, \u0060final_value: <value>\u0060, \u0060target: <target>\u0060, and \u0060reason: <reason>\u0060. Do not append a separate experiments closure entry; the objective document owns closure state.\n\n**Exit-early stop condition**: If objective.yaml or experiments.yaml evidence shows the target is already met and the objective is not already closed, run the objective closure procedure with reason \u0060already met at startup\u0060, report exit signal \u0060complete: objective achieved\u0060, and stop before Analyze.\n\n### Step 2: Analyze\n\nRun two checks:\n\n**2a. Experiment history**: if experiments.yaml has prior entries, run:\n\n\u0060\u0060\u0060bash\nagentera state experiments list --objective OBJECTIVE_ID --limit 5 --format json\n\u0060\u0060\u0060\n\nOutputs recent experiment status counts, metric deltas, conclusions, and next-step notes.\n\n**2b. Current metric**: run the eval harness to get the baseline for this experiment:\n\n\u0060\u0060\u0060bash\nchmod +x .agentera/optimize/<objective-name>/harness && .agentera/optimize/<objective-name>/harness\n\u0060\u0060\u0060\n\nParse the JSON output. Record the current metric as the baseline.\n\n**Plateau detection**: if \u0060plateau_detected: true\u0060 (no improvement in 3+ experiments), flag explicitly. Consider a radically different approach, ⬚ research, or escalate to the user.\n\n### Step 3: Hypothesize\n\nFormulate a single, focused hypothesis.\n\nEffort-bias check: if one hypothesis took more effort to construct, reset before selection. Choose by experiment history, expected metric impact, risk, constraints, and smallest falsifiable test; construction effort is not evidence.\n\n1. **Review history**: what's been tried, what worked, what failed?\n2. **Seek inspiration**: for non-trivial domains, 2-3 targeted web queries for techniques, libraries, or patterns.\n3. **Formulate**: \"I expect [change] to improve the metric because [reasoning].\" MUST be falsifiable.\n\nBe conservative early; escalate if conservative approaches plateau.\n\n### Step 4: Implement\n\n**Pre-spawn Git commit**: before creating the worktree, commit any pending artifact changes so the subagent branches from current state. Run \u0060git status --porcelain\u0060. If empty, skip to spawn. Stage only the artifact files this session wrote. Commit with \u0060chore(optimize): checkpoint before worktree dispatch\u0060. Do not pass \u0060--no-verify\u0060. If pre-commit hooks reject the commit: fix and retry. If retry also fails, abort the spawn.\n\n**Stale-base awareness**: before spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If the count is greater than zero, the worktree will be based on a stale commit. Proceed with spawn, but in Step 5 do NOT merge the worktree branch: fetch the diff and apply it to the main checkout. Re-run the eval harness in the main checkout.\n\nUse the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) — never spawn by running \u0060agentera optimize\u0060 or other capability-name CLI commands.\n\nSpawn an implementation sub-agent in a worktree (\u0060isolation: \"worktree\"\u0060) with:\n\n- The hypothesis from step 3\n- Relevant context files (objective.yaml, recent experiments, source files being modified)\n- Clear constraint: implement the hypothesis and nothing else\n\n\u0060\u0060\u0060\nYou are implementing one optimization experiment for [project].\n\n## Hypothesis\n[The hypothesis]\n\n## Context\n- Current metric: [value] ([unit])\n- Target: [target value]\n- Scope: [files/modules in scope from objective.yaml]\n\n## Constraints\n- Implement ONLY what the hypothesis describes. No scope creep.\n- Do NOT modify the eval harness at .agentera/optimize/<objective-name>/harness.\n- Do NOT modify objective.yaml or experiments.yaml.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Keep the change as small as possible while testing the hypothesis.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\nWait for the implementation agent to complete before proceeding.\n\n### Step 5: Measure\n\nAfter implementation completes, run two checks in sequence:\n\n**5a. Regression check**: run the project's existing test/build/lint suite. If the regression check fails, **stop here**. The experiment is discarded. Do not run the eval harness. Log the regression failure and move to Step 7.\n\n**5b. Metric measurement**: run the eval harness. Parse the JSON output. Compare the new metric against the baseline from Step 2.\n\n### Step 6: Decide\n\nPresent the decision conversationally: what the numbers say and what you'd recommend, then the structured gate below makes it official.\n\nApply the decision gate. **Both conditions MUST be true** to keep an experiment:\n\n1. **Regression check passed** (from Step 5a)\n2. **Metric improved**: the new value is strictly better than the baseline, in the direction declared by the harness (lower for \"lower\", higher for \"higher\")\n\nIf both pass: **keep**. Merge the worktree branch into the current branch. Commit with a conventional commit message:\n\n\u0060\u0060\u0060\nperf(scope): summary of what improved the metric\n\nMetric: <before> → <after> ⮉ (<unit>)\n\u0060\u0060\u0060\n\nIf either fails: **discard**. The worktree is abandoned. No merge. No commit.\n\nIf the kept experiment's new metric also meets the target in the harness direction, mark the objective as ready for closure after the experiment entry is logged in Step 7.\n\n### Step 7: Log\n\nBefore writing, run \u0060agentera check lint --artifact experiments --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 [post-audit-flagged] if still failing.\n\nSummarize the experiment for the user before writing the log: what moved, what didn't, and what it suggests trying next. Then write the structured record.\n\nWrite the schema-valid experiment entry without its CLI-owned \u0060number\u0060 field to a temporary YAML/JSON input, then run \u0060agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json\u0060. The writer validates identity and schema, durably publishes immutable full detail, atomically updates the bounded projection, and makes byte-equivalent retries idempotent.\n\nIf Step 6 marked the objective as ready for closure, immediately run the objective closure procedure with reason \u0060experiment met target\u0060. This closure is part of the same log step, after the experiment result is recorded.\n\nDo not compact or rewrite experiment history manually; publication owns the immutable archive and 10/40/50 projection.\n\nThen stop. One experiment complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT modify the eval harness during an optimization cycle. Only during brainstorm (bootstrap) or user-requested refinement.\n- MUST NOT modify objective.yaml during a cycle except for canonical closure when the target is met. Other edits only happen during brainstorm or refine.\n- MUST NOT bypass the project's test/lint/build suite. Regression check before every metric measurement. Regression failure = automatic discard.\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 keep an experiment that causes a regression, even if the metric improved.\n- One experiment per invocation. MUST NOT attempt multiple experiments.\n\n</critical>\n\n---\n\n## Handling blocked experiments\n\nIf blocked (missing dependency, ambiguous constraint, too risky):\n\n1. Publish a schema-valid discarded experiment record with the blocker in its conclusion and context\n2. Formulate a different hypothesis and complete a full experiment 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─── ⎘ optimize · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): One experiment completed the full cycle: hypothesis formulated, implementation dispatched, regression check passed, metric measured, decision made (kept or discarded), and the experiment published through the typed writer.\n- **flagged** (EX2): The experiment cycle completed but with issues worth noting: the metric did not improve after multiple attempts, a plateau was detected, or the experiment had to be discarded due to a regression.\n- **stuck** (EX3): Cannot proceed because objective.yaml is missing and the brainstorm cannot be completed without user input, the eval harness is broken and cannot be repaired without user approval, or the regression check infrastructure is unavailable.\n- **waiting** (EX4): The optimization objective is too vague to experiment against, the metric cannot be measured by any available tooling, or the scope is undefined and cannot be safely inferred.\n\nBefore reporting any status, inspect the last 3 entries in \u0060.agentera/progress.yaml\u0060 via \u0060agentera state progress\u0060. If all 3 entries record failed or discarded experiments, this constitutes 3 consecutive failures: **stop the cycle**, log the failure pattern to TODO.md, and surface the situation to the user with a recommended course of action. Do not attempt a 4th consecutive experiment on the same problem.\n\nAfter reporting an exit signal, the cycle is over — the next experiment requires an explicit user request or ⎈ orchestrate.\n\n---\n\n## Cross-capability integration\n\nOptimize is part of a twelve-capability suite.\n\n### Invokes ⬚ research\n\nWhen the Hypothesize step needs external techniques (especially after a plateau), search for approaches the way ⬚ research would. Read the source deeply, extract transferable patterns, and fold them into the next hypothesis.\n\n### Reads ♾ profile output\n\nEvery experiment reads \u0060status.profile\u0060 from prime. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions. Stale or missing profile is a caveat, not approval to refresh profile state.\n\n### Uses ❈ discuss for objective decisions\n\nWhen the brainstorm surfaces ambiguity about what to optimize (competing metrics, unclear constraints, or tradeoffs between measurement approaches), suggest ❈ discuss to deliberate first. During Orient, use \u0060agentera state decisions list --limit 20 --format json\u0060 for prior deliberation context and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n\n### Audited by ⛶ audit\n\nWhen an audit reveals a poor dimension grade with a clearly measurable improvement path (test coverage, complexity score, dependency count), the finding can become an optimization objective. ⛶ audit may suggest ⎘ optimize when the metric and direction are clear.\n\n### Fed by ≡ plan\n\nWhen a plan includes optimization-shaped tasks (improving a measurable metric), plan can delegate those tasks to optimize. The plan's acceptance criteria inform the optimization objective.\n\n### Fed by ⧉ build\n\nWhen build picks optimization-shaped work, it delegates to optimize. Build provides the context; optimize runs the experiment loop.\n\n### Getting started\n\n**First optimization**: run \u0060/agentera profile\u0060 to generate or refresh the decision profile (skip if recent). Run \u0060/agentera optimize\u0060; the first run detects no objective.yaml, runs the brainstorm to define the objective and write the eval harness, then proceeds to experiment 1.\n\n**Resuming**: run \u0060/agentera optimize\u0060; if objective.yaml and the harness exist, experimenting starts immediately. Reads bounded experiment history with objective-scoped list/get commands.\n\n**Changing the target**: edit objective.yaml directly, or tell optimize to \"refine the objective\" for a guided session. If the measurement approach needs to change, the harness MUST be rebuilt and re-approved.\n\n**Drawing in external techniques**: run \u0060/agentera research <url>\u0060 with a relevant article, repo, or resource. The analysis surfaces optimization techniques applicable to the objective. The next experiment picks it up from the inspiration analysis.\n"`);
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Objectives, experiments, progress cycles, and decisions use entity authority: each record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through bounded list or exact \`get --id ID\` commands. Use \`agentera state objective explain\` and \`agentera state experiments explain\` before typed entity writes; never edit entity paths directly. The benchmark harness, TODO, docs policy, and profile retain their declared file or singleton boundaries.
+
+## Workflow phases`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("agentera state experiments get --objective OBJECTIVE_ID --id ID", "agentera state experiments get --id ID")
+    .replaceAll("--task N", "--id ID")
+    .replaceAll("`.agentera/progress.yaml`", "the progress entity view")
+    .replaceAll("`.agentera/decisions.yaml`", "the decisions entity view");

package/dist/capabilities/orchestrate/instructions.js

@@ -0,0 +1,42 @@
+// 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\nRead \u0060capability_context.startup.outcome\u0060 and use bounded \u0060orchestration_context\u0060 from the same capsule for task selection and evaluator handoff. For deferred detail, run the matching \u0060capability_context.startup.availability\u0060 row\u0027s exact \u0060detail_command\u0060 before any raw diagnostic. Raw reads are last-resort diagnostics, not normal startup.\n\nThe \u0060agentera\u0060 CLI is a state interface. Do not run capability-name commands such as \u0060agentera build\u0060 or \u0060agentera plan\u0060.\n\n| Artifact | Role | Purpose |\n|----------|------|---------|\n| \u0060plan\u0060 | produces_and_consumes | Task queue. Use \u0060orchestration_context.task_queue\u0060 and \u0060selected_next_task\u0060; update status (pending → complete/blocked) only after evaluation. |\n| \u0060progress\u0060 | consumes | Cross-cycle context. Use \u0060orchestration_context.progress_verification\u0060; dispatched capabilities write their own entries. |\n| \u0060health\u0060 | consumes | Health context after plan completion to decide whether to start a new plan. |\n| \u0060todo\u0060 | produces | Blocked task logging. Write when a task exhausts its retry budget. |\n| \u0060decisions\u0060 | consumes | Decision context. Use included caveats or \u0060agentera state decisions list --limit 20 --format json\u0060; preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060. |\n| \u0060vision\u0060 | consumes | Direction context for bootstrap. If missing from context, treat as a caveat. |\n| \u0060profile\u0060 | consumes | Persona context. Preserve stale or missing caveats; do not refresh profile during orchestration. |\n| \u0060docs\u0060 | consumes | Artifact path resolution for write targets. |\n\n### Decision satisfaction authority\n\nWhen orchestration touches decision satisfaction, agents may mark provisional satisfaction with evidence only. Orchestrate MUST NOT mark, infer, or user-confirm final satisfaction; only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in dispatch and evaluation context.\n\nVisual tokens: \u0060skills/agentera/protocol.yaml\u0060 (task states VT1-VT4, glyph SG12, exit signals EX1-EX4, severity SI1-SI4, decision labels DL1-DL3).\n\n---\n\n## The orchestration loop\n\nThe orchestrator follows a deterministic state machine. It does not reason creatively about orchestration; it follows the loop.\n\n### Step 0: Assess\n\nStart from \u0060agentera prime --context orchestrate --format json\u0060. Check \u0060capability_context.startup.outcome\u0060, its availability rows, 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 returned startup caveats as context.\n- **Plan exists, but blocked or incomplete tasks remain**: do not archive it as successful completion. Route to the orchestration loop or replanning so incomplete evidence stays visible.\n- **Plan exists, tasks pending**: proceed to the loop using \u0060orchestration_context\u0060 task selection.\n\n**Staleness check** (plan completion): When all tasks are complete, check whether delegated capabilities updated their expected artifacts.\n\n1. **Identify delegated capabilities** from plan task history and progress summary in CLI context.\n2. **Compare modification dates**: for each expected artifact, check \u0060git log -1 --format=%aI -- <path>\u0060 against the plan's creation date. An artifact is stale if it was not modified since the plan's creation and the owning capability was delegated at least once during the plan.\n3. **Surface findings**: include stale artifact findings as informational context for the next plan cycle. Archive the plan with \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming and active-plan removal.\n\n---\n\nStep markers: display \u0060── task N · step M/5: verb\u0060 before each step in the loop. N is the task number from the selected orchestration context task.\n\n### Step 1: Select task\n\nUse \u0060orchestration_context.selected_next_task\u0060 when present. Otherwise, use \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060: pick the first task whose dependencies are complete. Treat \u0060orchestration_context.task_queue.blocked_tasks[*].blocked_reasons\u0060 as the dependency explanation.\n\nIf no tasks are eligible (all remaining tasks are blocked by incomplete dependencies), report \u0060stuck\u0060 with the dependency chain.\n\nUse decision state or caveats from the returned context first. If decisions are missing from startup context, run \u0060agentera state decisions list --limit 20 --format json\u0060. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in dispatch and evaluation context instead of filling gaps by reconstruction.\n\n### Step 2: Delegate\n\nInfer which capability handles the task based on its description:\n\n| Task signals | Target capability |\n|--------------|-------------------|\n| Implementation, building, coding, feature, fix, refactor | ⧉ build |\n| Documentation, docs, README, CHANGELOG | ▤ document |\n| Health audit, architecture review, code quality check | ⛶ audit |\n| Research, external patterns, library evaluation | ⬚ research |\n| Optimization, performance, metric improvement, benchmark | ⎘ optimize |\n| Visual identity, design tokens, DESIGN.md | ◰ design |\n| Version bump | ⧉ build (with bump instructions from docs artifact) |\n\nIf the task does not clearly map, default to ⧉ build.\n\nSpawn the target capability through the host-provided worker facility. Do not run capability-name CLI commands; the \u0060agentera\u0060 CLI remains a state interface.\n\n\u0060\u0060\u0060\nYou are executing a planned task for [project].\n\n## Task\n[Task title and description from selected_next_task]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria from selected_next_task or evaluator_handoff]\n\n## Context\n[Any relevant context from orchestration_context: related decision entries or caveats,\nhealth/TODO findings, prior task results, stale app/profile caveats, retry-state\nprovenance. Keep brief.]\n\n## Constraints\n- Execute ONLY this task. No scope creep.\n- Follow existing code patterns and conventions.\n- Use the host-provided worker facility (for example, Task) for the selected capability.\n- Commit your changes with a conventional commit message.\n- You are working on a plan-driven task. Update the task status in the plan artifact\n  to ■ complete when done.\n\u0060\u0060\u0060\n\nWait for the task-notification result.\n\n### Step 3: Evaluate\n\nEvaluation has two surfaces in sequence: an orchestrator-side presence check using latest progress verification, then an audit delegation whose prompt is extended with an evidence audit. Both surfaces must run before the task can be resolved.\n\n**Surface 1: Presence check from progress verification**\n\nWhen the delegated capability was build (or any capability that produces progress cycle entries), perform a cheap evidence presence check before spawning audit:\n\n1. Start with \u0060orchestration_context.progress_verification\u0060 and its \u0060latest_progress_verification_pointer\u0060.\n2. If unavailable or incomplete, run \u0060agentera state progress list --limit 20 --format json\u0060 before any raw artifact read.\n3. Look for a non-empty \u0060verified\u0060 field in the latest relevant progress entry.\n4. **Present and non-empty**: proceed to Surface 2.\n5. **Missing or empty**: treat the task as a failed evaluation. Go straight into Step 4's FAIL branch with \"missing or empty \u0060verified\u0060 field in progress Cycle N\" as the failure reason.\n\n**Surface 2: Audit delegation with evidence audit**\n\nOnce the presence check passes, spawn audit as a subagent to verify the work:\n\n\u0060\u0060\u0060\nYou are evaluating a completed task for [project].\n\n## Task that was completed\n[Task title and description from evaluator_handoff]\n\n## Acceptance criteria to verify\n[The task's Given/When/Then criteria from evaluator_handoff]\n\n## What to check\n- Verify each acceptance criterion against the current codebase state.\n- Check for unintended side effects from the implementation.\n- Verify the project's test/build suite still passes.\n\n## Verification evidence audit\n- Use the latest progress verification pointer and \u0060verified\u0060 evidence supplied by\n  the orchestration context or \u0060agentera state progress list --limit 20 --format json\u0060.\n- Compare the recorded evidence to the task's acceptance criteria.\n- Report whether the evidence substantiates the criteria or is merely trivially\n  populated (e.g., \"tests pass\" without any observation of the actual feature\n  running counts as insufficient).\n- If the field is \u0060N/A: <tag>\u0060, confirm the tag is drawn from the allowlist\n  (\u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060,\n  \u0060chore-build-config\u0060, \u0060test-only\u0060) AND that the tag fits the nature of the work.\n- If the field is a free-form N/A rationale, confirm it is at least 8 words long AND\n  actually explains why the change has no observable behavior.\n- Flag the task as FAIL on the evidence audit if the recorded \u0060verified\u0060 content\n  does not substantiate the acceptance criteria.\n\n## Returned startup 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 bounded startup detail commands.\n- MUST NOT run tests, builds, linters, or implementation project commands directly. Delegated capabilities handle all verification.\n- MUST NOT modify the vision artifact. The orchestrator reads direction; it does not set it.\n- MUST NOT delegate to a capability without an active plan task justifying it (except during bootstrap in Step 0).\n- MUST NOT push to any remote. Local operations only.\n- MUST NOT retry a task more than 2 times. After the second failure, mark blocked and move on.\n- MUST NOT skip evaluation. Every completed task must be verified by audit before being marked complete.\n- MUST NOT make implementation decisions. Delegate to the appropriate capability.\n- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries. Orchestrate changes plan lifecycle state only through \u0060agentera state plan set-status ...\u0060 and \u0060agentera state plan archive\u0060.\n- MUST NOT research external patterns or libraries. Delegate to research.\n- MUST NOT mark, infer, or user-confirm final decision satisfaction. Only the user confirms. Preserve caveats for missing, compacted, open, provisional, or review-needed satisfaction state.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⎈ orchestrate · <status>\u0060 on its own line, followed by a summary sentence. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what needs attention.\n\n- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.\n- **flagged** (EX2): The plan was executed but with issues: one or more tasks were blocked after exhausting retries, or the post-plan health check revealed problems. Each concern is listed explicitly.\n- **stuck** (EX3): Cannot proceed because the plan has circular dependencies preventing any task from becoming eligible, no target capabilities are available to delegate, or file access prevents reading or updating artifacts.\n- **waiting** (EX4): No plan exists and the bootstrap chain cannot proceed because the vision artifact is absent and the user has not confirmed how to create one, or a delegated capability returned \u0060waiting\u0060 status requiring user input.\n\n### Loop stop condition\n\nEach task gets max 2 retries before being blocked. Additionally, if 3 consecutive different tasks all fail evaluation (even after their retries), orchestrate stops the session and escalates:\n\n1. **Stop**: do not delegate more tasks.\n2. **Log**: file the pattern to TODO.md with what was attempted across the 3 tasks and what appears systematically wrong.\n3. **Surface**: tell the user and recommend a course of action (e.g., \"⛶ audit for a full audit\", \"❈ discuss to reconsider the plan\", \"the plan may need replanning via ≡ plan\").\n\n---\n\n## Cross-capability integration\n\nOrchestrate is the orchestration layer that chains all other capabilities together. It delegates through the host-provided worker facility. Every supported runtime discovers Agentera through the canonical shared skill and uses the CLI for behavior and state; Agentera ships no runtime-native delegation descriptors. Orchestrator-side instructions, retry logic, and audit evaluation gating stay unchanged across runtimes; only the host-provided worker facility differs.\n\n### Delegation targets\n\n- **⧉ build**: Implementation, feature, fix, refactor tasks. Build runs its full cycle as a subagent and writes progress and changelog entries.\n- **⛶ audit**: Two roles — evaluator after each task completion (verifying acceptance criteria), and health checker after plan completion (producing health grades). Audit is the discriminator in the evaluate-then-proceed pattern.\n- **▤ document**: Documentation tasks — docs updates, README changes, documentation coverage.\n- **⬚ research**: Research tasks. During bootstrap, orchestrate chains research for vision-gap analysis before plan creates a plan.\n- **⎘ optimize**: Optimization-shaped tasks (metric improvement, performance tuning) route to optimize.\n- **◰ design**: Visual identity tasks (DESIGN.md updates, design token changes).\n- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.\n\n### State consumers\n\n- **❈ discuss**: Decision state provides firm constraints during task selection. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 from returned decision entries.\n- **⛺ vision**: Direction context during bootstrap. If vision is missing, preserve the caveat and ask before creating direction.\n- **♾ profile**: Persona context for calibrating delegation. Do not refresh profile state during orchestration; if unavailable, proceed without persona grounding and preserve the caveat.\n\n### When to use orchestrate\n\nExecute an existing plan: create the plan first (\u0060/agentera plan\u0060), then run \u0060/agentera orchestrate\u0060 to execute it with evaluation gating.\n\nFull autonomous session: \u0060/agentera orchestrate\u0060 with no plan triggers bootstrap (research → plan → execute).\n\nAfter a deliberation: \u0060/agentera discuss\u0060 → \u0060/agentera plan\u0060 → \u0060/agentera orchestrate\u0060.\n\nUse orchestrate instead of a host loop for plan-aware, evaluated, multi-cycle execution. Use it when the user explicitly requests autonomous multi-task execution.\n"`);
+export default `${instructions
+    .replace(/## State artifacts[\s\S]*?## The orchestration loop/, `## State artifacts
+
+Plans, tasks, progress cycles, health audits, and decisions use entity authority: every record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through bounded list or exact \`get --id ID\` commands. Trust \`agentera prime --context orchestrate --format json\`; read \`capability_context.startup.outcome\` and use a deferred availability row's exact \`detail_command\` for detail. Discover plan mutations through \`agentera state plan explain --verb <verb> --format json\`; task writes always use the task's bare ID. Never edit entity paths directly.
+
+Advance tasks with \`agentera state plan set-status --id ID\` and persist evaluator outcomes with \`agentera state plan record-evaluation --id ID\`. A superseded task is terminal, satisfies dependencies, and stays out of ready and blocked queues; record it only through \`agentera state plan supersede --id ID --by COMPLETED_ID --reason "..." --format json\`. Every replacement must be complete with latest persisted PASS before supersession.
+
+When competing open plans block startup, do not infer predecessor or successor roles from list order. Use \`agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json\` only after canonical evidence establishes the complete recovery pair.
+
+## The orchestration loop`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replace("task N · step M/5", "task ID · step M/5")
+    .replace("N is the task number from the selected orchestration context task.", "ID is the bare ID from the selected orchestration context task.")
+    .replace(/- \*\*Plan exists, `header\.status: complete`, and all tasks complete\*\*:[\s\S]*?---\n\nStep markers/, () => [
+    "- **Plan exists, `active: true` and `complete_plan: true`**: terminal-open closure. This is not bootstrap. Keep the plan open while completing the closure sequence; do not call the archive route.",
+    "- **Plan exists, but blocked or incomplete tasks remain**: do not complete it as successful work. Route to the orchestration loop or replanning so incomplete evidence stays visible.",
+    "- **Plan exists, tasks pending**: proceed to the loop using `orchestration_context` task selection.",
+    "",
+    "**Terminal-open closure sequence**: complete every step while `active: true` and `complete_plan: true`.",
+    "",
+    "1. **Assess staleness**: identify delegated capabilities from plan task history and progress summary in CLI context. For each expected artifact, compare `git log -1 --format=%aI -- <path>` with the plan creation date. An artifact is stale only when its owner was delegated and it was not modified since that date.",
+    "2. **Delegate Audit**: request a limited post-plan health result covering the staleness assessment and closure evidence. Preserve returned caveats and require PASS or WARN/FAIL findings with evidence.",
+    "3. **PASS only — publish health before plan completion**: discover `agentera state health explain --verb append --format json`, then publish one typed health record with `agentera state health append --input PATH --format json`. Use only the canonical `artifact_freshness` dimension. Its summary and evidence state the terminal-task scope, staleness result, and Audit verdict; do not represent this limited closure check as a codebase-wide audit.",
+    "4. **PASS only — complete the open plan**: after the health writer confirms publication, run `agentera state plan set-plan-status --status complete --format json`. Do not call `agentera state plan archive`; archive history is not part of terminal-open closure.",
+    "5. **WARN or FAIL requiring follow-up**: keep the plan open, surface the cited finding and staleness context, and route it to the applicable task/replanning path. Do not publish a PASS closure record, complete the plan, or call an archive route.",
+    "",
+    "---",
+    "",
+    "Step markers",
+].join("\n"))
+    .replace("- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries. Orchestrate changes plan lifecycle state only through `agentera state plan set-status ...` and `agentera state plan archive`.", "- MUST NOT write to progress or changelog. Dispatched capabilities write their own entries. During terminal-open closure only, Orchestrate may publish the limited typed health record, then change plan lifecycle state through `agentera state plan set-plan-status --status complete --format json`; it MUST NOT invoke the archive route.")
+    .replace("- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.", "- **complete** (EX1): All plan tasks are terminal, the limited health check passed, its typed health record was published, and the open plan was set complete without archiving.")
+    .replace("- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.", "- **≡ plan**: When no plan exists, including after successful terminal-open closure removes the active plan from selection, orchestrate invokes plan to create the next plan.")}
+
+## Evaluation Retry State
+
+After every evaluator verdict, persist it with \`agentera state plan record-evaluation --id ID --attempt-id ATTEMPT --verdict {pass,fail} --provenance SOURCE --format json\` before marking the task complete. A failed verdict also requires \`--failure-evidence\`. Reuse the same stable attempt ID after an interrupted retry; the writer owns attempt counts, retains the latest failure evidence and provenance, and blocks the task after its second failed evaluation. The writer's one terminal exception is recovery for persisted out-of-order replacement state: while the plan remains open, an unevaluated complete task named in a same-plan superseded predecessor's \`superseded_by\` may receive its first PASS only. This is not the normal workflow. Do not reconstruct retry state from conversation memory or modify decision satisfaction.
+`;

package/dist/capabilities/plan/instructions.js

@@ -0,0 +1,33 @@
+// 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 list --limit 20 --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 guidance**: read \u0060capability_context.startup.outcome\u0060, \u0060capability_context.startup.availability\u0060, and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context plan --format json\u0060. Use bounded plan detail already served for an \u0060included\u0060 row; for a \u0060deferred\u0060 row, run its exact \u0060detail_command\u0060 before a raw plan diagnostic. Raw plan artifact access is for writing, archiving, validation, or corruption diagnostics. The runtime owns the planning-level taxonomy, required step list, step-marker format, task-coherence rule, 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 are orient, specify, review, audit, write, and handoff; 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). Read \u0060capability_context.startup.outcome\u0060 and treat \u0060capability_context.startup.availability\u0060 as the inventory: use an \u0060included\u0060 family summary already served in context; for \u0060deferred\u0060 detail, run that row\u0027s exact \u0060detail_command\u0060 before any 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 list --limit 20 --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**: Ordered tasks, each one build cycle, within a coherent lifecycle boundary. Split only when work crosses a real lifecycle or coherence boundary. 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- **Unknown identification**: every full plan surfaces at least one consequential 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- Unknowns 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: Validate and publish\n\nOptionally run \u0060agentera check lint --artifact plan --file PATH --strict --format json\u0060 for early draft feedback. The typed writer is the sole publication gate: it validates strict prose lint and schema against the final candidate before publishing.\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 the final bytes, 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: 2026-07-13\n  status: open\n  title: \"Plan: Short Title\"\nwhat: Deliver one bounded outcome.\nwhy: Keep the work ready for one build cycle.\nconstraints: Preserve the stated delivery boundary.\noverall_acceptance: GIVEN the plan is published WHEN build reads it THEN the next task is clear.\nscope:\n  included: [bounded outcome]\n  excluded: [unrelated work]\ntasks:\n  - number: 1\n    name: Deliver outcome\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN the work is complete WHEN behavior is checked THEN the outcome is available.\nsurprises: []\n\u0060\u0060\u0060\n\n#### Full plan format\n\nOmit \u0060rejected:\u0060 when no critic finding is dismissed; never write an empty \u0060rejected: []\u0060 section.\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: 2026-07-13\n  status: open\n  reviewed: 2026-07-13\n  critic_issues: \"1 found, 0 addressed, 1 dismissed\"\n  title: \"Plan: Short Title\"\nwhat: Deliver a validated multi-task outcome.\nwhy: Keep dependent work behaviorally ordered.\nconstraints: Preserve the stated delivery boundary.\noverall_acceptance: GIVEN all tasks complete WHEN the plan is evaluated THEN the intended outcome is available.\nscope:\n  included: [validated outcome]\n  excluded: [unrelated work]\n  deferred: []\ndesign: Sequence observable outcomes without prescribing implementation.\nunknowns:\n  - question: \"Will the dependent outcome remain necessary after task 1?\"\n    affects_task: 2\n    resolve_by: \"Use task 1 evidence before beginning task 2.\"\nrejected:\n  - issue: \"Specify an implementation library in task acceptance.\"\n    rationale: \"Behavioral acceptance remains implementation-independent.\"\ntasks:\n  - number: 1\n    name: Establish outcome\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN the first task completes WHEN behavior is checked THEN its outcome is available.\n  - number: 2\n    name: Verify dependent outcome\n    depends_on: [\"1\"]\n    status: pending\n    acceptance:\n      - GIVEN task 1 completes WHEN the dependent behavior is checked THEN its outcome is available.\nsurprises: []\n\u0060\u0060\u0060\n\n### Step 5: 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 is non-empty, name the unresolved questions 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 keep all tasks within a coherent lifecycle boundary. Split only at real lifecycle or coherence boundaries; do not split solely to satisfy an arbitrary task count.\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
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Plans and tasks use entity authority: each plan and task has \`id\` and \`artifact\` and lives in one writer-owned entity file; task relationships carry the bare plan ID. Read plans and tasks through bounded list or exact \`get --id ID\` commands. Discover creation and mutation contracts with \`agentera state plan explain --verb <verb> --format json\`, and use bare task IDs for task writes. Never edit entity paths directly. Vision, docs policy, design, changelog, and profile retain their declared singleton boundaries.
+
+Create with \`agentera state plan create --input PATH --format json\`. Task numbers and dependency values in that one atomic create document are create-local symbolic ordinals; the writer removes them and publishes bare ten-letter envelope IDs. A source \`header.id\` is legacy migration-only and never a selector. Append a task with \`agentera state plan append [--plan PLAN_ID] --input TASK.yaml --format json\` and patch one with \`agentera state plan update --id TASK_ID [--plan PLAN_ID] --input TASK-PATCH.yaml --format json\`; post-publication payloads contain only mutable task content and all task relationships use bare ten-letter IDs. Keep status, supersession, evaluation, plan lifecycle, and archive changes as flag-only transitions. Archive completed plan entities with \`agentera state plan archive --format json\`. Read profile grounding only from the \`content\` returned by \`agentera report profile-grounding --format json\` when its shared validity is \`valid\`; preserve exact absent or repair-needed recovery and never direct-read PROFILE.md. The grounding command excludes the owned personal Glossary section and fails closed on invalid sources.
+
+### Governed terminology advice
+
+At initial meaning-sensitive planning input, identify the requested term from that current input and invoke the exact structured, headless \`agentera report glossary-advice --input <file|-> --format json\` interface. Invoke it again only for a later user-authored change to scope, requirements, constraints, task or overall acceptance, or clarification that can alter the affected meaning. Do not invoke it for unchanged replay, artifact rendering, tool output, evaluator text, unrelated turns, background rereads, or control-only continuation. Use only the current bounded event input; never scan a persistent or unbounded transcript.
+
+Use only \`advice.applicable_meaning\` with \`advice.applicable_owner\` for affected planning. An exact project meaning governs; a personal fallback applies only when the CLI proves a valid project gap. Definitions from personal/profile glossary data are transient inputs: derive the needed behavioral requirement but never copy or quote the definition into plan scope, requirements, constraints, tasks, task or overall acceptance, diagnostics, or handoff. A term already supplied by the user may remain. Do not expose unrelated glossary data or silently infer that differently named terms are equivalent.
+
+Determine mode from explicit signals in this order. Explicit delegated or orchestrated no-pause execution is autonomous. Otherwise, direct user invocation with an available clarification turn is interactive. Unknown, ambiguous, or conflicting mode evidence fails safe to interactive clarification and \`waiting\`. Never infer autonomy from silence, timeout, or elapsed time.
+
+In interactive mode, when \`review\` requires acknowledgment and ambiguity could alter downstream requirements, first emit one focused clarification, then wait for the user answer, refresh advice for only that affected term, and only then finalize affected scope, requirements, constraints, tasks, or acceptance. Ground any resolved requirement only in the user-authored clarification, never hidden candidate data. Preserve Plan's ordinary clarification and approval gates: consumer clarification is not decision confirmation, plan approval, glossary approval, or publication consent.
+
+In autonomous mode, if required review remains unresolved, first abstain from the disputed meaning, then leave affected scope, requirements, tasks, and acceptance explicitly unresolved or deferred, and then emit at most one transient handoff intent. The intent contains exactly \`event: current\`, \`reason\`, and \`ownership_state\`; it is emitted only—not delivered, stored, persisted, or published. It never contains \`caveat_id\`, \`capability\`, or \`transition_id\`, and it is not a complete durable envelope. Use only these authority-defined reason/state pairs: unresolved primary equivalence is \`inferred_equivalence\`/\`review_required\`; an unresolved inferred relation beside applicable exact project authority is \`inferred_equivalence\`/\`project_governs_exact\`; unavailable project authority is \`authority_unavailable\`/\`authority_unavailable\`; and unavailable personal input after a proven project gap is \`personal_input_unavailable\`/\`authority_unavailable\`. Build alone may later submit those three caller-owned fields to \`agentera state progress append\`; its writer creates \`caveat_id\`, \`capability: build\`, and \`transition_id: null\` to complete the authoritative current envelope.
+
+For a divergent exact collision, apply the project meaning and, only when material, represent the bounded tension without exposing the personal definition. Exact project authority with unavailable personal input remains usable: keep the \`personal_input_unavailable\`/\`project_governs_exact\` advisory transient and do not emit a handoff intent. For other unavailable, invalid, or no-applicable advice, abstain from glossary grounding; ask ordinary focused clarification only in interactive mode when the meaning is critical. Autonomous meaning-critical work leaves the affected requirement unresolved rather than guessing and emits an intent only for an authority-declared unresolved pair.
+
+Advice, clarification, tension, and handoff intent are transient and never write glossary, approval, decision-conflict, plan-conflict, or progress caveat state; never call \`agentera state glossary publish\`; and never alter ordinary Plan approval semantics. Durable Plan artifacts and user-visible intent reveal no profile-derived or personal glossary definition, anchor, profile or project path, raw section, unrelated entry, approval, or provenance.
+
+## Workflow phases`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replace("Archive completed plan entities with `agentera state plan archive --format json`.", "Archive completed plan entities with `agentera state plan archive --format json`. With exactly one unfinished canonical predecessor, `agentera state plan create --force --input PATH --format json` archives it unchanged, publishes the successor, and records its bare ID in the writer-owned `previous_plan_archived` field. `agentera state plan archive --force` likewise preserves unfinished task, evaluation, and completion history; multiple implicit open candidates reject before effects. When competing open plans block selection, do not infer roles from list order: use `agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json` only after canonical evidence establishes the complete recovery pair.")
+    .replace("served via `planning_context.profile.path` — read directly when `status: loaded`; if missing or stale, proceed without persona grounding", "served through `agentera report profile-grounding --format json` — use only returned `content` when shared validity is `valid`; if absent or repair_needed, proceed without persona grounding and preserve exact recovery")
+    .replaceAll("planning_context.profile.path", "the shared profile validity summary");

package/dist/capabilities/profile/instructions.js

@@ -0,0 +1,70 @@
+import { personalGlossaryOutputContract } from "../../registries/glossaryEntryContract.js";
+// Capability instructions for profile
+// Served via `agentera prime --context profile --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# PROFILE\n\n**Persona Reconstruction: Observable Footprint Indexing Logic. Extract, Reconcile, Formalize**\n\nGlyph: ♾ (protocol ref: SG9).\n\nMine the user's session history and produce a structured decision profile for predicting \"What would this person decide?\" Each entry carries numeric confidence, permanence classification, and temporal metadata enabling dormancy decay. The profile is consumed by all capabilities via \u0060status.profile\u0060.\n\n---\n\n## State artifacts\n\nProfile reads bounded signal tiers and decisions; writes PROFILE.md. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060profile\u0060 | produces_and_consumes | \u0060profile_context.profile.path\u0060 |\n| \u0060decisions\u0060 | consumes | deferred \u0060capability_context.startup.availability\u0060 row\u0027s \u0060detail_command\u0060 |\n\n**Startup contract**: trust \u0060profile_context\u0060, \u0060capability_context.startup\u0060, and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context profile --format json\u0060. Observe \u0060capability_context.startup.outcome\u0060. Treat \u0060capability_context.startup.availability\u0060 as the inventory: use the bounded context summary for an \u0060included\u0060 family, and run a \u0060deferred\u0060 row\u0027s \u0060detail_command\u0060 before any raw artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Visual-token families (VT/SI/EX/SG/PH) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### Profile format\n\nOutput constraint: ≤30 words per signal, ≤15 words per evidence line.\n\n\u0060\u0060\u0060markdown\n# Decision Profile: [User Name]\n\n<!-- Generated: {date} | Data: {date range from earliest to latest timestamp} | Validated: — -->\n<!-- Sources: {N} memory files, {N} history prompts, {N} conversation exchanges, {N} configs -->\n<!-- Decay parameters: stable λ=0.001, durable λ=0.005, situational λ=0.015 -->\n<!-- Formula: effective_conf = conf × e^(-λ × days_since_confirmed), floor 20 -->\n<!-- Regenerate with /agentera profile -->\n\n## How to Use This Profile\n\nThis profile captures decision-making patterns extracted from {N} months of sessions across {N} projects. Each entry carries inline metadata:\n\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- **conf** (0-100): Evidence-based confidence. 90+ shipped consistently (CS1), 70-89\n  established (CS2), 50-69 emerging (CS3), 30-49 single signal (CS4), 0-29 speculative (CS5).\n  Line weight tokens: ━ (VT9) high (90-100), ─ (VT10) medium (50-89), ┄ (VT11) low (0-49).\n- **perm**: How stable the decision domain is. stable (decade), durable (year),\n  situational (month).\n- **dates**: When the decision was first observed, refreshed,\n  and last challenged.\n- **Generated / Validated**: Full rebuild date vs last validate-mode\n  maintenance date in the header comment. \u0060agentera prime\u0060 treats the\n  profile as fresh through the newer of the two.\n\nWhen consuming this profile, compute effective confidence using the decay formula.\nStale situational entries carry less weight than fresh stable ones.\n\n**When the profile is silent**: If a situation isn't covered, look for the closest trade-off\nheuristic or meta-decision pattern. When truly uncertain, ask.\n\n## Decision-Making Philosophy\n\n[2-3 paragraphs describing the meta-patterns: how this person approaches decisions, what\nframeworks they use, their risk posture, when they decide quickly vs deliberate, what\ninformation they seek before deciding]\n\n## [Category Name]\n\n### [Decision Name]\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- ▸ **Rule**: [Imperative statement an agent can follow directly]\n- ▸ **When**: [Specific conditions or triggers for this rule]\n- ▸ **Why**: [The reasoning, the value or concern that drives this]\n- ▸ **Exceptions**: [Known cases where this was overridden, or \"None observed\"]\n\n[Repeat for each decision in the category. Order by confidence (highest first).]\n\n[Repeat for all 12 categories. Skip categories with no signal.]\n\n## Tensions\n\nEach entry records a contradiction or divergence found during profile generation or challenged during validation. Default status is **unresolved**. Resist the urge to wrap tensions in resolution narratives. Some tensions are real and persistent.\n\n### YYYY-MM-DD: [Short description]\n\n**Decision affected**: [which decision was contradicted]\n**What happened**: [what was observed or said that didn't fit]\n**Status**: unresolved\n\u0060\u0060\u0060\n\n**Writing guidelines**:\n\n- Write rules as imperatives (\"Use X\" not \"[Name] prefers X\")\n- Be specific (\"when building Go CLIs\" not \"when building things\")\n- Always include the *why* because agents need reasoning for edge cases\n- Don't duplicate AGENTS.md. This covers decision *patterns*, not project instructions\n- Omit categories with <2 decisions (insufficient signal)\n- Every entry MUST have inline metadata after the ### heading\n\n---\n\n## Workflow phases\n\nMode-split shape. Two modes: **Full** (regenerate from scratch) and **Validate** (quick incremental check).\n\nCheck if \u0060profile_context.profile.path\u0060 resolves to an existing file. If it does NOT exist, proceed directly to Full mode. If it DOES exist, present the mode choice:\n\n> **Full**: Regenerate from scratch using all session data. Replaces the existing profile including any accumulated tensions. Best when the profile feels significantly outdated or you want a clean baseline.\n>\n> **Validate**: Quick check of your existing profile (~2 minutes). Reviews the entries most worth validating: confirm, challenge, or skip each one. Best for regular maintenance between full regenerations.\n\n### Full Mode\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: extract, read, synthesize, generate.\n\n#### Step 1: Coverage and extraction\n\nRun the active-runtime Coverage Audit as the first user-visible output of every Full-mode run, then publish bounded tiers:\n\n\u0060\u0060\u0060bash\nagentera report refresh --consent local-history\n\u0060\u0060\u0060\n\nThe refresh runs the coverage audit first and exits flagged (EX2) if available runtimes are skipped without \u0060--accept-coverage-gap\u0060. On success it publishes bounded evidence tiers (full-evidence shards + a bounded signal tier with evidence anchors) as the canonical bounded output. The monolithic corpus is no longer written; tiers are the synthesis input.\n\nThe active runtime IDs are exactly \u0060opencode\u0060, \u0060codex\u0060, \u0060cursor\u0060, and \u0060copilot\u0060. Cursor Agent CLI storage is a Cursor source product, never a separate runtime identity. Apply \u0060--no-codex\u0060, \u0060--no-opencode\u0060, \u0060--no-copilot\u0060, or \u0060--no-cursor\u0060 only when the user selects a partial active-runtime corpus; available skipped sources require \u0060--accept-coverage-gap\u0060.\n\nClaude Code is not a supported runtime. Its transcript parser is available only as an explicit historical importer:\n\n\u0060\u0060\u0060bash\nagentera report refresh --consent local-history --import-source claude\n\u0060\u0060\u0060\n\nBefore that opt-in, warn that transcripts can contain secrets, file contents, and command output. The import is local and read-only. Every imported record is labeled \u0060source_class=historical_import\u0060, \u0060source_product=claude-code\u0060, and \u0060active_runtime=false\u0060; default active analytics exclude it. Never describe imported records as Claude support, health, installation, or active-runtime coverage. Use \u0060agentera report --sources all\u0060 only when the user explicitly asks for historical/all-source analysis, and keep provenance visible.\n\nThe extractor writes instruction documents, history prompts, conversation turns, tool calls, and project config signals as bounded signal records. Read \u0060profile_context.profile.bounded_signals\u0060 to confirm the tier state, signal count, and sufficiency assessment without loading full evidence. If an active source fails, proceed with bounded degradation evidence; if historical import fails, report only the importer failure and do not turn it into runtime health.\n#### Step 2: Read bounded signals\n\nRead the bounded signal tier published in Step 1. The \u0060profile_context.profile.bounded_signals\u0060 status provides \u0060tiers_dir\u0060, \u0060signal_path\u0060, \u0060signal_count\u0060, \u0060profile_signal_count\u0060, and the \u0060sufficiency\u0060 assessment. The signal tier carries only the contract-required fields plus \u0060evidence_anchor\u0060 for every record — no transcript text, raw tool arguments, or raw store paths. Group signals by \u0060signal_type\u0060 for synthesis:\n\n1. **instruction**: Memory files, AGENTS.md (highest signal: explicit user instructions)\n2. **decision** and **correction**: Decision-rich and revision signals from session history\n3. **question**: Interrogative signals surfacing uncertainty and information-gathering intent\n4. **configuration**: Recurring config patterns across projects (most objective: what shipped)\n\nEach signal carries \u0060source_kind\u0060, \u0060signal_type\u0060, \u0060timestamp\u0060, \u0060project_id\u0060, \u0060runtime\u0060, \u0060source_product\u0060, and \u0060evidence_anchor\u0060. The \u0060evidence_anchor\u0060 resolves to exactly one retained full-evidence shard — do not re-scan unbounded history to retrieve a full record.\n\n**Sufficiency gate**: Before synthesizing, check \u0060bounded_signals.sufficiency\u0060. If \u0060sufficient\u0060 is false, surface the underrepresented families with their retained and intended counts. Cap confidence for affected categories to the single-signal band (CS4, 30-49) or below — never fabricate high-confidence claims from sparse or missing evidence. Report the limitation in the profile header and emit \u0060♾ profile · flagged\u0060 (EX2).\n\n**Legacy state**: If \u0060bounded_signals.state\u0060 is \u0060legacy\u0060 (tiers not published, monolithic corpus exists) or \u0060missing\u0060, do not load the corpus whole. Run Step 1 refresh to publish bounded tiers first.\n\n#### Step 3: Categorize and synthesize\n\nGroup signals into 12 categories:\n\n1. **Architecture & Design Patterns**: package layout, abstraction boundaries, API design\n2. **Technology & Tooling Selection**: languages, frameworks, libraries, build tools\n3. **Agent & Automation Philosophy**: agent behavior, autonomy, interaction patterns\n4. **Code Quality & Standards**: error handling, testing, validation, naming\n5. **DX & Project Structure**: directory layout, build targets, configuration\n6. **Scoping & Prioritization**: what to build, milestones, complexity budgets\n7. **Communication Style**: writing preferences, documentation voice\n8. **Process & Workflow**: git workflow, commit conventions, release process\n9. **UI/UX Preferences**: visual patterns, interaction design, CLI vs TUI vs web\n10. **Trade-off Heuristics**: simplicity vs flexibility, speed vs correctness\n11. **Anti-patterns & Rejections**: things actively avoided, with reasoning\n12. **Meta-decision Style**: frameworks used, information gathering, decide vs defer\n\nPer category: identify distinct decisions (not just preferences; decisions have conditions and reasoning), look for the *why*, note exceptions where the rule was overridden.\n\n**Assign confidence** (numeric, 0-100, protocol ref: CS1-CS5)\n\nDecision patterns are empirically verifiable via git history and configs:\n\n| Range | Label | Token | Criteria |\n|-------|-------|-------|----------|\n| 90-100 (CS1) | Shipped consistently | ━ (VT9) | Appears in configs/code across 3+ projects, verifiable from artifacts |\n| 70-89 (CS2) | Established | ━ (VT9) | Consistent across sessions, corroborated by behavior |\n| 50-69 (CS3) | Emerging | ─ (VT10) | Observed multiple times but limited context or minor variations |\n| 30-49 (CS4) | Single signal | ┄ (VT11) | One data point or inferred from adjacent patterns |\n| 0-29 (CS5) | Speculative | ┄ (VT11) | No direct evidence, extrapolated from related decisions |\n\n**Bias check**: Confidence is earned through evidence, not assigned by how insightful the decision sounds. A pithy design principle observed once is 30, not 75.\n\n**Assign permanence class**\n\nPermanence captures domain *stability*, independent of confidence. You can be highly confident about something that will change (85, situational) or uncertain about something deep (35, stable).\n\n| Class | Domain | Timescale |\n|-------|--------|-----------|\n| **stable** | Architecture principles, design patterns, meta-decision heuristics | Decade |\n| **durable** | Tooling choices, code standards, process conventions, DX preferences | Year |\n| **situational** | Current project priorities, active initiative choices, recent tech stack picks | Month |\n\nDefault permanence mapping by category:\n\n- Architecture & Design Patterns, Meta-decision Style → stable\n- Technology & Tooling, Code Quality & Standards, Process & Workflow, DX & Project Structure, Communication Style, Trade-off Heuristics, Anti-patterns → durable\n- Scoping & Prioritization, UI/UX Preferences → situational (unless clearly long-standing)\n- Agent & Automation Philosophy → durable (unless project-specific)\n\nOverride the default when the evidence suggests otherwise.\n\n**Set dates**\n\n- **first**: Earliest timestamp from the source data that evidences this decision\n- **refresh date**: Set to today's date (the generation date)\n- **challenged**: Set to \u0060—\u0060 (none yet on a fresh profile)\n\n**Identify tensions**\n\nLook for cross-category patterns and contradictions: stated principle vs shipped code, conflicts between categories, \"Exceptions\" suggesting a weaker rule. Record contradictions in the Tensions section rather than smoothing them into a coherent narrative.\n\n**Evidence anchor resolution**\n\nEvery synthesized claim must carry the \u0060evidence_anchor\u0060 (the \u0060source_id\u0060) of the signal it was derived from. To check a claim's source identity, resolve the anchor to its retained full-evidence shard — the manifest maps \u0060source_id\u0060 to the owning shard, so only that shard is loaded. Never re-scan unbounded history. If an anchor does not resolve (stale tier, corrupt shard), the claim cannot be checked: lower its confidence or omit it.\n\n#### Step 4: Generate the profile and validate\n\nWrite the decision profile to \u0060profile_context.profile.path\u0060 following the Profile format template above.\n\nIf a previous version exists: copy to the \u0060history/\u0060 subdirectory alongside PROFILE.md, generate new version, show change summary (added, updated, removed).\n\n**Prediction validation**\n\nPick 5 decision-rich prompts NOT used to create profile entries. For each: predict what the profile would recommend, check against what happened. Report accuracy (e.g., \"4/5\").\n\nBelow 3/5: identify categories needing more signal, note in profile header, and emit \u0060♾ profile · flagged\u0060 (EX2) — the profile is written but signal quality is insufficient.\n\n---\n\n### Validate Mode\n\nQuick incremental check. Step markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: select, present, apply.\n\n#### Step V1: Select entries\n\nIdentify which entries are most worth checking by reading PROFILE.md directly and prioritizing high-confidence, stale, or tension-heavy entries. If PROFILE.md is missing, fall back to Full mode.\n\n#### Step V2: Present entries for validation\n\nPresent entries one at a time: decision name, rule text, reason surfaced, stored vs effective confidence. Ask: **Confirm**, **Challenge**, or **Skip**.\n\n#### Step V3: Apply updates and write\n\nFor each response:\n\n- **Confirm**: Bump \u0060conf\u0060 by 5 (cap at 95). Update \u0060confirmed\u0060 to today's date.\n- **Challenge**: Soften \u0060conf\u0060 by 10 (floor at 10). Update \u0060challenged\u0060 to today's date.\n  Append a tension entry to the \u0060## Tensions\u0060 section:\n\n  \u0060\u0060\u0060\n  ### {today}: {decision name} challenged during validation\n  **Decision affected**: {decision name}\n  **What happened**: Challenged by user during validation\n  **Status**: unresolved\n  \u0060\u0060\u0060\n\n- **Skip**: No changes to this entry.\n\nUpdate the header comment before writing:\n\n- Set \u0060Validated:\u0060 to today's date.\n- Preserve \u0060Generated:\u0060 unchanged (last full rebuild date).\n- If \u0060Validated:\u0060 already exists, replace its date; otherwise append \u0060| Validated: {today}\u0060.\n\nWrite updated PROFILE.md. Report: \"Reviewed {N} entries: {N} accepted, {N} challenged, {N} skipped.\" Mention challenged entries by name.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT fabricate decision patterns. Every profile entry MUST be grounded in observed evidence from bounded signal tiers, memory files, configs, or conversation data.\n- MUST NOT assign confidence higher than the evidence warrants. A single data point is 30-49 (CS4), not 70+, regardless of how insightful the decision sounds. When bounded_signals.sufficiency is insufficient, cap affected categories to CS4 or below.\n- MUST NOT load the monolithic corpus.json whole. Profile synthesis reads the bounded signal tier; full-evidence records are retrieved one shard at a time via evidence_anchor.\n- MUST NOT smooth over contradictions. When evidence conflicts, record tensions rather than forcing a coherent narrative.\n- MUST NOT modify the user's session history, memory files, or config files. Profile reads these sources; it never writes to them.\n- MUST NOT share profile contents with external services or include them in commits.\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♾ profile · <status>\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a ▸ (VT15) bullet below the summary identifying what needs attention. The exit marker uses profile's canonical glyph ♾ (SG9, U+267E).\n\n- **complete** (EX1): PROFILE.md was written (Full mode) or updated (Validate mode). Metadata changes were applied, prediction accuracy was assessed (Full mode), and changes were summarized.\n- **flagged** (EX2): Profile generation or validation completed but with data quality issues: available runtime history was skipped without explicit acceptance, extraction failed for one or more sources, prediction accuracy was below 3/5, or significant tensions were found that could not be resolved from available evidence.\n- **stuck** (EX3): Cannot generate or validate a profile because extraction scripts failed entirely or session data sources are unreadable.\n- **waiting** (EX4): The user chose Validate mode but PROFILE.md lacks valid metadata. A Full mode run needs user approval, or the requested mode is ambiguous.\n\n---\n\n## Cross-capability integration\n\n### Consumption contract\n\nAll capabilities consume the profile via \u0060status.profile\u0060 from their prime context. Confidence thresholds: 65+ for strong constraint, below 45 for suggestion. Effective confidence decays over time using the formula and parameters declared in the Profile format template (§2). High effective confidence entries are treated as strong constraints; low as suggestions. Full rules are read from PROFILE.md when needed for detailed reasoning.\n\n### Consumed by\n\n- **build** — confidence-weighted summary table in Orient step; high confidence as strong constraints\n- **optimize** — calibrates experimentation style and trade-off preferences\n- **research** — informs applicability judgments; high confidence constrains recommendations\n- **discuss** — reads profile at start of every deliberation; high-confidence entries acknowledged upfront\n- **audit** — calibrates quality bar and which findings matter for this user\n- **plan** — calibrates planning depth and constraint priorities in Orient step\n\n### Fed by\n\n- **discuss** — \u0060decisions\u0060 artifact is a high-signal extraction source. Prefer \u0060agentera state decisions list --limit 20 --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure rather than raw-reading missing historical context.\n\n### Getting started\n\nFirst profile generation:\n\n\u0060\u0060\u0060\n/agentera profile\n\u0060\u0060\u0060\n\nFull extraction across all sources. Produces PROFILE.md at \u0060profile_context.profile.path\u0060.\n\nRegular validation:\n\n\u0060\u0060\u0060\n/agentera profile validate\n\u0060\u0060\u0060\n\nQuick confidence refresh without full regeneration. Run weekly or per-session.\n\nUsing the profile in other capabilities: automatic — all capabilities read \u0060status.profile\u0060 from their prime context. No manual steps needed; just ensure PROFILE.md exists."`);
+const profileGlossaryOutput = personalGlossaryOutputContract();
+const personalGlossaryInstructions = `#### Step 4: Generate the profile and validate
+
+Generate the complete non-glossary decision profile in memory as byte string \`B\`, following the Profile format template above. The generated base MUST NOT contain either personal-glossary marker or a line whose complete heading is \`## Glossary\`.
+
+Use this ordered publication sequence. Do not reorder or combine its writes:
+
+<!-- agentera:profile-full-action:capture-owned-glossary -->
+1. **Capture and validate the existing owned Glossary section.** Before copying history or writing any generated bytes, read the existing \`profile_context.profile.path\` only if it exists. Count the literal start marker, literal end marker, and line-anchored \`## Glossary\` heading. If all counts are zero, set the captured section \`G\` to absent. Otherwise require exactly one of each, the start before the end, the heading inside that range, and the complete range to match the deterministic representation below. Its JSON must parse to a mapping with exactly \`schema_version\`, \`as_of\`, \`confidence_basis\`, and \`entries\`; require schema \`${profileGlossaryOutput.sectionSchemaVersion}\`, a valid calendar date, one integer confidence basis per unique case-insensitive term, and shared-primitive-valid entries. Reject unmatched markers, duplicate sections or terms, an unowned heading, malformed JSON or fields, or any other ambiguous boundary before a history copy or base write. Capture \`G\` as the exact bytes from the first byte of the start marker through the final byte of the end marker, inclusive.
+<!-- agentera:profile-full-action:write-base-profile -->
+2. **Write the base profile before glossary publication.** If a previous profile exists and validation succeeded, first copy its original bytes to the \`history/\` subdirectory alongside PROFILE.md. If \`G\` is absent, write \`B\` exactly to \`profile_context.profile.path\`. If \`G\` is present, write exactly \`B + (B ends with "\\n" ? "\\n" : "\\n\\n") + G + "\\n"\`. This replaces all generated non-glossary content while carrying the validated owned range byte-for-byte; do not parse, re-render, trim, or normalize \`G\`. The base profile now exists even on first generation.
+<!-- agentera:profile-full-action:publish-profile-glossary -->
+3. **Publish the glossary lifecycle result.** Only after the base profile exists, invoke \`${profileGlossaryOutput.command} --input - --format json\` with the structured request below. This post-write call retains, refreshes, or decays the preserved section and adds it on first generation.
+
+Show the non-glossary change summary (added, updated, removed) after publication.
+
+### Personal Glossary section
+
+Profile Full actively synthesizes and persists personal glossary entries. It never reads a project glossary: do not accept, resolve, import, or inspect a project root, \`.agentera/glossary.yaml\`, project glossary artifact identity, or project-file provenance. Profile itself performs no consumer lookup, project precedence, or semantic-equivalence review; Discuss, Plan, and Build obtain that active behavior separately through \`agentera report glossary-advice\`.
+
+Each entry is exactly the shared primitive from \`references/artifacts/glossary-entry-contract.yaml\`: \`term\`, \`meaning\`, \`confidence\`, \`permanence\`, \`temporal\`, and personal \`provenance\`. Do not restate or replace that authority's confidence, permanence, or provenance rules. Decision-pattern confidence and glossary-entry confidence are separate domains; glossary work MUST NOT alter decision headings, metadata, or confidence.
+
+Write exactly one independently owned section in this deterministic representation, sorted by case-insensitive term identity:
+
+~~~markdown
+<!-- agentera:personal-glossary:start -->
+## Glossary
+
+\`\`\`json
+{
+  "schema_version": "agentera.personalGlossarySection.v1",
+  "as_of": "YYYY-MM-DD",
+  "confidence_basis": { "case-insensitive term identity": 75 },
+  "entries": [
+    {
+      "term": "...",
+      "meaning": "...",
+      "confidence": 75,
+      "permanence": "durable",
+      "temporal": { "observed_at": "YYYY-MM-DD", "last_confirmed_at": "YYYY-MM-DD" },
+      "provenance": { "kind": "personal_explicit_definition", "evidence": [] }
+    }
+  ]
+}
+\`\`\`
+<!-- agentera:personal-glossary:end -->
+~~~
+
+The section-level \`confidence_basis\` records confidence at establishment or the latest qualifying refresh so decay is derived from that basis rather than repeatedly compounded from rendered confidence. It is lifecycle metadata, not an entry field. Send one \`${profileGlossaryOutput.requestSchemaVersion}\` YAML or JSON mapping on stdin with exactly \`schema_version\`, \`profile_path\`, \`as_of\`, \`fresh_entries\`, and \`retained_history\`. Set \`profile_path\` to the exact \`profile_context.profile.path\` returned by startup; do not discover it. Each retained-history row carries \`source_id\`, \`evidence_anchor\`, \`source_kind\`, and \`signal_type\`; the list may be empty when regeneration has no fresh entries. Use \`--dry-run\` for a no-write candidate preview after the ordered base write, never as a substitute for preserving \`G\`.
+
+The callable adds the section when absent and otherwise replaces only the exact owned marker range, preserving every other byte. Unmatched markers, duplicate owned sections, or an unowned \`## Glossary\` heading fail before effects. New explicit entries retain exactly one admitted anchor; inferred entries retain exactly two pairwise-distinct anchors.
+
+Merge terms case-insensitively. Preserve established spelling and \`observed_at\`. Matching fresh evidence refreshes confidence, confidence basis, evidence anchors, and \`last_confirmed_at\` only when meaning and provenance kind are unchanged; preserve permanence. Divergent meaning or provenance kind is a conflict, not an overwrite. Without fresh evidence, retain the entry and permanence, and derive integer confidence from the basis using the existing Profile exponential formula, the entry's unchanged permanence-class lambda, elapsed UTC calendar days from \`last_confirmed_at\`, the existing floor, and nearest-integer rounding. Age alone never deletes an entry. Identical input on the same date must produce identical bytes.
+`;
+export const servedInstructions = instructions.replace("#### Step 4: Generate the profile and validate\n\nWrite the decision profile to `profile_context.profile.path` following the Profile format template above.\n\nIf a previous version exists: copy to the `history/` subdirectory alongside PROFILE.md, generate new version, show change summary (added, updated, removed).", personalGlossaryInstructions);
+export function loadProfileDecayParameters() {
+    const lambdas = /Decay parameters: stable λ=([0-9.]+), durable λ=([0-9.]+), situational λ=([0-9.]+)/.exec(instructions);
+    const floor = /Formula: effective_conf = conf × e\^\(-λ × days_since_confirmed\), floor (\d+)/.exec(instructions);
+    if (!lambdas || !floor)
+        throw new Error("Profile decay authority is malformed");
+    return {
+        lambdas: { stable: Number(lambdas[1]), durable: Number(lambdas[2]), situational: Number(lambdas[3]) },
+        floor: Number(floor[1]),
+    };
+}
+export default servedInstructions;

package/dist/capabilities/research/instructions.js

@@ -0,0 +1,5 @@
+// Capability instructions for research (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context research --format json`. RFC 2119 modal vocab per D71.
+// Rewritten per Decision 83 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
+export const instructions = JSON.parse(String.raw `"# RESEARCH\n\n**Insight Navigation: Source Pattern Identification and Resonance. Evaluate, Reframe, Assimilate**\n\nGlyph: **\u2b1a** (protocol ref: SG10). Analyze an external resource and map its ideas to a target project. Output a structured markdown analysis the user can navigate and act on.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available \u2014 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\nNo dedicated state file. Reads the user's decision profile; writes to other capabilities' artifacts with confirmation.\n\n| Artifact | Role | Source |\n|---|---|---|\n| profile | consumes | \u0060research_context.profile\u0060 (via \u0060agentera prime --context research --format json\u0060) |\n| todo | produces | \u0060research_context.write_boundaries\u0060 |\n| vision | produces | \u0060research_context.write_boundaries\u0060 |\n\n**Startup contract**: trust \u0060research_context\u0060, \u0060capability_context.startup\u0060, and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context research --format json\u0060. Observe \u0060capability_context.startup.outcome\u0060. Treat \u0060capability_context.startup.availability\u0060 as the inventory: use the bounded context summary for an \u0060included\u0060 family, and run a \u0060deferred\u0060 row\u0027s \u0060detail_command\u0060 before any raw 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) by \u0060skills/agentera/protocol.yaml\u0060.\n\n---\n\n## Workflow phases\n\nLinear shape: five steps with a named checkpoint between source reading and target exploration.\n\nAt each step, display \u0060\u2500\u2500 step N: verb\u0060 before starting that step's work.\n\n### Step 1: Identify source, target, and motivation\n\nFrom the user's message, extract:\n\n- **Source**: the external resource \u2014 could be a URL (GitHub repo, article, docs, HN thread), a local file path, a concept name (\"research the actor model\"), or a verbal approach description\n- **Target**: the user's project, which could be any of:\n  - A **GitHub repo URL** \u2192 explore via available remote-access tools\n  - A **local path** or project name \u2192 explore via filesystem tools\n  - The **current working directory** \u2192 if the user says \"my project\" / \"what I'm building\" without a URL, and they're clearly working in a project, treat cwd as the target\n  - **Absent** \u2192 if truly no target is implied, skip Steps 3\u20134 and do source-only analysis\n- **Motivation**: what the user is trying to learn or decide. Common flavors:\n  - **Adoption evaluation** \u2014 \"should I use this?\"\n  - **Idea extraction** \u2014 \"what can I learn from this?\"\n  - **Comparison** \u2014 \"how does this compare to what I'm doing?\"\n  - **Curiosity** \u2014 \"what's interesting about this?\"\n\nThe motivation shapes the analysis framing throughout.\n\n---\n\n### Step 2: Read the source\n\nRead deeply, form opinions as you go. Not a data-collection pass.\n\n#### GitHub repos\n\nUse available remote-access tools to explore the repository deeply:\n\n1. List root directory structure\n2. Read README\n3. Read key source directories until you understand: core abstractions, design patterns, notable primitives, dependencies, clever approaches worth borrowing\n\nGo deep and don't stop at the README. If available tools cannot access the repository, fall back to public pages or note the limitation.\n\n#### Articles, blog posts, docs pages\n\nFetch full content. Extract core thesis, named concepts/patterns, code samples, and referenced tools. If paywalled, try reader-mode variant; if that fails, note the limitation.\n\n#### Hacker News threads\n\nRead both the linked article and top comments. HN comments often contain the most useful distillation. Treat as signal.\n\n#### Known libraries\n\nFor well-known libraries, also check documentation databases for up-to-date docs beyond the README.\n\n#### Concept names or verbal descriptions\n\nWhen no URL is provided, draw on training data, docs, and web search to reconstruct the concept. State the sources you used.\n\n---\n\n### Transferable concepts checkpoint\n\nBefore proceeding to target analysis, surface 3\u20135 most transferable concepts from the source. These survive if the source file reads are cleared.\n\nThis is a checkpoint: the user can redirect here before you spend time mapping concepts to a project they don't need. If no target was identified in Step 1, skip to Step 5 and deliver source-only analysis using these concepts.\n\n---\n\n### Step 3: Read the target project\n\nChoose the exploration strategy based on the target type identified in Step 1.\n\n#### Local projects (current directory or local path)\n\nCommon case. Use filesystem tools (faster, includes uncommitted work):\n\n1. Map the directory structure by listing files matching relevant extensions (e.g. \u0060**/*.{ts,go,py,rs}\u0060)\n2. Read README.md if one exists\n3. Check dependency manifests (\u0060package.json\u0060, \u0060go.mod\u0060, \u0060Cargo.toml\u0060, \u0060pyproject.toml\u0060, etc.)\n4. Search for patterns, imports, or abstractions relevant to the source's concepts\n5. Read key source files to understand architecture and current patterns\n\n#### Remote GitHub repos\n\nUse available remote-access tools:\n\n1. List the root directory structure\n2. Read the README\n3. Read dependency manifests and key source files\n\n#### Build understanding of\n\nLanguage, stack, dependencies, architecture, patterns, and problems being solved.\n\n#### Check for existing usage\n\nDoes the target already use the source (or a fork/alternative)?\n\n- **Already using**: \"Getting the most out of it?\" Focus on underused features and better patterns.\n- **Using alternative**: \"Worth switching?\" Compare approaches and migration cost.\n- **Not using**: \"Should you adopt?\" This is the default framing.\n\n---\n\n### Step 4: Map concepts to the target\n\nWith both source and target understood, reason about adaptation \u2014 not replacement. How do these ideas *augment* the target's existing conventions and processes?\n\nFor each transferable concept:\n\n- What is the source doing that the target should adapt?\n- Abstractions that simplify current complexity?\n- Patterns the target implements manually or poorly?\n- Primitives worth borrowing or adapting?\n- Source doing something the target does, but better?\n- Fundamentally incompatible? Say so clearly.\n- Adoption cost: one-file change or multi-sprint evolution?\n\nFraming: research is about getting inspired and adapting ideas into what already exists, without replacing existing conventions or processes \u2014 only augmenting them.\n\n---\n\n### Step 5: Deliver the analysis\n\nOpen with your take before the structured sections: what excited you, what surprised you, what the user should care about most. The structured analysis follows, but the human read comes first.\n\nWrite a **structured markdown analysis**. If no target was given, skip the Applicability Matrix and deliver source-only transferable concepts (see \"No target given\" below).\n\n#### Output format\n\n\u0060\u0060\u0060\u0060markdown\n# [Source Name] \u2192 [Target Name]: Cross-Pollination Analysis\n\n## TL;DR\nOne or two sentences. Is this worth pursuing? What's the strongest single takeaway?\n\n## Source Overview\nBrief summary of what the source does and its core design philosophy.\n\n## Key Concepts\n\n### [Concept Name]\nWhat it is, why it's interesting, and where/how it concretely adapts to the target.\n\n### [Concept Name]\nSection repeats for each significant concept (typically 2\u20135).\n\nReasoning about adaptation SHOULD live in the response text, not the matrix.\nThe Applicability Matrix MUST contain only conclusions, not reasoning chains.\nEach matrix cell MUST be \u226415 words.\n\n## Applicability Matrix\n\n| Concept | How it adapts to [Target] | Effort | Partially present? |\n|---------|---------------------------|--------|---------------------|\n| ...     | specific adaptation approach    | Low/Med/High | Yes/No + what exists |\n\n## What Doesn't Apply\nHonest assessment of concepts/patterns that look interesting but don't fit, and why.\nBeing clear about what *not* to adopt is as valuable as the recommendations.\n\n## Recommended Next Steps\n\u25b8 [action] \u00b7 [specific file or module]\n\u25b8 [action] \u00b7 [specific file or module]\nSteps SHOULD be ordered by value/effort ratio.\n\u0060\u0060\u0060\u0060\n\n**Tone**: direct, technically fluent. Skip empty sections. Lead with highest signal.\n\nRead more files, not fewer. Shallow reads produce shallow analysis. Large repos: focus on modules most relevant to the concept, not everything. Explore source and target concurrently where possible. Always use available remote-access tools for GitHub URLs.\n\nOffer to go deeper: prototype an adaptation, explore a concept with code, compare alternatives.\n\n#### No target given\n\nSurface transferable concepts in general terms. Skip Applicability Matrix. Ask if the user wants to map to a specific project.\n\n---\n\n## Safety rails\n\n<critical>\n- Research MUST NOT modify code in the target project. It analyzes and maps concepts; other capabilities (build, optimize) implement changes. The only writes are to TODO.md and VISION.md, and only with explicit user confirmation.\n- Research MUST NOT write to TODO.md or VISION.md without explicit user confirmation. Present findings and get approval before filing.\n- Research MUST NOT present shallow analysis as deep insight. If the source was not read thoroughly, say so.\n- Research MUST NOT recommend adoption without assessing fit. Every recommendation must consider the target project's constraints, stack, and principles.\n- Research MUST NOT fabricate source content. Quote actual code and text from the source.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion.\n\nFormat: emit \u0060\u2b1a research \u00b7 <status>\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060, \u0060stuck\u0060, and \u0060waiting\u0060, add a \u25b8 bullet below the summary identifying what needs attention.\n\n- **complete**: Source was read deeply, target project was explored (if provided), concept mapping was completed, and a structured analysis with applicability matrix and recommended next steps was delivered.\n- **flagged**: Analysis completed but with limitations worth surfacing: the source was paywalled or truncated, the target project was inaccessible, or key concepts could not be fully assessed for fit.\n- **stuck**: Cannot proceed because the source URL is inaccessible and no fallback content is available, or the target project specified does not exist and cannot be located.\n- **waiting**: The source link was not provided or is malformed, or the target project is genuinely ambiguous and neither the current directory nor context resolves it.\n\n---\n\n## Cross-capability integration\n\nResearch is part of a twelve-capability suite. Its analysis feeds naturally into the other capabilities.\n\n### Feeding into build\n\nAdd actionable findings to the project's TODO.md, classifying each by severity per protocol SF1-SF3. Or refine vision's direction if the inspiration shifts thinking. The next build cycle picks up the changes automatically.\n\n### Feeding into optimize\n\nWhen the source contains optimization techniques (performance patterns, algorithm improvements, caching strategies), optimize can draw on the analysis for its next experiment.\n\n### Informed by profile\n\nThe user's decision profile, when available via \u0060research_context.profile\u0060, grounds applicability judgments in the user's patterns. Use effective confidence to weight judgments.\n\n### Feeding into vision\n\nWhen the analysis shifts thinking about the project's direction (a new paradigm, a competitor's approach, or a user need not yet captured), the findings can inform vision refinement. Suggest \u26e5 vision to revisit the project direction with the new context.\n\n### Feeding into plan\n\nWhen the analysis recommends adapting patterns or libraries, plan can incorporate those recommendations into a plan's design section and task decomposition.\n\n### Feeding into discuss\n\nWhen the analysis surfaces recommendations that require deliberation (competing approaches, unclear adoption cost, or tradeoffs the user needs to resolve), suggest \u2748 discuss to think it through before acting. Discuss can evaluate which recommendations are actually worth adopting and capture the reasoning in decisions.\n\n### Getting started\n\nAnalyze a GitHub repo:\n\n\u0060\u0060\u0060\n/agentera research https://github.com/org/repo\n\u0060\u0060\u0060\n\nReads the repo, maps its patterns to your current project.\n\nAnalyze an article or docs page:\n\n\u0060\u0060\u0060\n/agentera research https://example.com/blog/interesting-approach\n\u0060\u0060\u0060\n\nExtracts transferable concepts and assesses applicability.\n\nAfter analysis, file actionable findings to TODO.md for \u29c9 build to pick up, or refine vision if the research shifts your project's direction.\n"`);
+export default instructions;

package/dist/capabilities/status/instructions.js

@@ -0,0 +1,15 @@
+// Capability instructions for status (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context status --format json`. RFC 2119 modal vocab per D71.
+export const instructions = JSON.parse(String.raw `"# STATUS\n\n**Holistic Entry Junction. Orient, Route, Activate**\n\nSingle entry point to the agentera suite. Detects fresh vs returning, delivers a situational briefing, routes to the right capability. Same path on first install and the 100th session.\n\nGlyph: **⌂** (SG1). Status reads suite state through \u0060agentera prime\u0060 and writes nothing. A bare user message of exactly \u0060/agentera\u0060 invokes this capability; it does not fall back to conversational smalltalk.\n\nStatus MUST source both instructions and bounded state from \u0060agentera prime --context status --format json\u0060 and write nothing. Read \u0060capability_context.instructions\u0060 in full, render from \u0060capability_context.context.status_context\u0060, and use the one \u0060capability_context.startup\u0060 aggregation. Its outcome is \u0060ok\u0060, \u0060degraded\u0060, or \u0060blocked\u0060; \u0060status_context.outcome\u0060 is the same value. For deferred detail, run only that availability row\u0027s exact \u0060detail_command\u0060. An \u0060ok\u0060 startup needs no second prime call. Status MUST NOT raw-read \u0060.agentera/*.yaml\u0060.\n\n---\n\n## Dashboard rendering\n\nStatus owns the prime dashboard contract. SKILL.md and other surfaces delegate here.\n\n\u0060\u0060\u0060text\n┌─┐┌─┐┌─┐┌┐┌┌─┐┌─┐┬─┐┌─┐\n├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤\n┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴\n\n─── status ─────────────────────────────\n\n  ⛶ health    [⮉|⮋] [grade] ([worst dimension: grade])\n  ⇶ todo      N critical · M degraded · J annoying\n  ≡ plan      [██████▓░░░] N/M tasks\n  ⎘ optim     [metric] [current] → [target]\n  ♾ profile   [loaded | not found]\n\n  [1-2 sentence narrative read: what shipped, what's moving, what needs eyes.\n  Interpretation, not metrics. Closes the status section before attention.]\n\n─── attention ──────────────────────────\n\n  ⇶ [critical items, triple arrow for critical]\n  ⇉ [degraded items, double arrow for degraded]\n  → [normal items, single arrow for normal]\n  ⇢ [annoying items, dashed arrow for annoying]\n\n─── next ───────────────────────────────\n\n  suggested → [glyph] [capability] ([reason])\n\u0060\u0060\u0060\n\nBuild the dashboard from \u0060agentera prime --format json\u0060 output. Source labels such as \u0060mode:\u0060, \u0060profile:\u0060, \u0060v1_migration:\u0060, \u0060health:\u0060, \u0060todo:\u0060, \u0060plan:\u0060, \u0060objective:\u0060, \u0060attention:\u0060, \u0060next_action:\u0060, and the \u0060app.status\u0060 installed-app status object are parsing aids, not dashboard lines. Do not relay raw CLI lines as the user-facing briefing.\n\n**Output constraint**: ≤120 words total briefing, ≤15 words per routing suggestion.\n\n**Exit marker**: after the closing code fence of the dashboard, emit \u0060⌂ status · <status>\u0060 on its own line, followed by a one-sentence summary of what you delivered. For \u0060waiting\u0060, \u0060flagged\u0060, or \u0060stuck\u0060, add a \u0060▸\u0060 bullet below the summary identifying what the user needs to decide or act on next. The exit marker MUST appear on every invocation regardless of mode (fresh welcome or returning briefing).\n\n**Formatting rules**:\n- Each status line uses the skill glyph that owns that data\n- Severity arrows (VT5-VT8) mark attention items by urgency\n- Trend arrows (VT12/VT13) show health trajectory; derive ⮉/⮋ from \u0060health.degrading\u0060 (false→⮉, true→⮋); omit when no audit history\n- Progress bars (VT18) show plan completion visually\n- The inline separator (VT16) joins counts on a single line\n- Lead with status metrics, then the narrative read inside the status section\n- The narrative read is colleague interpretation; metric lines above it are evidence\n- The todo summary line lists critical, degraded, and annoying counts only; normal-priority items belong in attention with → (SI3), not on the summary line\n- Omit any line whose source artifact is missing\n- Omit any section that would be empty (e.g., no attention items = no attention section)\n\nVisual token IDs live in \u0060skills/agentera/protocol.yaml\u0060; see VT, SI, EX, SG, PH families.\n\n---\n\n## Briefing\n\nUse the \u0060mode\u0060 field from \u0060agentera prime\u0060 to detect fresh vs returning:\n\n- **Fresh** (\u0060mode: fresh\u0060): render welcome language; lead with the suggested capability from \u0060next_action\u0060. Do not enumerate the full suite unless asked.\n- **Returning** (\u0060mode: returning\u0060): render the dashboard template above using \u0060mode\u0060, \u0060profile\u0060, \u0060health\u0060, \u0060todo\u0060, \u0060plan\u0060, \u0060objective\u0060, \u0060attention\u0060, and \u0060next_action\u0060 fields.\n\nNarration voice: warm, brief, unscripted.\n\n### Project integration rendering\n\nWhen \u0060project_integration.recommendation\u0060 is \u0060upgrade\u0060:\n1. Render the plain-language \u0060project_integration.message\u0060.\n2. Show \u0060project_integration.dry_run_command\u0060 preview; state that it changes nothing.\n3. Ask before running \u0060project_integration.apply_command\u0060.\n\nWhen \u0060recommendation\u0060 is \u0060stay\u0060, do not suggest upgrade.\n\n### App status rendering\n\nRender \u0060app.status\u0060 as a status line only when it is not \u0060up_to_date\u0060. Use the plain-language \u0060project_integration.message\u0060 if present. Status MUST NOT teach install-recovery procedure — that belongs to the upgrade capability and \u0060agentera doctor\u0060.\n\n### Profile rendering\n\nRender \u0060profile.status\u0060 (\u0060loaded\u0060 or \u0060not found\u0060). Render \u0060profile.suggested_action\u0060 or a missing-profile attention item only when prime supplies one.\n\n### Attention items\n\nPriority order with severity arrows (SI1-SI4):\n\n- ⇶ (SI1) Critical issues, degrading health dimensions\n- ⇉ (SI2) Blocked/overdue plan tasks, stale artifacts, overdue health audits (prime \u0060health.stale=true\u0060), loop stop-condition triggers\n- → (SI3) Standard work: features, improvements, routine tasks\n- ⇢ (SI4) Unresolved exploratory decisions\n\nA clean bill of health is useful — say so when nothing is flagged.\n\n---\n\n## Routing suggestion\n\nThe routing suggestion MUST name the artifact item it would act on. A skill name without a concrete object is not a valid suggestion.\n\nValid objects: \u0060PLAN Task N: <title>\u0060, \u0060TODO: <item>\u0060, \u0060DECISION N follow-up\u0060, \u0060OBJECTIVE: <metric>\u0060, or \u0060VISION refresh\u0060.\n\n**Priority order** (SG codes are internal protocol references; never render them in user-facing handoff labels):\n\n- Active PLAN with pending tasks → suggest ⎈ orchestrate for the first unblocked pending task.\n- Critical or degrading health → suggest ⛶ audit or ⧉ build for the named finding.\n- Stale health audit (CLI \u0060health.stale=true\u0060) with no higher-priority work → suggest ⛶ audit for \u0060HEALTH: Audit N stale\u0060.\n- Active non-closed OBJECTIVE with stalled or missing metric evidence → suggest ⎘ optimize for that metric.\n- todo open items → select the highest-severity open item, then route by shape: narrow one-cycle todo items suggest ⧉ build; contract-shaped, multi-surface, dependency-heavy, migration, schema, metadata, validation, or acceptance-risky todo items suggest ≡ plan first. Prefer items that unlock product evidence or future plans.\n- Pending decisions follow-up → suggest ❈ discuss for the named unresolved decision.\n- Vision exists but no plan, objective, decision follow-up, or TODO work is active → suggest ≡ plan.\n- No vision, no executable follow-ups, and no active plan → suggest ⛥ vision to choose a direction.\n\nDo not let \u0060healthy + plan complete → ⛥\u0060 override active TODO, OBJECTIVE, DECISIONS, or a newer active PLAN. A completed plan means \"look for the next executable follow-up,\" not automatically \"refresh vision.\"\n\n### Routing posture\n\n- Present one concrete suggestion and let the user choose. Coercion MUST NOT occur.\n- Do not list generic skill options unless the user asks for the full menu.\n- The waiting bullet should ask whether to run the named action, not ask the user to pick from skills.\n- On the initial status brief, use a free-form continuation prompt rather than a native question menu unless the user asked for bounded choices or the suggested next step is a state-changing Proceed/Cancel handoff.\n- Mid-conversation, use the native question tool only for at least two meaningful non-terminal next actions or a consequential Proceed/Cancel decision; \u0060Done\u0060 and free-form/custom answer affordances do not count as alternatives.\n- State-changing handoffs are consequential Proceed/Cancel decisions even when there is only one suggested action. State-changing means the proposed next step may write artifacts, edit code, run optimization or orchestration cycles, apply migrations, refresh app/runtime state, or otherwise mutate project/runtime state.\n- Use the behavior rule first, with common examples such as ⧉ build, ≡ plan when creating or updating plans, ▤ document when writing docs, ⎘ optimize when running or applying optimization cycles, and ⎈ orchestrate when dispatching cycles.\n- For one non-mutating suggested action, clear free-form acceptance such as \u0060yes\u0060, \u0060start\u0060, \u0060do it\u0060, or \u0060run <capability>\u0060 confirms that suggestion. Ambiguous replies get one clarifying question.\n\nUnclear mapping? Ask **one** clarifying question. Compound questions MUST NOT occur.\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER execute implementation work. Status orients and routes; it MUST NOT build, audit, plan, or decide.\n- NEVER dump full artifact contents verbatim. Summarize concisely; the user can read the files themselves.\n- NEVER skip the briefing in returning mode. The user needs context before choosing a direction.\n- NEVER assume what the user wants without asking. Present the suggestion, then wait for confirmation.\n- NEVER modify any state artifact. Status is strictly read-only.\n- NEVER route to a capability without the user's consent. Suggest, don't force.\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⌂ status · <status>\u0060 on its own line below the dashboard's closing code fence, followed by a one-sentence summary of what was delivered. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what the user needs to decide or act on next. The exit marker MUST appear on every invocation regardless of mode and uses status's canonical glyph \u0060⌂\u0060 (SG1, U+2302).\n\n- **complete** (EX1): Briefing delivered (or welcome shown in fresh mode) and user successfully routed to a capability.\n- **flagged** (EX2): Briefing delivered but critical attention items were found: critical issues, degrading health, loop stop-condition triggers. Each concern MUST be listed explicitly.\n- **stuck** (EX3): Cannot orient: the working directory is not a code project, no readable files exist, or permissions prevent scanning.\n- **waiting** (EX4): Briefing or welcome delivered, suggestion made, awaiting user input on which direction to take.\n\n---\n\n## Cross-capability integration\n\nStatus is the suite entry point. It reads other capabilities' artifacts, produces no artifact, and outputs only a briefing plus routing suggestion.\n"`);
+export default `${instructions
+    .replaceAll("loaded | not found", "valid | absent | repair_needed")
+    .replaceAll("loaded or not found", "valid, absent, or repair_needed")
+    .replace("Render `profile.status` (`loaded` or `not found`). Render `profile.suggested_action` or a missing-profile attention item only when prime supplies one.", "Render the exact shared `profile.validity` status (`valid`, `absent`, or `repair_needed`). Treat `profile.freshness` separately; show stale guidance only for valid stale input, preserve exact recovery for absent or repair-needed input, and never suggest refresh for repair-needed input.")}
+
+### Profile validity
+
+Render the shared profile validity exactly as \`valid\`, \`absent\`, or \`repair_needed\`. Freshness is separate and may be \`current\`, \`stale\`, or \`unknown\`; only valid stale input may carry stale guidance. Repair-needed input preserves its repair recovery and MUST NOT receive refresh advice. Never render profile path or content.
+
+### Plan selection
+
+Render \`status_context.plan.id\` as the canonical selected plan identity. If competing open plans block startup, preserve the failure and its recovery verbatim. Do not infer predecessor or successor roles from a title or list order; only run \`agentera state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json\` after canonical evidence establishes both roles.`;