agentera 3.0.0-dev.8 → 3.0.0-dev.80

package/dist/capabilities/plan/instructions.js

@@ -1,6 +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: Adaptive Notation, Executable Requirements Architecture. Enumerate, Refine, Assign**\n\nScale-adaptive planning bridging deliberation and execution. PLAN.md with behavioral acceptance criteria for build. Plan owns WHAT and WHY; build owns HOW.\n\nVoice: the sharp colleague, here to plan the work. Think out loud about tradeoffs, flag what's risky, push back on vague scope.\n\nThree levels: **skip** (trivial), **light** (single-cycle), **full** (multi-cycle with adversarial review).\n\nSkill introduction: \u0060─── ≡ plan · planning ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **≡** (protocol ref: SG5). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne file and one archive directory in \u0060.agentera/\u0060.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060PLAN.md\u0060 | Canonical plan artifact, stored as \u0060.agentera/plan.yaml\u0060 unless mapped otherwise. Spec, tasks, acceptance criteria. | Created during planning session. |\n| \u0060.agentera/archive/\u0060 | Completed or discarded plans. | Created on first archival. |\n\n**Presence signal**: \u0060.agentera/plan.yaml\u0060 means active planned work. Absence means no plan, so build reasons from VISION.md.\n\nFor read-only current-plan startup or evaluation context, use \u0060agentera plan\n--format json\u0060 first. When its \u0060source_contract.complete_for_plan_artifact\u0060 is\ntrue, its \u0060summary\u0060, \u0060entries\u0060, and \u0060source_contract\u0060 are complete for plan\nmetadata, task dependencies, acceptance criteria, task evidence, overall\nacceptance, surprises, and previous-plan archive references; do not reread the\npersisted plan artifact defensively. Raw mapped plan artifact access is still\nrequired for writing a new plan, archiving a completed plan, artifact validation,\ncorruption diagnostics, or when CLI output is unavailable or incomplete after\nCLI fallbacks.\n\nWhen a user directly invokes ≡ plan to create a new plan and the existing\nPLAN.md is already complete, archiving that completed plan before writing its\nreplacement is implicit in the direct Plan invocation and does not require a\nseparate pre-write confirmation. Human-initiated replacement plans still require\nplan approval before the write. Replacing, discarding, or archiving an active or\nincomplete plan is not implicit; ask for explicit confirmation before the write.\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060plan\u0060 to locate the active installed schema; use \u0060artifact_locations\u0060 or \u0060agentera query --list-artifacts --format json\u0060 to locate the mapped plan path and raw-access boundary before any diagnostic raw read. Do not search Agentera directories manually. Existing plan artifacts provide repository-local examples of the shape.\n\nFor normal Plan startup, \u0060agentera prime --context plan --format json\u0060\nexposes \u0060capability_context.context.planning_context.startup_contract\u0060 as the\ncompact read model for planning levels, step markers, CLI-first orientation, plan\nartifact boundaries, full-plan review/self-audit requirements, and handoff\nexpectations. Use that context before rereading this prose. Read this file when editing Plan,\nresolving contradiction or ambiguity, validating detailed behavior not covered\nby compact context, or investigating benchmark/read-trigger evidence.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, prefer the CLI artifact-location contract from \u0060agentera describe --format json\u0060 or \u0060agentera query --list-artifacts --format json\u0060. It resolves \u0060.agentera/docs.yaml\u0060 mappings, default paths, existence, and read boundaries without a separate raw docs read. Raw \u0060.agentera/docs.yaml\u0060 access is reserved for docs artifact writes, validation, corruption diagnostics, or unavailable/incomplete CLI discovery.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: status tokens VT1-VT4 (■/▣/□/▨), list item VT15 (▸), inline separator VT16 (·), section divider VT14, flow/target VT17 (→). Skill glyphs SG1-SG12 for cross-capability references. Exit signals EX1-EX4 for the exit marker. Decision labels DL1-DL3 for DECISIONS.md reading. Severity issue levels SI1-SI4 for TODO entries. Phases PH1-PH5 for phase context.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference.\n\n---\n\n## Step 0: Detect level\n\nAssess work complexity. Read the description (user, DECISIONS.md, or TODO.md). Scan codebase if needed.\n\n| Signal | Level |\n|--------|-------|\n| Single-file change, bug fix, config tweak, < 50 lines | **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\nconfirmation 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---\n\nStep markers: display \u0060── step N/6: verb\u0060 before each step (Step 0 excluded). Steps: orient, specify, review, audit, write, handoff.\n\n## Step 1: Orient\n\nUse CLI-provided startup state and listed CLI fallbacks before raw artifact reads.\nFor current PLAN.md context, prefer \u0060agentera plan --format json\u0060; if its source\ncontract is complete, skip raw \u0060.agentera/plan.yaml\u0060 reads during this read-only\norientation step.\n\nOrient on VISION.md, DECISIONS.md, TODO.md, HEALTH.md, PROGRESS.md, and profile\nstate through the supported CLI state seam where available. If a required state\nfamily is missing or incomplete, run the CLI-provided fallback before any\nlast-resort raw artifact read.\n\n1. **VISION.md**: the north star (if exists)\n2. **DECISIONS.md**: use \u0060agentera decisions --format json\u0060; read \u0060firm\u0060 (DL1) entries only (hard constraints for planning), and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n3. **HEALTH.md**: latest codebase health grades (if exists)\n4. **TODO.md**: related known issues (if exists)\n5. **PROGRESS.md**: what was built recently (if exists)\n6. **Decision profile**: read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly when it exists. If missing, proceed without persona grounding.\n\n7. **Project discovery** (if unfamiliar):\n   - Map directory structure\n   - Read dependency manifests, README.md, CLAUDE.md, AGENTS.md\n   - Identify build/test/lint commands\n\nBefore decomposing: summarize the constraints from VISION.md and DECISIONS.md. If the decisions source contract reports \u0060complete_for_normal_deliberation_context=true\u0060, do not read raw \u0060.agentera/decisions.yaml\u0060 for normal planning context.\n\n---\n\n## Step 2: Specify\n\nDefine WHAT and WHY. Intent layer, not implementation details.\n\nEffort-bias check: when comparing plan shapes, do not treat effort spent constructing an option as evidence for it.\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.md. 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 VISION.md\n- **Constraints**: architectural boundaries, off-limits modules\n- **Scope**: what's in, out, deferred\n- **Design**: approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure; those belong in scope or task-level acceptance. Design SHOULD describe how subsystems interrelate and the order phases SHOULD run in.\n- **Task decomposition**: 3-8 ordered tasks, each one build cycle. Per task: description, dependencies, 3-5 behavioral Given/When/Then acceptance criteria\n- **Test proportionality**: for tasks with tests, add a proportionality target. Default: one pass + one fail per testable unit.\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 DOCS.md versioning exists and the plan includes \u0060feat\u0060/\u0060fix\u0060 work.\n- **Overall acceptance criteria**: behavioral criteria for the complete feature\n\nPresent for approval or proceed to adversarial review.\n\n---\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.md 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\u0060\u0060\u0060\n\nAddress legitimate issues; dismiss false positives with rationale. Present reviewed plan.\n\n---\n\n## Step 4: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation.\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\n## Step 5: Write PLAN.md\n\nWrite tasks with acceptance criteria. The conversation preserves reasoning; the artifact preserves the plan.\n\nWrite the plan to \u0060.agentera/plan.yaml\u0060.\n\nArtifact writing follows contract Section 24 conventions.\n\n### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: YYYY-MM-DD\n  status: active\n  title: Short Title\nwhat: One paragraph.\nwhy: Motivation and value.\nconstraints: What must not break; what is out of scope.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\ntasks: []\n\u0060\u0060\u0060\n\n### Full plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: YYYY-MM-DD\n  status: active\n  reviewed: YYYY-MM-DD\n  critic_issues: \"N found, N addressed, N dismissed\"\n  title: Short Title\nwhat: Detailed description.\nwhy: Motivation, user impact, relationship to vision.\nconstraints: Architectural boundaries and off-limits modules.\nscope:\n  included: []\n  excluded: []\n  deferred: []\ndesign: Approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure.\ntasks:\n  - number: 1\n    name: Title\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN context WHEN action THEN expected outcome\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\nsurprises: []\n\u0060\u0060\u0060\n\n---\n\n## Step 6: Handoff\n\n- **Single task**: suggest ⧉ build to execute and wait for confirmation.\n- **Full plan**: suggest ⎈ orchestrate to execute the entire plan and wait for confirmation.\n\n---\n\n## How build reads PLAN.md\n\nWhen PLAN.md has pending tasks, build's Step 2 changes:\n\n1. Read PLAN.md\n2. Find tasks with \u0060Status: □\u0060 (VT3) pending whose dependencies are all \u0060Status: ■\u0060 (VT1) complete\n3. Pick the first eligible task\n4. Use the task's acceptance criteria as exit conditions\n5. After committing, update task status to \u0060■ complete\u0060\n6. If unexpected, add to \u0060## Surprises\u0060\n7. If a task doesn't make sense, mark it \u0060skipped\u0060\n\nWhen all tasks complete:\n\n1. Archive PLAN.md to \u0060.agentera/archive/plan-{date}.yaml\u0060\n2. Delete \u0060.agentera/plan.yaml\u0060\n3. Build resumes vision-driven work selection\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER include implementation details in PLAN.md. Plan owns WHAT and WHY. Build owns HOW.\n- NEVER write acceptance criteria that reference implementation. Use behavioral, domain-language criteria only.\n- NEVER produce more than 8 tasks in a full plan. If work requires more, split into sequential plans.\n- NEVER modify PLAN.md during a build cycle except to update task status and add surprises.\n- NEVER skip adversarial review for full plans.\n- NEVER auto-approve plans when human-initiated. Present for approval.\n- NEVER plan trivial work. If skip level, say so and stop.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ≡ plan · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details.\n\n- **complete** (EX1): PLAN.md written and approved, adversarial review ran for full plans, handoff suggested.\n- **flagged** (EX2): Plan produced with caveats: critic issues dismissed, scope larger than ideal, or acceptance criteria not fully behavioral.\n- **stuck** (EX3): Cannot plan: description too ambiguous, context files contradict, or user declined approval with no revision path.\n- **waiting** (EX4): Feature not specified enough for acceptance criteria, or key architectural constraints unknown.\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, the next step is ≡ plan. DECISIONS.md provides the \"why\" context.\n\n### Feeds ⧉ build\n\nPLAN.md tasks become build's work queue. Task acceptance criteria become cycle exit conditions. Build updates status and logs surprises.\n\n### Feeds ⎘ optimize\n\nWhen a plan includes optimization-shaped tasks, those tasks can be delegated to optimize.\n\n### Informed by ⛶ audit\n\nHEALTH.md 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 output\n\nVISION.md provides the north star that plan reads 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 conventions\n\nPlan reads the \u0060versioning\u0060 block from DOCS.md. When the plan includes \u0060feat\u0060/\u0060fix\u0060 work, plan appends a version bump task.\n\n---\n\n## Getting started\n\n### Planning a new feature\n\n1. ❈ discuss: deliberate on what to build and why\n2. ≡ plan: plan how to build it\n3. ⧉ build or ⎈ orchestrate: execute\n\n### Planning a remediation\n\n1. ⛶ audit: audit codebase health\n2. ≡ plan: plan fixes\n3. ⧉ build: execute\n\n### Mid-feature replanning\n\nIf build logs multiple surprises in PLAN.md:\n\n1. Read the surprises section\n2. ≡ plan: reassess tasks\n3. Resume ⧉ build\n\n### Skipping the plan\n\nFor trivial work, plan detects skip level and routes to ⧉ build directly.\n"`);
-export default instructions;
-//# sourceMappingURL=instructions.js.map
+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

@@ -1,6 +1,105 @@
-// Source: skills/agentera/capabilities/profile/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 `"# PROFILE\n\n**Persona Reconstruction: Observable Footprint Indexing Logic. Extract, Reconcile, Formalize**\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.\n\nSkill introduction: \u0060─── ♾ profile · profile ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **♾** (protocol ref: SG9). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne global artifact (written) and project-level artifacts (read).\n\n| Artifact | Purpose | Path |\n|----------|---------|------|\n| PROFILE.md | Decision profile consumed by all capabilities | \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060) |\n| DECISIONS.md | High-signal source for pattern extraction | \u0060.agentera/decisions.yaml\u0060 (per docs.yaml mapping) |\n\n### Artifact path resolution\n\nPROFILE.md is global. Its base directory defaults to the platform-appropriate data directory (\u0060$XDG_DATA_HOME/agentera/\u0060 on Linux, \u0060~/Library/Application Support/agentera/\u0060 on macOS, \u0060%APPDATA%/agentera/\u0060 on Windows). Override via \u0060AGENTERA_PROFILE_DIR\u0060 environment variable. Existing profiles at \u0060~/.claude/profile/\u0060 are auto-migrated on first run. \u0060.agentera/docs.yaml\u0060 mapping does not apply to PROFILE.md. For project-level artifacts, check if .agentera/docs.yaml exists and use its path mapping; if absent, use the default layout.\n\n### Contract values\n\nContract values are inlined where referenced. Confidence scale tiers CS1-CS5 for numeric boundaries (90-100, 70-89, 50-69, 30-49, 0-29) with thresholds at 65 (strong constraint) and 45 (suggestion). Visual tokens: confidence tokens VT9-VT11 (━/─/┄), list item VT15 (▸), inline separator VT16 (·), section divider VT14, progress bar VT18. Skill glyph SG9 for exit markers. Exit signals EX1-EX4 for status reporting. Decision labels DL1-DL3 for entry firmness.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\nTwo modes:\n\n- **Full**: Detect available local runtime history, ask which extractable runtimes to include, synthesize from scratch, write a fresh PROFILE.md.\n- **Validate**: Quick incremental check. Surface the ~6 entries most worth validating, let the user confirm or challenge each one, update metadata in place.\n\n---\n\n## Step 0: Detect mode\n\nBefore doing anything else, check if \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 exists (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060).\n\n**If it does NOT exist**: Proceed directly to Full mode (Step 1).\n\n**If it DOES exist**: Present the mode choice.\n\nNarration voice (riff, don't script):\n\n- \"Profile's here. Full rebuild or quick tune-up?\" · \"You've got a profile already. Regenerate from scratch, or just validate what's there?\"\n\nOffer:\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\nIf the user chooses **Full**, proceed to Step 1.\nIf the user chooses **Validate**, skip to Validate Mode.\n\n---\n\n## Full Mode\n\nThe sharp colleague, here to pay attention to how you decide, not run a classification pipeline. This is someone who's been watching your work, noticing patterns, and reflecting back what they've seen. \"Here's what I've noticed about how you work,\" not \"Signal extraction complete.\"\n\nStep markers: display \u0060── step N/6: verb\u0060 before each step.\nSteps: detect, extract, read, categorize, generate, validate.\n\n### Step 1: Coverage Audit (mandatory pre-extraction)\n\nBefore asking what to include or running extraction, run the Coverage Audit. This is the **first user-visible output** of every Full-mode run:\n\n\u0060\u0060\u0060bash\nnpx -y agentera report refresh --consent local-history --coverage-audit-only\n\u0060\u0060\u0060\n\nThe audit enumerates all supported runtimes (codex, claude-code, cursor, cursor-agent, opencode, github-copilot) with store paths and earliest/latest session timestamps. It names skipped runtimes and reasons. Do not display raw transcript content.\n\nTreat a runtime as **available** when the audit marks it \u0060available\u0060 with session timestamps. Treat \u0060missing\u0060, \u0060skipped\u0060, \u0060sparse\u0060, and \u0060degraded\u0060 runtimes as unavailable for selection; report them briefly with bounded status/reason labels and remediation labels when present.\n\n**EX2 gating:** If any available runtime would be skipped by flags or the user's selection, stop and emit \u0060♾ profile · flagged\u0060 (EX2). Do not extract until the user explicitly accepts the coverage gap. When the user accepts, rerun extraction with \u0060--accept-coverage-gap\u0060 plus the agreed runtime opt-out flags. If all available runtimes are selected, proceed without EX2 for coverage.\n\nSupported runtime sources:\n\n- **Claude Code**: default \u0060~/.claude/projects\u0060, override with \u0060--claude-projects-dir <path>\u0060, disable with \u0060--no-claude\u0060\n- **Codex**: default \u0060~/.codex/sessions\u0060, override with \u0060--codex-sessions-dir <path>\u0060, disable with \u0060--no-codex\u0060\n- **OpenCode**: default \u0060opencode db path\u0060 when available, override with \u0060--opencode-conversations-dir <path>\u0060, disable with \u0060--no-opencode\u0060\n- **GitHub Copilot**: default \u0060$COPILOT_HOME\u0060 or \u0060~/.copilot\u0060, override with \u0060--copilot-conversations-dir <path>\u0060, disable with \u0060--no-copilot\u0060\n- **Cursor IDE**: default \u0060$CURSOR_HOME/projects\u0060 or \u0060~/.cursor/projects\u0060, override with \u0060--cursor-projects-dir <path>\u0060, disable with \u0060--no-cursor\u0060\n- **Cursor Agent CLI**: default \u0060~/.config/cursor/chats\u0060, override with \u0060--cursor-chats-dir <path>\u0060 or \u0060$CURSOR_CONFIG_HOME/chats\u0060; disabled with \u0060--no-cursor\u0060\n\nAsk which runtime histories to include with a multi-select question. Put \u0060All (Recommended)\u0060 first; it means every selectable runtime from the preview and wins over any individual runtime selections. Also offer one option per selectable runtime and a docs/config-only option for cases where the user wants no runtime conversation history. The question controls runtime conversation sources only; instruction documents and project config signals remain included.\n\nIf no runtime has extractable records, skip the selection question, say no local runtime history is currently extractable, and continue with instruction documents and project config signals.\n\n### Step 2: Run extraction\n\nRead \u0060$AGENTERA_PROFILE_DIR/intermediate/corpus.json\u0060 if it already exists and still matches the selected runtime set. If the corpus is absent, stale, or was produced for a different source selection, run the extractor from the Agentera app:\n\n\u0060\u0060\u0060bash\nnpx -y agentera report refresh --consent local-history\n\u0060\u0060\u0060\n\nThe extractor always emits the Coverage Audit summary before writing corpus files. Apply runtime opt-out flags from Step 1. For example, if the user selects Claude Code and OpenCode only, run with \u0060--no-codex --no-copilot --no-cursor\u0060. If the user selects docs/config-only, run with \u0060--no-claude --no-codex --no-opencode --no-copilot --no-cursor\u0060. If the user selects \u0060All (Recommended)\u0060, use no runtime opt-out flags. When the user explicitly accepted skipping available runtimes in Step 1, add \u0060--accept-coverage-gap\u0060; without it the extractor stops with EX2.\n\nThe extractor writes the default \u0060$AGENTERA_PROFILE_DIR/intermediate/corpus.json\u0060 envelope and emits the four portable Section 22 families: \u0060instruction_document\u0060, \u0060history_prompt\u0060, \u0060conversation_turn\u0060, and \u0060project_config_signal\u0060. Use \u0060--output <path>\u0060, repeated \u0060--project-root <path>\u0060, \u0060--codex-sessions-dir <path>\u0060, \u0060--claude-projects-dir <path>\u0060, \u0060--opencode-conversations-dir <path>\u0060, \u0060--copilot-conversations-dir <path>\u0060, \u0060--cursor-projects-dir <path>\u0060, or \u0060--cursor-chats-dir <path>\u0060 when the host stores data outside the defaults.\n\nRead the corpus file's top-level \u0060metadata\u0060 object to confirm counts per source family. Report totals to the user.\n\n**If extraction fails**: common causes include \u0060npx\u0060/agentera not found, permission errors, and empty output (no session history). If only some runtimes fail, the corpus will contain partial data with bounded runtime notes in \u0060metadata.runtime_statuses\u0060; proceed and note missing sources.\n\n---\n\n### Step 3: Read corpus data\n\nRead the corpus.json produced in Step 2. Each record carries a \u0060source_kind\u0060 field. Group records by source family for synthesis:\n\n1. **instruction_document**: Memory files, CLAUDE.md, AGENTS.md (highest signal: explicit user instructions)\n2. **history_prompt**: Decision-rich prompts from session history\n3. **conversation_turn**: Decision exchanges from conversations (most nuanced: real-time reasoning)\n4. **project_config_signal**: Recurring config patterns across projects (most objective: what shipped)\n\nRead the full corpus before synthesis. If total records exceed 500, prioritize high-signal records:\n\n- history correction or decision kinds\n- longer user responses\n- configs shared across projects\n\n---\n\n### Step 4: 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,\n  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---\n\n### Step 5: Generate the profile\n\nOutput constraint: ≤30 words per signal, ≤15 words per evidence line.\n\nWrite the decision profile to \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060.\n\nIf a previous version exists: copy to \u0060$AGENTERA_PROFILE_DIR/history/PROFILE-{timestamp}.md\u0060, generate new version, show change summary (added, updated, removed).\n\nWhen presenting the profile, frame it as a colleague reflecting on what they've observed, not a system delivering results. Open with what stood out, what surprised you, where the user is most consistent and where they contradict themselves. The structured profile follows, but the human read comes first.\n\n#### Profile format\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 CLAUDE.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### Step 6: Validate predictions\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\"). Below 3/5: identify categories needing more signal, note in profile header.\n\n---\n\n## Validate Mode\n\nQuick incremental check (~2 minutes). Same colleague voice: you're checking in on what you noticed before, not running a diagnostic. \"Still true? Let me know.\"\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: select, present, apply, write.\n\n### Step V1: Run smart selection\n\nIdentify which entries are most worth checking by reading \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 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\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\n### Step V4: Write and report\n\nUpdate the first header comment before writing PROFILE.md:\n\n- Set \u0060Validated:\u0060 to today's date.\n- Preserve \u0060Generated:\u0060 unchanged (last full rebuild date).\n- If the profile predates \u0060Validated:\u0060, append \u0060| Validated: {today}\u0060 to that comment line.\n- If \u0060Validated:\u0060 already exists, replace its date.\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- NEVER fabricate decision patterns. Every profile entry must be grounded in observed evidence from session history, memory files, configs, or conversation data.\n- NEVER assign confidence higher than the evidence warrants. A single data point is 30-49 (CS4), not 70+, regardless of how insightful the decision sounds.\n- NEVER smooth over contradictions. When evidence conflicts, record tensions rather than forcing a coherent narrative.\n- NEVER modify the user's session history, memory files, or config files. Profile reads these sources; it never writes to them.\n- NEVER 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, 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 the extraction scripts failed entirely, Python is unavailable, or \u0060~/.claude/\u0060 is unreadable and no session data can be accessed.\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\nProfile is part of a twelve-capability suite. The decision profile it produces is consumed by the other capabilities.\n\n### Consumed by build\n\nBuild runs the effective profile script in its Orient step to get a confidence-weighted summary table. High effective confidence entries are treated as strong constraints; low effective confidence entries are treated as suggestions. Full rules are read from PROFILE.md when needed for detailed reasoning.\n\n### Consumed by optimize\n\nOptimize runs the effective profile script to calibrate experimentation style: how aggressive to be, how much complexity is acceptable, what trade-offs the user prefers. Effective confidence weighting ensures stale preferences don't over-constrain experiments.\n\n### Consumed by research\n\nResearch can run the effective profile script to inform applicability judgments: what patterns the user favors, what they resist, how to weigh recommendations. High-confidence entries strongly constrain recommendations; low-confidence entries are treated as tendencies.\n\n### Consumed by discuss\n\nDiscuss reads the decision profile at the start of every deliberation. High-confidence entries in the relevant domain are acknowledged upfront to prevent re-deliberating settled preferences. Low-confidence entries are surfaced as hypotheses worth testing during the conversation.\n\n### Fed by discuss\n\nDECISIONS.md (maintained by discuss) is a high-signal source for profile's extraction scripts. Each decision entry captures reasoning, tradeoffs, and confidence, making deliberation sessions one of the richest inputs for decision profile generation. For normal read-only extraction, prefer \u0060agentera decisions --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### Consumed by audit\n\nAudit reads the decision profile to calibrate what \"healthy\" means for this user. Quality preferences, complexity tolerance, and pattern priorities from the profile weight the grading and determine which findings matter most.\n\n### Consumed by plan\n\nPlan reads the decision profile during its Orient step to calibrate planning depth, pattern preferences, and constraint priorities.\n\n### Profile consumption\n\nAll consuming capabilities read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly when it exists. Confidence thresholds and dormancy notes are kept in the profile itself so the guidance remains editable and portable.\n\n---\n\n## Getting started\n\n### First profile generation\n\n\u0060\u0060\u0060\n/agentera profile\n\u0060\u0060\u0060\n\nFull extraction across all sources. Produces \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060.\n\n### Regular 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\n### Using the profile in other capabilities\n\nAll capabilities may read the profile directly when \u0060PROFILE.md\u0060 exists. No manual steps needed; just ensure PROFILE.md exists.\n\n---\n\n## Notes on depth vs speed\n\n- Extraction scripts handle I/O; Claude's job is synthesis, not parsing.\n- Large intermediate files: use subagents to read in parallel.\n- Signal hierarchy: crystallized.json (highest: memory + CLAUDE.md), conversation exchanges (most nuanced: real-time reasoning), config patterns (most objective: what shipped).\n- Validate mode: weekly/per-session. Full mode: monthly or when significantly stale.\n"`);
+import { personalGlossaryOutputContract } from "../../registries/glossaryEntryContract.js";
+import { personalGlossaryCandidateProjectionContract } from "../../registries/glossaryCandidateProjectionContract.js";
+import { personalGlossaryCandidateDecisionContract } from "../../registries/glossaryCandidateDecisionContract.js";
+import { personalGlossaryProfileFullContract } from "../../registries/glossaryProfileFullContract.js";
+import { personalGlossaryReviewRecordsContract } from "../../registries/glossaryReviewRecordsContract.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 fullModeExistingGenerationInstructions = `#### Step 1: Verify existing bounded evidence
+
+Profile Full uses an already published bounded signal tier. It MUST NOT run \`report refresh\`, collect local history, or create a generation implicitly. Read \`profile_context.profile.bounded_signals\` before synthesis. If it is missing, legacy, stale, or corrupt, stop before any base write and report its explicit-consent recovery. If it is insufficient, continue only with its declared confidence cap and flagged output. Do not load a monolithic corpus or rescan history.
+
+**Separate explicit refresh (outside this Full run):** The active runtime IDs are exactly \`opencode\`, \`codex\`, \`cursor\`, and \`copilot\`. A user who explicitly wants a new generation may run \`npx -y agentera@next report refresh --consent local-history\`, then start a new Full run. Cursor Agent CLI storage is a Cursor source product, never a separate runtime identity. Claude Code is not a supported runtime. Its transcript parser is an explicit historical importer only: \`npx -y agentera@next report refresh --consent local-history --import-source claude\`. Before that opt-in, warn that transcripts can contain secrets, file contents, and command output. Every imported record is labeled \`source_class=historical_import\`, \`source_product=claude-code\`, and \`active_runtime=false\`; default active analytics exclude it.
+
+#### Step 2: Read bounded signals`;
+/** Build and validate glossary-owned Profile Full instructions only when Profile is requested. */
+export function servedInstructions() {
+    const profileGlossaryOutput = personalGlossaryOutputContract();
+    const profileGlossaryCandidates = personalGlossaryCandidateProjectionContract();
+    const profileGlossaryDecision = personalGlossaryCandidateDecisionContract();
+    const profileGlossaryReviews = personalGlossaryReviewRecordsContract();
+    const profileGlossaryProfileFull = personalGlossaryProfileFullContract();
+    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 base-profile 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 while preserving the owned section.** 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:consume-existing-personal-glossary-generation -->
+3. **Consume one existing personal glossary generation.** Only after the base write, run \`${profileGlossaryCandidates.candidateReadCommand} list --limit ${profileGlossaryProfileFull.candidateListLimit} --format json\` once. Bind this Full run to that response's \`generation\`, \`policy_version\`, and \`candidate_projection_sha256\`; do not follow \`next_cursor\`. This command reads the existing consent-bound user-local projection bound to the readable current tier generation. Do not refresh history, acquire consent, collect or reread history, discover candidates, create or persist a projection, or create another generation. If its coverage report is degraded, stop the personal glossary flow after this list: do not call \`get\`, classify, invoke decision or review queue, or publish. Keep \`B\` and \`G\` exactly as written, report the explicit \`npx -y agentera@next report refresh --consent local-history\` recovery, and continue without personal publication. If the current tier generation or projection is missing, stale, corrupt, empty, or the bounded read fails, use the same preservation and recovery.
+
+<!-- agentera:profile-full-action:decide-personal-glossary-candidates -->
+4. **Classify only the bounded selection, then use CLI admission.** Only when Step 3 is not degraded, for each returned summary use \`${profileGlossaryCandidates.candidateReadCommand} get\` with every required binding. Classify only that bounded exact view and its safe context. Submit a \`${profileGlossaryDecision.receiptConstructionRequestSchemaVersion}\` request to \`${profileGlossaryDecision.command} --input - --format json\` with exactly \`${profileGlossaryDecision.receiptConstructionRequestFields.join("\`, \`")}\`; use the exact candidate bindings from the list and get results, and supply only the host classification. The CLI computes \`semantic_fingerprint\` and \`receipt_sha256\` and returns the receipt and decision needed by queue or publication. Host classification is semantic evidence, never admission authority. Preserve the CLI outcome and reason exactly: do not synthesize or upgrade a decision. If an exact read or decision fails, report one bounded failure and do not publish that candidate. An inferred or ambiguous result is never eligible for automatic admission. A project-scoped result must abstain; never inspect project state to resolve it.
+
+<!-- agentera:profile-full-action:queue-personal-glossary-reviews -->
+5. **Queue review before asking.** For every \`review_required\` result, submit the same receipt to \`${profileGlossaryReviews.command} queue --input - --format json\`. This is the durable review path. If a host question channel is available, show at most ${profileGlossaryProfileFull.questionReviewMaximum} queued review cards, each limited to term, proposed meaning, reason, occurrence count, and safe context when present. A conversational answer is not a disposition or publication approval. It must go through the authenticated local-host review disposition flow. Without a question channel, ask nothing and rely on the durable queue. For \`abstain\`, keep the bounded reason explainable in the final summary and do not queue or publish it.
+
+<!-- agentera:profile-full-action:publish-authorized-explicit-candidates -->
+6. **Publish only current explicit automatic decisions.** For each CLI \`automatic_admission\` with reason \`explicit_current_authorized\`, submit the receipt, exact CLI decision, and one injected \`as_of\` date to \`${profileGlossaryOutput.command} --input - --format json\`. Do not use \`--dry-run\` as publication and do not publish a \`review_required\` or \`abstain\` result. The publisher revalidates the current generation and changes only the owned \`G\` range at the same \`profile_context.profile.path\`; a failed or replayed publication cannot replace the base profile or any unapproved glossary entry.
+
+Show the non-glossary change summary (added, updated, removed), followed by one compact bounded glossary summary: automatic publications, queued reviews, abstentions, and failures. Do not print candidate pages, history, anchors, project keys, or project glossary state.
+
+### Personal Glossary section
+
+Profile Full preserves a validated existing personal Glossary section until the canonical publisher receives a current authorized decision. 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 performs no consumer lookup, project precedence, or semantic-equivalence review; Discuss, Plan, and Build obtain active consumer behavior separately through \`agentera report glossary-advice\`.
+
+Each publisher-created 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.
+
+The separate publisher writes 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. Only the \`${profileGlossaryOutput.requestSchemaVersion}\` publication operation may add, refresh, or decay this section. Profile Full preserves \`G\` exactly until that operation authorizes its replacement.
+
+The publisher 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.
+
+The publisher merges terms case-insensitively. It preserves 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.
+`;
+    const servedInstructionBody = instructions
+        .replace("Steps: extract, read, synthesize, generate.", "Steps: verify, read, synthesize, generate.")
+        .replace(/#### Step 1: Coverage and extraction[\s\S]*?#### Step 2: Read bounded signals/, fullModeExistingGenerationInstructions)
+        .replace("Read the bounded signal tier published in Step 1.", "Read the existing bounded signal tier.")
+        .replace("Run Step 1 refresh to publish bounded tiers first.", "Stop and report the explicit refresh recovery; do not refresh during Full mode.")
+        .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)
+        .replace("Full extraction across all sources. Produces PROFILE.md at `profile_context.profile.path`.", "Uses existing consent-bound bounded evidence and a current personal glossary generation. Produces PROFILE.md at `profile_context.profile.path`.");
+    return servedInstructionBody;
+}
+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 instructions;
-//# sourceMappingURL=instructions.js.map

package/dist/capabilities/research/instructions.js

@@ -1,6 +1,5 @@
-// Source: skills/agentera/capabilities/research/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 `"# RESEARCH\n\n**Insight Navigation: Source Pattern Identification and Resonance. Evaluate, Reframe, Assimilate**\n\nAnalyze an external resource and map its ideas to a target project. Output a structured markdown analysis the user can navigate and act on.\n\nSkill introduction: \u0060─── ⬚ research · analysis ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **⬚** (protocol ref: SG10). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nNo dedicated state file. Writes to other capabilities' artifacts.\n\n| Artifact | Purpose | Path |\n|----------|---------|------|\n| TODO.md | File actionable findings for build (severity per protocol SF1-SF3) | \u0060TODO.md\u0060 (per DOCS.md mapping) |\n| VISION.md | Refine direction when inspiration shifts thinking | \u0060VISION.md\u0060 (per DOCS.md mapping) |\n| PROFILE.md | Decision profile for persona-grounded applicability judgments | \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (global, not project-scoped) |\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if .agentera/docs.yaml exists. If it has an Artifact Mapping section, use the path specified for each canonical filename (TODO.md, VISION.md, etc.). If .agentera/docs.yaml doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at .agentera/vision.yaml; other agent-facing artifacts at .agentera/*.yaml. This applies to all artifact references in this capability, including cross-capability writes (TODO.md, VISION.md).\n\nPROFILE.md is global, not project-scoped. Its path is determined by profile: \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060). Check the profile-determined path directly rather than falling back to the project root.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: confidence tokens VT9-VT11 (━/─/┄), list item VT15 (▸), inline separator VT16 (·), section divider VT14. Skill glyph SG10 for exit markers. Exit signals EX1-EX4 for status reporting. Severity finding levels SF1-SF3 for TODO.md entries.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: identify, read, explore, map, deliver.\n\n---\n\n## Step 1: Identify source and target\n\nFrom the user's message, extract:\n\n- **Source**: the external URL (GitHub repo, article, docs, HN thread, etc.)\n- **Target**: the user's project, which could be any of:\n  - A **GitHub repo URL** → explore via the optional GitHub MCP integration\n  - A **local path** or project name → explore via filesystem tools\n  - The **current working directory** → 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** → if truly no target is implied, skip Steps 3–4 and do source-only analysis\n\n---\n\n## Step 2: Read the source\n\nThis should feel like a colleague diving into something interesting, genuinely curious, reading deeply, forming opinions as you go. Not a report generator collecting data points.\n\n### GitHub repos\n\nUse the optional GitHub MCP integration to explore deeply:\n\n1. List root directory structure\n2. Read README\n3. Read key source directories until you understand: core abstractions, design patterns,\n   notable primitives, dependencies, clever approaches worth borrowing\n\nGo deep and don't stop at the README. If the optional GitHub MCP integration\nreturns errors, 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 context7 for up-to-date docs beyond the README.\n\nBefore proceeding to target analysis: in your response, list the 3-5 most transferable concepts from the source. These survive if the source file reads are cleared.\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. \u0060Glob\u0060 to map the directory structure (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. \u0060Grep\u0060 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 the optional GitHub MCP integration:\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 across\n\nWith both codebases understood, reason about applicability:\n\n- What is the source doing that the target should be?\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 refactor?\n\n---\n\n## Step 5: Deliver the analysis\n\nThe sharp colleague, here to share what you dug up, not file a report. Open with your take before the structured sections: what excited you, what surprised you, what the user should care about most. \"Here's what I found and what matters for us.\" The structured analysis follows, but the human read comes first.\n\nWrite a **structured markdown analysis**:\n\n### Output format\n\n\u0060\u0060\u0060\u0060markdown\n# [Source Name] → [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 applies to the target.\n\n### [Concept Name]\nSection repeats for each significant concept (typically 2–5).\n\nReasoning about applicability SHOULD live in the response text, not the matrix.\nThe Applicability Matrix MUST contain only conclusions, not reasoning chains.\nEach matrix cell MUST be ≤15 words.\n\n## Applicability Matrix\n\n| Concept | Relevance | Effort | Where in [Target] | Already Partially Done? |\n|---------|-----------|--------|-------------------|------------------------|\n| ...     | High/Med/Low | Low/Med/High | specific module or file | Yes/No |\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▸ [action] · [specific file or module]\n▸ [action] · [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\nOffer to go deeper: prototype a change, 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- NEVER modify code in the target project. Research analyzes; other capabilities implement.\n- NEVER write to TODO.md or VISION.md without explicit user confirmation. Present findings and get approval before filing.\n- NEVER present shallow analysis as deep insight. If you haven't read the source thoroughly, say so.\n- NEVER recommend adoption without assessing fit. Every recommendation must consider the target project's constraints, stack, and principles.\n- NEVER 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 (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⬚ research · <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 research's canonical glyph ⬚ (SG10, U+2B1A).\n\n- **complete** (EX1): 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** (EX2): 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 (e.g., incompatible language or paradigm).\n- **stuck** (EX3): 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** (EX4): 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.md'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's Hypothesize step can draw on the analysis for its next experiment.\n\n### Informed by profile\n\nIf a decision profile exists at \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060, read it directly and use effective confidence to weight applicability judgments. If PROFILE.md is missing, proceed without persona grounding.\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 ⛥ vision to revisit VISION.md with the new context.\n\n### Feeding into plan\n\nWhen the analysis recommends adopting 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 ❈ discuss to think it through before acting. Discuss can evaluate which recommendations are actually worth adopting and capture the reasoning in DECISIONS.md.\n\n---\n\n## Getting started\n\n### Analyze 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\n### Analyze 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\n### Feed findings into the development loop\n\nAfter analysis, file actionable findings to TODO.md for ⧉ build to pick up, or refine VISION.md if the research shifts your project's direction.\n\n---\n\n## Notes on depth vs. speed\n\n- Read more files, not fewer. Shallow reads produce shallow analysis.\n- Large repos: focus on modules most relevant to the concept, not everything.\n- Explore source and target concurrently where possible.\n- Always use the optional GitHub MCP integration for GitHub URLs.\n"`);
+// 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;
-//# sourceMappingURL=instructions.js.map

package/dist/capabilities/status/instructions.js

@@ -1,6 +1,15 @@
-// Source: skills/agentera/capabilities/status/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 `"# 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 on first install and 100th session. A bare user message exactly \u0060/agentera\u0060 uses this same briefing path, not generic greeting behavior.\n\nEach invocation = one orientation. Uses the CLI composite briefing first,\nwrites nothing.\n\n---\n\n## State artifacts\n\nGlyph: **⌂** (SG1). Status reads suite state through \u0060agentera prime\u0060 and writes\nnothing. It may fall back to direct reads only when the composite command fails\nor explicitly asks for fallback.\n\n### CLI-first access\n\nFor returning projects, run one composite command before any individual state\naccess:\n\n\u0060\u0060\u0060bash\nnpx -y agentera prime\n\u0060\u0060\u0060\n\nUse that output to render the dashboard and select the concrete next action. Do\nnot relay raw CLI lines as the user-facing briefing. Source labels such as\n\u0060mode:\u0060, \u0060profile:\u0060, \u0060v1_migration:\u0060, \u0060health:\u0060, \u0060todo:\u0060, \u0060plan:\u0060,\n\u0060objective:\u0060, \u0060attention:\u0060, \u0060next_action:\u0060, \u0060source_contract:\u0060, and the\ncompatibility \u0060bundle:\u0060 installed-app status object are parsing aids, not\ndashboard lines. Do not run \u0060agentera plan\u0060, \u0060agentera progress\u0060, \u0060agentera\nhealth\u0060, \u0060agentera todo\u0060, \u0060agentera decisions\u0060, or \u0060agentera objective\u0060 as part\nof normal status briefing assembly. Do not read raw\n\u0060.agentera/*.yaml\u0060 files for normal status orientation. If a normal dashboard field\nis missing from \u0060agentera prime\u0060, fix or extend the composite CLI contract instead\nof adding routine fallback reads. Use top-level fallback commands only when\n\u0060agentera prime\u0060 fails or explicitly reports fallback-only recovery.\n\nResolve \u0060RESOLVED_AGENTERA_HOME\u0060 with the app-home precedence \u0060AGENTERA_HOME\u0060\nwhen set, otherwise the platform data home, then run\nthe installed command once. Do not preflight app health with \u0060glob\u0060, \u0060grep\u0060,\n\u0060read\u0060, \u0060ls\u0060, \u0060python\u0060, \u0060doctor\u0060, \u0060--help\u0060,\n\u0060registry.json\u0060, or \u0060.agentera-bundle.json\u0060.\nNever combine the app-home assignment with the same shell command that expands\nthe managed app script path; shell expansion can otherwise turn an unset\n\u0060AGENTERA_HOME\u0060 into \u0060npx -y agentera\u0060 before the assignment takes effect.\n\nRecovery copy must be plain-language and recommendation-first. Never ask users\nto choose between technical install concepts, internal directory states,\ncommand-mode flags, or package-layout terms. Say what happened, what changed,\nwhat the safe fix does, and what it will not touch. The safe fix must say it will\nnot edit project files, shell startup files, or unknown directories. Good recovery labels are \u0060Use the safe fix\n(Recommended)\u0060, \u0060Choose a different directory\u0060, and \u0060Stop\u0060.\n\nIf the command cannot execute because \u0060AGENTERA_HOME\u0060 names the old default\n\u0060$HOME/.agents/agentera\u0060 and \u0060npx -y agentera\u0060 is missing,\ndo not require a successful failed CLI invocation and do not first ask the user to\nunset \u0060AGENTERA_HOME\u0060. Say: \u0060Agentera found an old or broken local copy of\nitself. The safe fix is to install a fresh copy in the normal Agentera directory.\u0060\nThen show this preview command and say it changes nothing:\n\n\u0060\u0060\u0060bash\nnpx -y agentera@latest doctor\n\u0060\u0060\u0060\n\nThat preview writes nothing. Because no explicit \u0060--install-root\u0060 is supplied,\nupgrade can choose the normal platform app directory and preview repair for app\nfiles, managed runtime surfaces, and cleanup of the old directory. Ask for\nexplicit approval before writes, using plain wording such as\n\u0060Approve the safe Agentera repair at <directory>\u0060. Then apply the same safe repair path:\n\n\u0060\u0060\u0060bash\nnpx -y agentera@latest prime\n\u0060\u0060\u0060\n\nAfter apply, retry the installed command from the platform app home reported by\nthe upgrade output, not from the old default directory. If the command exits\nsuccessfully, inspect the CLI-provided \u0060bundle.status\u0060 installed-app status\nobject. Only \u0060up_to_date\u0060 passes the installed Agentera app gate for normal briefing.\nThe object also carries \u0060appHome\u0060, \u0060managedAppRoot\u0060, \u0060userDataRoot\u0060,\n\u0060expectedVersionSource\u0060, \u0060bundle.dryRunCommand\u0060, \u0060bundle.applyCommand\u0060, and\napproval text. If the installed command cannot execute, is out of date, missing\n\u0060prime\u0060, fails before argparse, or reports manual-review-needed/repair-needed status, tell\nthe user \u0060Agentera found an old or broken local copy of itself.\u0060 Then preview the\nrepair with the CLI-provided command when present:\n\n\u0060\u0060\u0060bash\nnpx -y agentera@latest doctor\n\u0060\u0060\u0060\n\nDo not run the matching apply command until the user explicitly approves the\nsame Agentera repair and directory.\nAfter apply, retry \u0060npx -y agentera prime\u0060; do not treat local checkout\nfallback as installed-app success. If \u0060AGENTERA_HOME\u0060 names the old default\n\u0060$HOME/.agents/agentera\u0060, no explicit \u0060--install-root\u0060 was supplied, and\n\u0060npx -y agentera\u0060 is missing or out of date, show the normal\nAgentera directory preview above instead of first asking the user to unset\n\u0060AGENTERA_HOME\u0060; do not claim to prove where the environment value came from. If\n\u0060AGENTERA_HOME\u0060 points at any other missing path, file, or directory with unknown\nfiles, say: \u0060Agentera was told to use a directory it cannot safely use. Choose a\ndifferent Agentera directory, or approve --force only after checking that directory is\nsafe to replace.\u0060\n\nIf doctor reports a leftover 1.x managed marker block in\nshell startup files, say plainly that Agentera will not edit those files.\nCleanup is user-owned manual cleanup, not a repair write.\n\nUse \u0060agentera query <artifact-name> --format json|yaml\u0060 only for advanced or\ncustom artifact inspection when no top-level command serves the needed state.\n\n### Artifact path resolution\n\nOnly if \u0060agentera prime\u0060 fails and fallback raw artifact access is explicitly\nneeded, check \u0060.agentera/docs.yaml\u0060 for path mappings before reading artifacts.\nWithout a mapping, use the default layout:\n\n- Human-facing artifacts at the project root (Markdown): \u0060TODO.md\u0060, \u0060CHANGELOG.md\u0060, \u0060DESIGN.md\u0060\n- Agent-facing artifacts in \u0060.agentera/\u0060 (YAML): \u0060progress.yaml\u0060, \u0060decisions.yaml\u0060, \u0060health.yaml\u0060, \u0060plan.yaml\u0060, \u0060docs.yaml\u0060, \u0060vision.yaml\u0060, and per-objective \u0060objective.yaml\u0060 / \u0060experiments.yaml\u0060\n\nCanonical names are identifiers, not literal paths. PROFILE.md is global:\n\u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060, default \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060.\n\n### Contract values\n\nUse protocol tokens by ID where needed: severity arrows VT5-VT8, trend arrows\nVT12-VT13, progress bar VT18, separator VT16, list item VT15, section divider\nVT14, flow arrow VT17, skill glyphs SG1-SG12, exits EX1-EX4, issues SI1-SI4.\n\n---\n\n## Step 0: Detect mode\n\nRun the resolved installed \u0060agentera prime\u0060 and use its \u0060mode\u0060 field. If the\ninstalled-app status check reports out-of-date or blocked, show the CLI-provided\nrefresh preview before normal mode handling.\n\n- **No artifacts found** → Step 1a (first time on this project)\n- **Artifacts found** → Step 1b (returning to known project)\n\nNarration voice: warm, brief, unscripted.\n\n---\n\n## Step 0.5: CLI-owned checks\n\nDo not run separate v1 artifact or PROFILE.md checks during normal status\norientation. \u0060agentera prime\u0060 owns those checks and emits the mode, profile status,\n\u0060v1_migration.detected\u0060, \u0060v1_migration.affected_files\u0060,\n\u0060v1_migration.dry_run_command\u0060, \u0060v1_migration.apply_command\u0060, \u0060project_integration.recommendation\u0060, \u0060project_integration.message\u0060, \u0060project_integration.dry_run_command\u0060, \u0060project_integration.apply_command\u0060, attention items,\nand next action. When \u0060project_integration.recommendation\u0060 is \u0060upgrade\u0060, explain the plain-language \u0060project_integration.message\u0060, show the preview command (\u0060project_integration.dry_run_command\u0060; it changes nothing), and ask before \u0060project_integration.apply_command\u0060. When it is \u0060stay\u0060, do not suggest upgrade. User-facing upgrade commands omit \u0060--project\u0060 because the CLI defaults to the current repo. Render those fields; do not spend additional tool calls on\n\u0060.agentera/*.md\u0060, \u0060.agentera/*.yaml\u0060, \u0060VISION.md\u0060, or global profile-path\ndiscovery. Treat \u0060v1_migration.dry_run_command\u0060 as the CLI-supplied preview and\ntell the user it changes nothing. Ask before any upgrade apply command, and only run\n\u0060v1_migration.apply_command\u0060 after confirmation.\nThe artifacts phase migrates supported v1 Markdown files to YAML with backups\nafter preview and confirmation.\n\nIf \u0060v1_migration.detected\u0060 is false, emit no upgrade notice. Profile status is\nalso CLI-owned: render \u0060profile: loaded\u0060 without warning, and render\n\u0060profile.suggested_action\u0060 or a missing-profile attention item only when\n\u0060agentera prime\u0060 supplies one.\n\nIf \u0060npx skills update\u0060 refreshed only the visible skill and \u0060/agentera\u0060 next\nfinds missing or out-of-date app files, explain in plain language that Agentera\nalso needs to repair its local app copy; the visible skill update alone is not\nenough. Package-manager repair commands remain opt-in through\n\u0060--update-packages\u0060.\n\n---\n\n## Step 1a: Welcome\n\nFirst impression: the colleague meets a new project.\n\n1. **Use composite state**: Build the welcome from \u0060agentera prime\u0060 output only.\n   Do not scan README files, git history, languages, framework files, or project\n   size during bare orientation.\n\n2. **Share what's available**: lead with the suggested capability from\n   \u0060next_action\u0060. Do not enumerate the full suite unless asked.\n\n3. **Route**: ask what they'd like to do with a free-form prompt. Do not use a\n   native question menu on the initial welcome unless the user explicitly asked\n   for bounded choices. Invoke a capability only after the user confirms it.\n\n---\n\n## Step 1b: Briefing\n\nShow where things stand.\n\n1. **Use composite state**: Build the briefing from \u0060agentera prime\u0060 output.\n   - Use its mode, profile, health, todo counts, plan progress, objective,\n     attention, and next_action fields.\n   - Do not issue individual artifact queries during normal returning-project\n     orientation.\n   - Do not open raw \u0060.agentera/*.yaml\u0060 files unless the composite command fails\n     or names a fallback need.\n   - If exceptional fallback is required, prefer top-level commands such as\n     \u0060agentera plan\u0060, \u0060agentera progress\u0060, \u0060agentera health\u0060, \u0060agentera todo\u0060,\n     \u0060agentera decisions\u0060, \u0060agentera objective\u0060, and \u0060agentera experiments\u0060.\n     Missing normal dashboard fields should be repaired in \u0060agentera prime\u0060\n     instead of weakening the one-command path.\n   - Keep \u0060agentera query\u0060 for advanced/custom inspection only.\n\n2. **Brief them**: concise status, only what exists. No empty sections.\n   Show the agentera logo.\n\n   \u0060\u0060\u0060\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\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 is mandatory 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\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;\n     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\n3. **Attention items**: priority order with severity arrows (SI1-SI4):\n   - ⇶ (SI1) Critical issues, degrading health dimensions\n   - ⇉ (SI2) Blocked/overdue plan tasks, stale artifacts (plan-relative per contract staleness detection; fall back to PROGRESS.md recency heuristic when no plan context exists), overdue health audits (hybrid time/cycle staleness via \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 default 30 and \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 default 10; stale when either axis exceeds its threshold), loop stop-condition triggers\n   - → (SI3) Standard work: features, improvements, routine tasks\n   - ⇢ (SI4) Unresolved exploratory decisions\n\n   Nothing? Say so. A clean bill of health is useful.\n\n4. **Select the concrete next action before selecting the skill**.\n   - The routing suggestion MUST name the artifact item it would act on.\n   - Valid objects: \u0060PLAN Task N: <title>\u0060, \u0060TODO: <item>\u0060, \u0060DECISION N follow-up\u0060, \u0060OBJECTIVE: <metric>\u0060, or \u0060VISION refresh\u0060.\n   - A skill name without a concrete object is not a valid suggestion.\n\n    Priority order. SG codes are internal protocol references; never render them\n    in user-facing handoff labels:\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.md open items → select the highest-severity open item, then route by shape: narrow one-cycle TODOs suggest ⧉ build; contract-shaped, multi-surface, dependency-heavy, migration, schema, metadata, validation, or acceptance-risky TODOs suggest ≡ plan first. Prefer items that unlock product evidence or future plans.\n   - Pending DECISIONS.md 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\n   Do 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\n5. **Route**: present one concrete suggestion and let the user choose. No coercion.\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 Agentera/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\n---\n\n## Step 2: Route\n\nNarration voice: \"Kicking off [skill]...\" or similarly brief.\n\nInvoke the capability. Status's work is done.\n\nUnclear mapping? Ask **one** clarifying question. No compound questions.\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER execute implementation work. Status orients and routes; it does 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 is mandatory and uses status's canonical glyph \u0060⌂\u0060 (SG1, U+2302).\n\n- **complete** (EX1): Briefing delivered (or welcome shown) 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 is 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\nno artifact, and outputs only a briefing plus routing suggestion.\n"`);
-export default instructions;
-//# sourceMappingURL=instructions.js.map
+// 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, \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.`;

package/dist/capabilities/status/startupInstructions.js

@@ -0,0 +1,34 @@
+/**
+ * Status has one authoritative startup capsule: its instructions and bounded
+ * state arrive together from `prime --context status`. Keep the established
+ * status vocabulary by adapting the canonical instructions rather than
+ * maintaining a second dashboard description.
+ */
+export function statusStartupInstructions(canonical) {
+    const replacements = [
+        [
+            "Glyph: **⌂** (SG1). Status reads suite state through `agentera prime` and writes nothing.",
+            "Glyph: **⌂** (SG1). Status reads its startup capsule through `agentera prime --context status --format json` and writes nothing.",
+        ],
+        [
+            "Build the dashboard from `agentera prime --format json` output.",
+            "Build the dashboard from `capability_context.context.status_context` in the status startup response.",
+        ],
+        [
+            "Use the `mode` field from `agentera prime` to detect fresh vs returning:",
+            "Use the `mode` field from `capability_context.context.status_context` to detect fresh vs returning:",
+        ],
+        [
+            "- 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.",
+            "- TODO open items → use the `next_action` selected from complete typed readiness state. Recommend only an actionable item ordered by severity and declared `queue_rank`; preserve its TODO ID, declared reason, derived phase, and exact retrieval. Keep needs-triage visible without displacing actionable work. When none is actionable, abstain and show the supplied recovery. Never infer destination or order from description prose.",
+        ],
+    ];
+    let adapted = canonical;
+    for (const [from, to] of replacements) {
+        if (!adapted.includes(from)) {
+            throw new Error(`status startup instructions no longer contain the expected vocabulary: ${from.slice(0, 48)}`);
+        }
+        adapted = adapted.replace(from, to);
+    }
+    return adapted;
+}