agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/capabilities/vision/instructions.js

@@ -1,6 +1,4 @@
-// Source: skills/agentera/capabilities/vision/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 `"# VISION\n\n**Visionary Inception: Strategic Imagination, Observation Nexus. Envision, Refine, Anchor**\n\nThe strategic steward of the canonical vision artifact, stored as \u0060.agentera/vision.yaml\u0060 unless mapped otherwise. Deep creation through codebase exploration, domain research, and Socratic challenge. Ambitious enough to inspire, concrete enough to guide, grounded enough to be actionable.\n\nTwo modes: **create** (new projects) and **refine** (evolve existing visions).\n\n---\n\n## Visual identity\n\nGlyph: **⛥** (protocol ref: SG6). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne agent-facing file in \u0060.agentera/\u0060 by default.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060VISION.md\u0060 | Canonical vision artifact. North star, direction, principles, personas, aspirations. An evergreen constitution. | Created via deep brainstorm session, written to \u0060.agentera/vision.yaml\u0060 by default. |\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060vision\u0060 to locate the active installed schema; do not search Agentera directories manually. Existing vision artifacts provide repository-local examples of the shape. Vision adapts and expands them based on the conversation.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename (VISION.md, etc.). If \u0060.agentera/docs.yaml\u0060 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 \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060. This applies to all artifact references in this capability, including cross-capability reads (.agentera/decisions.yaml, .agentera/health.yaml, .agentera/progress.yaml, TODO.md).\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8, trend arrows VT12-VT13, progress bar VT18, inline separator VT16 (·), list item VT15 (▸), section divider VT14, flow/target VT17 (→). Skill glyph SG6 for the exit marker. Exit signals EX1-EX4 for the exit marker. Confidence scale CS1-CS5 for decision profile consumption.\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\n## vision.yaml shape\n\n\u0060\u0060\u0060yaml\nproject_name: Project Name\nnorth_star: The dream. Not what the software does, but what it makes possible.\npersonas:\n  - name: Persona name\n    description: Their day, frustrations, and workflow.\nprinciples:\n  - name: Principle name\n    description: What this principle optimizes for and what it resists.\ndirection: Where this project is heading. Aspirational, not prescriptive.\n\nEach principle MUST state a tradeoff direction (\"A over B when they conflict\"). Principles SHOULD name what each one actively prevents. Principles MUST NOT name specific libraries, modules, file paths, or implementation patterns — those belong in constraints or task scope. \"Tests over time-to-first-commit\" is a principle; \"use vitest\" is not.\nidentity:\n  personality: adjective · adjective · adjective\n  voice: How it communicates.\n  emotional_register: What it feels like to use.\n  naming: Convention or philosophy.\ntension: The hardest tension in the vision.\n\u0060\u0060\u0060\n\nVision must be ambitious enough for months of development, personas concrete enough for \"who is this for?\" debates, direction clear enough to derive next steps, and identity vivid enough to guide decisions from error messages to module names. If DESIGN.md exists, Identity should cohere with the visual system.\n\n---\n\n## Step 0: Detect mode\n\n**If the vision artifact does NOT exist**: Proceed to **Create** mode (Step 1).\n\n**If the vision artifact exists**: Present the mode choice.\n\nNarration voice (riff, don't script):\n\n- \"You've already got a vision. Sharpen it or start over?\" · \"Found your vision. Refine what's there, or fresh start?\"\n\nOffer:\n\n> **Refine**: Evolve the existing vision based on what you've learned. Reads the current vision, the codebase state, and recent progress to propose informed updates.\n>\n> **Replace**: Start fresh with a deep brainstorm. Archives the current vision and creates a new one from scratch.\n\nIf **Refine**, skip to Refine mode.\nIf **Replace**, archive the current vision artifact to \u0060.agentera/archive/vision-{date}.yaml\u0060, then proceed to Create mode.\n\n---\n\n## Create mode\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: explore, research, converse, audit, write.\n\n### Step 1: Explore the codebase\n\nIf code exists, read deeply before asking questions. You arrive informed.\n\n1. Map structure: directory layout, key modules, entry points\n2. Read dependency manifests: stack, libraries, what choices reveal\n3. Read README.md, CLAUDE.md, AGENTS.md if they exist\n4. Read key source files to understand what the software does today\n5. Read PROGRESS.md, TODO.md, DECISIONS.md for trajectory; use \u0060agentera decisions --format json\u0060 for normal decision context and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical decision context.\n6. Read HEALTH.md for current quality\n7. Read DESIGN.md for existing visual identity\n8. **Decision profile**: read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060) directly per protocol confidence scale (CS1-CS5) conventions. If missing, proceed without persona grounding.\n9. \u0060git log --oneline -30\u0060 for recent story\n\nSynthesize: \"The project does X, built with Y, moving toward Z. Strongest patterns: A. Gaps: B.\"\n\nGreenfield? Skip to Step 2.\n\n### Step 2: Research the domain\n\nSearch for context grounding the vision in reality:\n\n1. **What exists**: similar tools, competing approaches, adjacent projects\n2. **State of the art**: recent developments, emerging patterns\n3. **What's missing**: suite gaps this project could fill\n4. **Who talks about it**: communities, forums, common frustrations\n\n3-5 targeted searches. Synthesize: \"The gap is X. The opportunity is Y.\"\n\n### Step 3: The conversation\n\nEngage the user. Ask one question at a time through the runtime question tool\n(\u0060AskUserQuestion\u0060, always include \u0060Done\u0060 option).\n\n**Personality**: the sharp colleague, here to dream with you. Pushes past safe answers: \"That's good, but what if it was more?\"\n\nFollow a narrative arc, not a checklist. Adapt, but cover:\n\n1. **The dream**: \"Based on what I see in the codebase [and the domain research], here's where I think this wants to go: [synthesis]. But I bet you're thinking bigger than that. What does this project make possible if it wildly succeeds?\"\n\n   Push beyond utility: \"It does X faster, but why does that matter? What can they do that they couldn't before?\"\n\n2. **The people**: \"Who reaches for this? Not 'developers,' a specific person. Their Tuesday morning. The frustration that makes them think 'I need something better'?\"\n\n   Challenge abstract personas: \"'Data engineers': the one at a startup with 3 services, or the one at a bank with 3,000?\"\n\n3. **The principles**: \"What principles should guide every decision? What do you optimize for when you can't have everything? What do you actively resist?\"\n\n   If decision profile exists, propose principles from it: \"Your profile says you value X over Y. Should that be a principle here?\"\n\n4. **The direction**: \"Given all of that, where is this heading? Not features. Capabilities. What kind of tool does this become in a year? What would surprise you?\"\n\n5. **The identity**: \"If this product were a person, bold and direct, or quiet and precise? How does it talk? How should it feel to use? What emotion does a successful interaction leave?\" Also naming: \"Convention, cultural reference, philosophy?\"\n\n   If DESIGN.md exists: \"Your visual system says X. Does the verbal identity match?\"\n\n6. **The tension**: \"What's the hardest tension in this vision? Where do the principles conflict? What will you have to give up to get what matters most?\"\n\n   This question often produces the most useful material for the vision document.\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 (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 5: Write the vision artifact\n\nSynthesize into an aspirational north star. **Tone**: evocative, not clinical. A rallying cry, not a requirements doc. **Structure**: follow template but adapt; add dimensions that emerged, omit sections that produced nothing interesting.\n\nOutput constraint: ≤20 words per principle.\n\nPresent the draft to the user. Get explicit approval before writing.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n**Exit marker**: emit \u0060⛥ vision · <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 \u0060▸\u0060 (VT15) bullet below the summary identifying what needs resolution. The exit marker is mandatory on every invocation.\n\n---\n\n## Refine mode\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: read, research, propose, audit, update.\n\n### Step 1: Read the current state\n\n1. Read the current vision artifact\n2. Read the codebase (same depth as Create Step 1)\n3. Read PROGRESS.md for what's been built since the vision was created\n4. Use \u0060agentera decisions --format json\u0060 for what decisions have shifted thinking; carry compacted/missing-field caveats forward rather than reconstructing absent historical context.\n5. Read HEALTH.md for what structural realities constrain the vision\n6. Read TODO.md for what recurring problems suggest the vision needs adjustment\n\n### Step 2: Research updates\n\nSearch for domain developments since the vision was written: new tools, community shifts, things the user might not have seen.\n\n### Step 3: Propose changes\n\nPresent your assessment:\n\n> Here's what's changed since the vision was written:\n>\n> - The project has built [A, B, C] (from PROGRESS.md)\n> - Decision [X] shifted thinking about [Y] (from DECISIONS.md)\n> - The domain has moved: [Z] (from research)\n>\n> I'd suggest updating:\n>\n> - [Section]: [what to change and why]\n> - [Section]: [what to change and why]\n>\n> What resonates? What's off?\n\nBrief conversation (2-4 exchanges) to refine proposed changes.\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 (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 5: Update the vision artifact\n\nShow the updated vision as a diff (what changed and why). Get explicit approval before writing.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER write the vision artifact without explicit user approval. Present drafts and get confirmation.\n- NEVER modify the vision artifact during a build cycle. Vision changes happen in dedicated vision sessions only.\n- NEVER produce a clinical, requirements-style document. The vision should inspire, not specify. If it reads like a PRD, rewrite it.\n- NEVER skip the codebase exploration (Step 1) when code exists. Arriving informed is the whole point.\n- NEVER propose a vision so vague it can't guide autonomous development. \"Make a great tool\" is not a vision. \"Make it possible for a solo developer to ship production-grade systems by letting an AI team handle the parts they'd otherwise skip\" is.\n- NEVER dismiss the user's ambition. If they dream big, help them articulate it. If they think small, push them bigger. But never cap their aspiration.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060⛥ vision · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details below the summary.\n\n- **complete** (EX1): The vision artifact was written (Create/Replace mode) or updated (Refine mode) with explicit user approval; the vision is ambitious, concrete, and structured to sustain autonomous development.\n- **flagged** (EX2): The vision was produced but with weaknesses worth surfacing: the user settled for a less ambitious or less specific vision than the capability pushed for, key sections (personas, principles, direction) are thin due to limited conversation depth, or the vision has unresolved tensions with existing DECISIONS.md entries.\n- **stuck** (EX3): Cannot write the vision artifact because the user declined to approve the draft and no actionable revision direction was given, or codebase exploration failed in a way that would make the vision unreliable (e.g., inaccessible repo).\n- **waiting** (EX4): The user has not provided enough about the project's purpose or direction to write a meaningful vision, and the codebase (if any) does not provide sufficient signal to proceed without a conversation.\n\n---\n\n## Cross-capability integration\n\nVision is part of a twelve-capability suite. It is the strategic layer, the capability that defines where the project is going.\n\n### Vision produces what build consumes\n\nThe vision artifact is the north star that drives build's work selection every cycle. When vision is installed, build defers to it for vision creation and refinement. When vision is NOT installed, build falls back to its own quick brainstorm. Both paths produce the same \u0060.agentera/vision.yaml\u0060 shape by default; the capabilities are interchangeable at the artifact level.\n\n### Vision is informed by discuss\n\nDECISIONS.md entries provide context for vision refinement: what choices have been made and why. When vision detects that decisions have shifted thinking away from the current vision, it surfaces this during refine mode.\n\n### Vision is informed by profile\n\nThe decision profile calibrates the vision conversation: what patterns the user values, what principles they've established across projects, what they resist. High-confidence entries (CS1-CS2, 70+) become proposed principles in the vision.\n\n### Vision is informed by research\n\nWhen research analysis has shifted thinking about the project's direction, vision reads DECISIONS.md for these insights and incorporates them into vision refinement.\n\n### Vision is informed by audit\n\nHEALTH.md tells vision what structural realities constrain the vision. A project with D-grade architecture may need a vision adjustment, or the vision may confirm that the architecture needs to change.\n\n### Vision reads design output\n\nIf DESIGN.md exists, vision reads it during codebase exploration to understand the project's visual identity. The \u0060identity\u0060 section in the vision artifact should be coherent with the visual system declared in DESIGN.md. Vision reads DESIGN.md for context but never writes it; design owns all DESIGN.md writes.\n\n### Vision reads document output\n\nDOCS.md provides artifact path resolution for the canonical vision artifact. Document's documentation coverage tracking helps vision understand what documentation exists in the project.\n\n### Vision feeds plan\n\nWhen a new or refined vision changes the project's direction, plan can produce a plan to realign the codebase with the updated vision.\n\n---\n\n## Getting started\n\n### New project\n\n1. ⛥ vision: deep creation of the vision artifact through codebase exploration, domain research, and aspirational conversation\n2. ≡ plan: plan the first features (if complex)\n3. ⧉ build: start building\n\n### Existing project without a vision\n\n1. ⛥ vision: reads the codebase, understands what exists, then pushes the user to articulate where it should go\n\n### Vision refinement\n\n1. ⛥ vision: detects the existing vision artifact, offers refine mode, reads progress and decisions since last update, proposes informed changes\n\n### Without vision installed\n\nBuild's built-in quick brainstorm creates a workable vision artifact. Vision adds depth and stewardship but is not required for the suite to function.\n"`);
+// Capability instructions for vision (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context vision --format json`. RFC 2119 modal vocab per D71.
+export const instructions = JSON.parse(String.raw `"# VISION\n\n**Strategic Layer. Envision, Refine, Anchor**\n\nThe strategic steward of the canonical vision artifact, stored as \u0060.agentera/vision.yaml\u0060 unless mapped otherwise. Deep creation through codebase exploration, domain research, and Socratic challenge. Ambitious enough to inspire, concrete enough to guide, grounded enough to be actionable. Glyph: **⛥** (protocol ref: SG6), used in the mandatory exit marker.\n\nTwo modes: **create** (new projects) and **refine** (evolve existing visions).\n\nVision MUST source state from \u0060agentera prime --context vision --format json\u0060 and write only the vision artifact, archived-vision history under \u0060.agentera/archive/\u0060, and \u0060.agentera/docs.yaml\u0060 artifact-mapping updates if a new path override is required. Read \u0060capability_context.startup\u0060. Observe \u0060outcome\u0060; use bounded context already served for an \u0060included\u0060 availability row, and run a \u0060deferred\u0060 row\u0027s exact \u0060detail_command\u0060 before any raw artifact diagnostic. If startup is \u0060blocked\u0060, use \u0060detail_discovery.schema\u0060 to inspect recovery; do not raw-read \u0060.agentera/*.yaml\u0060.\n\n---\n\n## State artifacts\n\nOne agent-facing file in \u0060.agentera/\u0060 by default, plus a per-project archive directory.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060vision\u0060 | Canonical vision artifact. North star, direction, principles, personas, aspirations, identity, tension. An evergreen constitution. | Created via deep brainstorm session, written to \u0060.agentera/vision.yaml\u0060 by default. |\n| \u0060.agentera/archive/\u0060 | Completed Replace-mode predecessors, retained as corrective context. | Created on first Replace-mode archive; files named \u0060vision-{date}.yaml\u0060. |\n\nRead-needs (sourced via \u0060vision_startup_context\u0060 when complete): vision, decisions, progress, health, todo, design, docs, profile. Write-targets: vision only.\n\nUse \u0060agentera schema --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060vision\u0060 to locate the active installed schema; do not search Agentera directories manually. Existing vision artifacts provide repository-local examples of the shape. Vision adapts and expands them based on the conversation.\n\n### vision.yaml shape\n\n\u0060\u0060\u0060yaml\nproject_name: Project Name\nnorth_star: The dream. Not what the software does, but what it makes possible.\npersonas:\n  - name: Persona name\n    description: Their day, frustrations, and workflow.\nprinciples:\n  - name: Principle name\n    description: What this principle optimizes for and what it resists.\ndirection: Where this project is heading. Aspirational, not prescriptive.\nidentity:\n  personality: adjective · adjective · adjective\n  voice: How it communicates.\n  emotional_register: What it feels like to use.\n  naming: Convention or philosophy.\ntension: The hardest tension in the vision.\n\u0060\u0060\u0060\n\nEach principle MUST state a tradeoff direction (\"A over B when they conflict\"). Principles SHOULD name what each one actively prevents. Principles MUST NOT name specific libraries, modules, file paths, or implementation patterns — those belong in constraints or task scope. \"Tests over time-to-first-commit\" is a principle; \"use vitest\" is not.\n\nVision MUST be ambitious enough for months of development, personas concrete enough for \"who is this for?\" debates, direction clear enough to derive next steps, and identity vivid enough to guide decisions from error messages to module names. If DESIGN.md exists, the \u0060identity\u0060 section SHOULD cohere with the visual system declared there.\n\n---\n\n## Workflow phases (mode-split: Step 0 detect, then Create 1-5 or Refine 1-5; emit \u0060── step N/5: verb\u0060 before each step — verbs listed per mode below)\n\n### Step 0: Detect mode\n\nRun \u0060agentera state query vision --format json\u0060. If \u0060source.exists=false\u0060, proceed to **Create** mode. If \u0060source.exists=true\u0060, present the mode choice:\n\n> **Refine**: Evolve the existing vision based on what you've learned. Reads the current vision, the codebase state, and recent progress to propose informed updates.\n>\n> **Replace**: Start fresh with a deep brainstorm. Archives the current vision and creates a new one from scratch.\n\nIf **Refine**, skip to Refine mode. If **Replace**, archive the current vision artifact to \u0060.agentera/archive/vision-{date}.yaml\u0060, then proceed to Create mode (which will read the archive as corrective context in Step 1).\n\n### Pre-write self-audit (shared by Create Step 4 and Refine Step 4)\n\nBefore writing the vision artifact, run \u0060agentera check lint --artifact vision --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (≥1 concrete anchor per principle), and filler accumulation (banned patterns). Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing after 3 attempts.\n\n---\n\n### Create mode\n\nSteps: explore, research, converse, audit, write.\n\n#### Step 1: Explore the codebase\n\nIf code exists, read deeply before asking questions. You arrive informed.\n\n1. Source state from \u0060agentera prime --context vision --format json\u0060's \u0060vision_startup_context\u0060 body — progress (latest cycle), health (grade + trajectory), todo (open counts by severity), profile (path; if \u0060stale=true\u0060, carry the caveat forward; do NOT invoke profile to refresh state during a vision cycle — prime covers only reading).\n2. For \u0060decisions\u0060: when its \u0060capability_context.startup.availability\u0060 row is \u0060deferred\u0060, run that row\u0027s exact \u0060detail_command\u0060; preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure rather than raw-reading historical decision context.\n3. For \u0060vision\u0060 itself when in Replace mode: read \u0060.agentera/archive/vision-{date}.yaml\u0060 (the artifact just archived in Step 0) for context on what to avoid.\n4. Map project structure: directory layout, key modules, entry points.\n5. Read dependency manifests: stack, libraries, what choices reveal.\n6. Read \u0060README.md\u0060 and \u0060AGENTS.md\u0060 (v3 canonical project guidance) if they exist.\n7. Read key source files to understand what the software does today.\n8. Read \u0060DESIGN.md\u0060 (project root) if it exists, for existing visual identity. The \u0060design\u0060 artifact family is \u0060deferred\u0060 in \u0060capability_context.startup.availability\u0060; use its exact \u0060detail_command\u0060 before a filesystem diagnostic.\n9. \u0060git log --oneline -30\u0060 for the recent story.\n\nSynthesize: \"The project does X, built with Y, moving toward Z. Strongest patterns: A. Gaps: B.\"\n\nGreenfield (no code exists)? Skip to Step 2.\n\n#### Step 2: Research the domain\n\nSearch for context grounding the vision in reality:\n\n1. **What exists**: similar tools, competing approaches, adjacent projects\n2. **State of the art**: recent developments, emerging patterns\n3. **What's missing**: suite gaps this project could fill\n4. **Who talks about it**: communities, forums, common frustrations\n\n3-5 targeted searches. Synthesize: \"The gap is X. The opportunity is Y.\"\n\n#### Step 3: The conversation\n\nEngage the user. Ask one question at a time through the native question tool (always include a \u0060Done\u0060 option). Adopt the conversational voice defined in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, run with a neutral operational stance; personality emerges from arc 5 below and is captured in the artifact.\n\nOperational stance: Socratic. Push past safe answers. Vision's job is to surface an inarticulate dream through challenge, not interview the user through a checklist.\n\nFollow a narrative arc, not a checklist. Adapt, but cover:\n\n1. **The dream**: \"Based on what I see in the codebase [and the domain research], here's where I think this wants to go: [synthesis]. But I bet you're thinking bigger than that. What does this project make possible if it wildly succeeds?\" Push beyond utility: \"It does X faster, but why does that matter? What can they do that they couldn't before?\"\n\n2. **The people**: \"Who reaches for this? Not 'developers,' a specific person. Their Tuesday morning. The frustration that makes them think 'I need something better'?\" Challenge abstract personas: \"'Data engineers': the one at a startup with 3 services, or the one at a bank with 3,000?\"\n\n3. **The principles**: \"What principles should guide every decision? What do you optimize for when you can't have everything? What do you actively resist?\" If decision profile exists, propose principles from it: \"Your profile says you value X over Y. Should that be a principle here?\"\n\n4. **The direction**: \"Given all of that, where is this heading? Not features. Capabilities. What kind of tool does this become in a year? What would surprise you?\" Also ask what it should NOT become: \"In five years you give up and move to a competitor — what killed it? Name that trait and exclude it here.\" Fold the answer into \u0060direction\u0060 as a scope boundary.\n\n5. **The identity**: \"If this product were a person, bold and direct, or quiet and precise? How does it talk? How should it feel to use? What emotion does a successful interaction leave?\" Also naming: \"Convention, cultural reference, philosophy?\" If DESIGN.md exists: \"Your visual system says X. Does the verbal identity match?\"\n\n6. **The tension**: \"What's the hardest tension in this vision? Where do the principles conflict? What will you have to give up to get what matters most?\"\n\n#### Step 4: Pre-write self-audit\n\nExercise the shared pre-write self-audit rule (declared above under Workflow phases).\n\n#### Step 5: Write the vision artifact\n\nSynthesize into an aspirational north star. **Tone**: evocative, not clinical. A rallying cry, not a requirements doc. **Structure**: follow template but adapt; add dimensions that emerged, omit sections that produced nothing interesting.\n\nPresent the draft to the user.\n\n\n---\n\n### Refine mode\n\nSteps: read, research, propose, audit, update.\n\n#### Step 1: Read the current state\n\n1. Run \u0060agentera state query vision --format json\u0060 for the current vision artifact's content and \u0060source.path\u0060.\n2. Source state from \u0060agentera prime --context vision --format json\u0060's \u0060vision_startup_context\u0060 body — progress, health, todo, profile (with same stale-case handling as Create Step 1).\n3. For decisions: when its \u0060capability_context.startup.availability\u0060 row is \u0060deferred\u0060, run that row\u0027s exact \u0060detail_command\u0060; carry \u0060compacted\u0060 / \u0060missing_fields\u0060 / \u0060caveats\u0060 / \u0060satisfaction.review_needed\u0060 pressure forward rather than reconstructing absent historical context.\n4. Read the codebase (same depth as Create Step 1 — rows 4–9: structure, manifests, README/AGENTS, source files, DESIGN.md if present, git log).\n5. Review the todo slice for recurring problems that suggest the vision needs adjustment.\n\n#### Step 2: Research updates\n\nSearch for domain developments since the vision was written: new tools, community shifts, things the user might not have seen.\n\n#### Step 3: Propose changes\n\nPresent your assessment:\n\n> Here's what's changed since the vision was written:\n>\n> - The project has built [A, B, C] (from progress state)\n> - Decision [X] shifted thinking about [Y] (from decisions state)\n> - The domain has moved: [Z] (from research)\n> - Recurring TODO items suggest: [W] (from todo state)\n>\n> I'd suggest updating:\n>\n> - [Section]: [what to change and why]\n>\n> What resonates? What's off?\n\nBrief conversation (2–4 exchanges) to refine proposed changes.\n\n#### Step 4: Pre-write self-audit\n\nExercise the shared pre-write self-audit rule (declared above under Workflow phases).\n\n#### Step 5: Update the vision artifact\n\nShow the updated vision as a diff (what changed and why).\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT write the vision artifact without explicit user approval. Present drafts and get confirmation.\n- MUST NOT modify the vision artifact during a build cycle; changes belong in dedicated vision sessions.\n- MUST NOT produce a clinical, requirements-style document. The vision SHOULD inspire, not specify. If it reads like a PRD, rewrite it.\n- MUST NOT skip the codebase exploration (Step 1) when code exists.\n- MUST NOT propose a vision so vague it cannot guide autonomous development. \"Make a great tool\" is not a vision. \"Make it possible for a solo developer to ship production-grade systems by letting an AI team handle the parts they'd otherwise skip\" is.\n- MUST NOT dismiss the user's ambition. If they dream big, help them articulate it. If they think small, push them bigger. Never cap aspiration.\n- MUST NOT invoke profile to refresh PROFILE.md during a vision cycle. Profile state is read-only context for vision; refreshing mutates state outside vision's contract.\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⛥ vision · <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 \u0060▸\u0060 (VT15) bullet below the summary identifying what needs resolution. The exit marker is mandatory on every invocation.\n\n- **complete** (EX1): The vision artifact was written (Create/Replace mode) or updated (Refine mode) with explicit user approval; the vision is ambitious, concrete, and structured to sustain autonomous development.\n- **flagged** (EX2): The vision was produced but with weaknesses worth surfacing: the user settled for a less ambitious or less specific vision than the capability pushed for, key sections (personas, principles, direction) are thin due to limited conversation depth, or the vision has unresolved tensions with existing decision entries.\n- **stuck** (EX3): Cannot write the vision artifact because the user declined to approve the draft and no actionable revision direction was given, or codebase exploration failed in a way that would make the vision unreliable (e.g., inaccessible repo).\n- **waiting** (EX4): The user has not provided enough about the project's purpose or direction to write a meaningful vision, and the codebase (if any) does not provide sufficient signal to proceed without a conversation.\n\n---\n\n## Cross-capability integration\n\nVision is the strategic layer — the capability that defines where the project is going within the twelve-capability suite.\n\n### Vision produces what build consumes\n\nThe vision artifact drives build's work selection every cycle. When vision is installed, build defers to it; otherwise build runs its own quick brainstorm. Both produce the same \u0060.agentera/vision.yaml\u0060 shape — the capabilities are interchangeable at the artifact level.\n\n### Vision is informed by discuss\n\nDecision entries provide context for vision refinement: what choices have been made and why. When vision detects that decisions have shifted thinking away from the current vision, it surfaces this during refine mode.\n\n### Vision is informed by profile\n\nThe decision profile calibrates the vision conversation: what patterns the user values, what principles they've established across projects, what they resist. High-confidence entries (CS1-CS2, 70+) become proposed principles in the vision.\n\n### Vision is informed by research\n\nResearch that shifts the project's direction lands in the decisions artifact; vision picks up the captured insight during refine mode.\n\n### Vision is informed by audit\n\nThe health artifact tells vision what structural realities constrain the vision. A project with D-grade architecture may need a vision adjustment, or the vision may confirm that the architecture needs to change.\n\n### Vision reads design output\n\nVision reads DESIGN.md (in Create Step 1) for the project's visual identity. The \u0060identity\u0060 section SHOULD cohere with this visual system. Vision never writes DESIGN.md; design owns all writes.\n\n### Vision reads document output\n\nDOCS.md provides artifact path resolution for the canonical vision artifact and signals what documentation exists in the project.\n\n### Vision feeds plan\n\nWhen a new or refined vision changes the project's direction, plan can produce a plan to realign the codebase with the updated vision.\n\n### Invocation guidance (consumer perspective)\n\n**New project**: invoke ⛥ vision for deep creation of the vision artifact through codebase exploration, domain research, and aspirational conversation. Then ≡ plan to plan the first features (if complex), then ⧉ build to start building.\n\n**Existing project without a vision**: invoke ⛥ vision to read the codebase, understand what exists, then push the user to articulate where it should go.\n\n**Vision refinement**: invoke ⛥ vision to detect the existing vision artifact, offer refine mode, read progress and decisions since last update, propose informed changes.\n\n**Without vision installed**: build's built-in quick brainstorm creates a workable vision artifact. Vision adds depth and stewardship but is not required for the suite to function.\n"`);
 export default instructions;
-//# sourceMappingURL=instructions.js.map

package/dist/cli/appContext.js

@@ -76,6 +76,19 @@ export function modelPath(model, key) {
 export function discoverSchemasDir(model = activeAppModel()) {
     return path.join(modelPath(model, "skillRoot"), "schemas", "artifacts");
 }
+/**
+ * Resolve the artifact-registry model backing a discovered schemas directory.
+ * Prefers a co-located model beside the skills root (so checkout/bundle/managed
+ * apps each load their own model); falls back to the production default when no
+ * co-located model is present.
+ */
+export function resolveRegistryModelPath(schemasDir) {
+    const root = path.resolve(schemasDir, "..", "..", "..", "..");
+    const candidate = path.join(root, "references", "artifacts", "artifact-registry-interface-model.yaml");
+    if (isFileSafe(candidate))
+        return candidate;
+    return registryModelPath();
+}
 const FIELD_SKIP = new Set([
     "meta",
     "GROUP_PREFIXES",
@@ -101,13 +114,8 @@ export function discoverFields(schema) {
     return fields;
 }
 export function loadRegistryForSchemas(schemasDir) {
-    const root = path.resolve(schemasDir, "..", "..", "..", "..");
-    let modelPathArg = path.join(root, "references", "artifacts", "artifact-registry-interface-model.yaml");
-    if (!isFileSafe(modelPathArg)) {
-        modelPathArg = registryModelPath();
-    }
     try {
-        return loadArtifactRegistry(schemasDir, modelPathArg);
+        return loadArtifactRegistry(schemasDir, resolveRegistryModelPath(schemasDir));
     }
     catch (exc) {
         process.stderr.write(`warning: failed to load artifact registry for schemas: ${exc.message}\n`);
@@ -222,4 +230,3 @@ export function artifactPath(info, schemaName) {
     const record = info.record;
     return resolveArtifactPathLocal(info.path, schemaName, record ?? null);
 }
-//# sourceMappingURL=appContext.js.map

package/dist/cli/argvalidate.js

@@ -38,4 +38,3 @@ export function pathStem(p) {
         return base;
     return base.slice(0, dot);
 }
-//# sourceMappingURL=argvalidate.js.map

package/dist/cli/capabilityContext/benchmark.js

@@ -4,7 +4,9 @@ import os from "node:os";
 import { resolveProfileDirOverride, resolveXdgDataHome } from "../../core/envPaths.js";
 import { expanduser } from "../../core/paths.js";
 import { sourceProvenance, uniqueList } from "./shared.js";
-export const BENCHMARK_CONTEXT_CMD = "agentera prime --context optimize --format json";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "./types.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+export const BENCHMARK_CONTEXT_CMD = preCutoverCommand("prime --context optimize --format json");
 export const BENCHMARK_LATEST_REPORT_LABEL = "startup_benchmark_latest_report";
 export const BENCHMARK_HISTORY_LABEL = "startup_benchmark_history";
 export const BENCHMARK_CONTEXT_SOURCE_LABELS = [BENCHMARK_LATEST_REPORT_LABEL, BENCHMARK_HISTORY_LABEL];
@@ -503,7 +505,7 @@ export function optimizeBenchmarkContext(capability) {
         ...(recommendation.caveats ?? []),
         ...(manualRefresh.caveats ?? []),
     ]);
-    const fallbackCommands = ["agentera state docs --format json", "agentera state query --list-artifacts --format json"];
+    const fallbackCommands = [STATE_FAMILY_FALLBACK_COMMANDS.docs, preCutoverCommand("state query --list-artifacts --format json")];
     return {
         capability: "optimize",
         benchmark_source: {
@@ -529,7 +531,7 @@ export function optimizeBenchmarkContext(capability) {
             complete_for_benchmark_context: complete,
             caveated: caveats.length > 0,
             raw_artifact_reads_required: false,
-            raw_artifact_read_policy: "Use this benchmark_context from `agentera prime --context optimize --format json` first. " +
+            raw_artifact_read_policy: `Use this benchmark_context from \`${preCutoverCommand("prime --context optimize --format json")}\` first. ` +
                 "If incomplete, follow fallback_commands and manual_refresh before any last-resort direct latest-report.json, " +
                 "latest-report.md, or runs.jsonl diagnostic read.",
             benchmark_state_families: [
@@ -561,4 +563,3 @@ export function optimizeBenchmarkContext(capability) {
         },
     };
 }
-//# sourceMappingURL=benchmark.js.map

package/dist/cli/capabilityContext/bespoke.js

@@ -3,7 +3,7 @@ import { documentCloseoutContext } from "./closeout.js";
 import { auditEvidenceContext } from "./evidence.js";
 import { optimizeBenchmarkContext } from "./benchmark.js";
 import { buildExecutionContext } from "./build.js";
-import { slimOrchestrationContext, slimEvidenceContext, slimCloseoutContext } from "./slim.js";
+import { slimOrchestrationContext, slimEvidenceContext, slimCloseoutContext, slimBenchmarkContext } from "./slim.js";
 export function slimBespokeContext(name, value) {
     if (name === "orchestration_context")
         return slimOrchestrationContext(value);
@@ -11,9 +11,11 @@ export function slimBespokeContext(name, value) {
         return slimEvidenceContext(value);
     if (name === "closeout_context")
         return slimCloseoutContext(value);
+    if (name === "benchmark_context")
+        return slimBenchmarkContext(value);
     return value;
 }
-export function bespokeCapabilityContexts(capabilityName, state) {
+export function bespokeCapabilityContexts(capabilityName, state, buildRequest = null) {
     // cast: orientation state fields are assembled from parsed .agentera artifacts;
     // bespoke builders consume JsonObject/typed shapes for these state families.
     const plan = state.plan;
@@ -25,12 +27,18 @@ export function bespokeCapabilityContexts(capabilityName, state) {
     const bundle = state.app;
     const todoItems = state.todo_items;
     const schemas = state.schemas;
+    const projectRoot = String(state.project_root);
+    const history = state.history && typeof state.history === "object" && !Array.isArray(state.history)
+        ? state.history
+        : {};
+    const decisionHistory = history.decisions && typeof history.decisions === "object" && !Array.isArray(history.decisions)
+        ? history.decisions
+        : {};
     return {
         orchestration_context: orchestrationContext(capabilityName, plan, progress, health, todoItems, docs, profile, nextAction),
-        closeout_context: documentCloseoutContext(capabilityName, schemas, plan, progress, todoItems, docs, profile, bundle),
-        evidence_context: auditEvidenceContext(capabilityName, schemas, plan, progress, health, todoItems, docs, profile, bundle),
+        closeout_context: documentCloseoutContext(capabilityName, schemas, plan, progress, todoItems, docs, profile, bundle, decisionHistory, projectRoot),
+        evidence_context: auditEvidenceContext(capabilityName, schemas, plan, progress, health, todoItems, docs, profile, bundle, decisionHistory),
         benchmark_context: optimizeBenchmarkContext(capabilityName),
-        execution_context: buildExecutionContext(capabilityName, schemas, plan, progress, health, todoItems, docs, profile, bundle),
+        execution_context: buildExecutionContext(capabilityName, schemas, plan, progress, health, todoItems, docs, profile, bundle, projectRoot, buildRequest),
     };
 }
-//# sourceMappingURL=bespoke.js.map

package/dist/cli/capabilityContext/build.js

@@ -3,20 +3,47 @@ import { capabilityContext } from "./contract.js";
 import { sourceProvenance, uniqueList, hasRecordedValue, taskRef } from "./shared.js";
 import { closeoutChangelogBoundary, orchestrationTaskSummary, planContextField, buildArtifactUpdateRequirements, buildPlanCompletionSweep, buildScopeBoundary, selectEvidenceTarget, taskByRef, } from "./planState.js";
 import { progressVerificationSummary } from "./progress.js";
-export function buildExecutionContext(capability, schemas, plan, progress, health, todoItems, docs, profile, bundle) {
+import { STATE_FAMILY_FALLBACK_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "./types.js";
+import { planLifecycleState } from "../planLifecycleState.js";
+import { discoverProjectVerification } from "./projectVerification.js";
+import { deferredStartupFamilies } from "./startupAggregation.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+import { progressWritePolicy } from "../../state/progressWritePolicy.js";
+const TRANSIENT_BUILD_INPUT_COMMAND = preCutoverCommand("prime --context build --input <file|-> --format json");
+const TRANSIENT_BUILD_STDIN_COMMAND = preCutoverCommand("prime --context build --input - --format json");
+function transientSourceProvenance(request, field) {
+    return {
+        source_family: "transient_build_execution_request",
+        command: TRANSIENT_BUILD_INPUT_COMMAND,
+        field,
+        schema_version: request.schema_version,
+        source_kind: request.source.kind,
+        persisted: false,
+    };
+}
+export function buildExecutionContext(capability, schemas, plan, progress, health, todoItems, docs, profile, bundle, projectRoot, buildRequest = null) {
     if (capability !== "build")
         return null;
     const capabilityContract = capabilityContext(capability) ?? {};
-    const tasks = asList(plan.tasks).filter((t) => t && typeof t === "object" && !Array.isArray(t));
+    const lifecycle = planLifecycleState(plan);
+    const tasks = lifecycle.current_plan_degraded === true
+        ? []
+        : asList(plan.tasks).filter((t) => t && typeof t === "object" && !Array.isArray(t));
     const target = selectEvidenceTarget(plan);
     const selected = taskByRef(plan, (target && typeof target === "object" ? target.task : null));
-    const acceptance = selected && typeof selected === "object" ? asList(selected.acceptance) : [];
+    const acceptance = buildRequest?.acceptance
+        ?? (selected && typeof selected === "object" ? asList(selected.acceptance) : []);
     const progressVerification = progressVerificationSummary(progress);
-    const changelogBoundary = closeoutChangelogBoundary(schemas, plan);
+    const changelogBoundary = closeoutChangelogBoundary(projectRoot, plan);
     const sweep = buildPlanCompletionSweep(plan);
+    const archiveOnly = Boolean(plan.exists) && plan.active === false;
     let mode;
-    if (plan.complete_plan)
+    if (plan.active === true && plan.complete_plan)
         mode = "completed_plan_sweep";
+    else if (buildRequest !== null && plan.active !== true)
+        mode = "no_plan";
+    else if (archiveOnly)
+        mode = "archive_only_history";
     else if (!plan.exists || tasks.length === 0)
         mode = "no_plan";
     else if (target.status === "selected" && selected !== null)
@@ -25,43 +52,42 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
         mode = "blocked_or_dependency_unready";
     let stateCaveats = [];
     let fallbackCommands = [];
-    for (const family of (capabilityContract.missing_state_families ?? [])) {
-        stateCaveats.push(`${family} state is not included in prime --context startup context.`);
+    for (const family of deferredStartupFamilies(capabilityContract)) {
+        stateCaveats.push(`${family} detail is deferred from prime --context startup.`);
     }
-    fallbackCommands.push(...(capabilityContract.cli_fallback ?? []));
-    if (!plan.exists) {
-        stateCaveats.push("plan state is unavailable; execution context cannot select plan-driven work.");
-        fallbackCommands.push("agentera state plan --format json");
+    if (lifecycle.status === "degraded") {
+        stateCaveats.push(...(lifecycle.caveats ?? []));
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
     }
     if (mode === "blocked_or_dependency_unready") {
         stateCaveats.push("No dependency-ready pending plan task is available in CLI plan state.");
-        fallbackCommands.push("agentera state plan --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
     }
     if (mode === "plan_driven" && acceptance.length === 0) {
         stateCaveats.push("Selected Build task has no acceptance criteria in CLI plan state.");
-        fallbackCommands.push("agentera state plan --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
     }
     if (!progress.exists) {
         stateCaveats.push("progress state is unavailable; progress logging context is incomplete.");
-        fallbackCommands.push("agentera state progress --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.progress);
     }
     if (!health.exists) {
         stateCaveats.push("health state is unavailable or incomplete.");
-        fallbackCommands.push("agentera state health --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.health);
     }
     if (!docs.exists) {
         stateCaveats.push("docs mapping state is unavailable or incomplete.");
-        fallbackCommands.push("agentera state docs --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.docs);
     }
     if (todoItems.length === 0) {
         stateCaveats.push("todo state has no open entries in prime --context response; absence may mean none open or unavailable.");
-        fallbackCommands.push("agentera state todo --format json");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.todo);
     }
     if (changelogBoundary.status !== "available") {
         stateCaveats.push(...(changelogBoundary.caveats ?? []));
-        fallbackCommands.push("agentera state query changelog --format json");
+        fallbackCommands.push(preCutoverCommand("state query changelog --format json"));
     }
-    if (profile.status !== "loaded") {
+    if (profile.status !== "valid") {
         stateCaveats.push("profile-derived state is unavailable in prime --context response.");
     }
     else if (profile.stale === true) {
@@ -70,48 +96,94 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
     if (bundle.status !== "up_to_date") {
         stateCaveats.push("Agentera app files are not up to date; this is a caveat, not approval to repair or update app files.");
     }
-    const scopeBoundary = buildScopeBoundary(plan, selected);
+    const scopeBoundary = buildRequest === null
+        ? buildScopeBoundary(plan, selected)
+        : {
+            artifact_families: ["progress", "todo", "docs", "health", "changelog", "decisions", "vision", "profile", "design"],
+            explicit_scope: buildRequest.scope,
+            source_scope: {
+                status: "unspecified",
+                explicit_paths: [],
+                policy: "The transient scope defines work intent only; no source-file allowlist or exclusion is inferred from its text.",
+            },
+            source_provenance: transientSourceProvenance(buildRequest, "scope"),
+        };
     const sourceScope = scopeBoundary.source_scope && typeof scopeBoundary.source_scope === "object" && !Array.isArray(scopeBoundary.source_scope)
         ? scopeBoundary.source_scope
         : {};
     if (sourceScope.status === "unspecified") {
         stateCaveats.push("source-file scope is unspecified; no allowed or prohibited source paths were inferred.");
     }
+    const noCurrentPlan = plan.active !== true && lifecycle.status !== "degraded";
+    if (noCurrentPlan) {
+        fallbackCommands = fallbackCommands.filter((command) => command !== STATE_FAMILY_FALLBACK_COMMANDS.plan);
+        if (buildRequest === null) {
+            stateCaveats.push("Explicit no-plan scope and acceptance are required before Build can execute without a current plan.");
+            fallbackCommands.push(TRANSIENT_BUILD_STDIN_COMMAND);
+        }
+    }
     fallbackCommands = uniqueList(fallbackCommands);
     stateCaveats = uniqueList(stateCaveats);
     const requiredState = {
-        work_selection: mode === "plan_driven" || mode === "completed_plan_sweep",
+        work_selection: mode === "plan_driven" || mode === "completed_plan_sweep" || buildRequest !== null,
         acceptance_criteria: mode === "completed_plan_sweep" || acceptance.length > 0,
         artifact_update_requirements: Boolean(docs.exists),
         progress_logging_requirements: progressVerification.status === "available" || (progressVerification.caveats ?? []).length > 0,
         changelog_boundary: changelogBoundary.status === "available",
         scope_boundary: true,
         safety_boundaries: true,
+        plan_state_healthy: lifecycle.status !== "degraded",
     };
     const missingRequired = Object.entries(requiredState).filter(([, present]) => !present).map(([name]) => name);
     const caveated = stateCaveats.length > 0;
-    const complete = (mode === "plan_driven" || mode === "completed_plan_sweep") && missingRequired.length === 0;
-    return {
-        capability: "build",
-        mode,
-        work_selection: {
+    const complete = (mode === "plan_driven" || mode === "completed_plan_sweep" || buildRequest !== null)
+        && missingRequired.length === 0;
+    const workSelection = buildRequest === null
+        ? {
             status: target.status,
             selection_reason: target.selection_reason,
             task: selected && typeof selected === "object" ? taskRef(selected) : null,
             source_provenance: target.source_provenance,
             caveats: target.caveats ?? [],
-        },
+        }
+        : {
+            status: "selected",
+            selection_reason: "explicit_no_plan_scope",
+            task: null,
+            scope: buildRequest.scope,
+            source_provenance: transientSourceProvenance(buildRequest, "scope"),
+            caveats: [],
+        };
+    const artifactUpdateRequirements = buildArtifactUpdateRequirements(plan, docs);
+    if (buildRequest !== null) {
+        artifactUpdateRequirements.required_families = ["todo", "changelog"];
+        artifactUpdateRequirements.conditional_families = ["progress"];
+        artifactUpdateRequirements.plan_status_update_required = false;
+        artifactUpdateRequirements.policy = "Transient no-plan work does not create, mutate, or require plan state.";
+    }
+    const progressRequirement = archiveOnly
+        ? "none"
+        : mode === "completed_plan_sweep"
+            ? "required"
+            : "conditional";
+    return {
+        capability: "build",
+        mode,
+        work_selection: workSelection,
         plan_task: selected && typeof selected === "object" ? orchestrationTaskSummary(selected) : null,
         acceptance_criteria: {
             status: acceptance.length > 0 ? "available" : "incomplete",
             items: acceptance,
             count: acceptance.length,
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.acceptance"),
+            source_provenance: buildRequest === null
+                ? sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries.acceptance")
+                : transientSourceProvenance(buildRequest, "acceptance"),
         },
         constraints: {
-            plan_constraints_present: hasRecordedValue(planContextField(plan, "constraints")),
-            plan_constraints_summary: "Plan constraints are represented here as structured safety and fallback policy; " +
-                "run the plan CLI fallback only if full wording is needed.",
+            plan_constraints_present: buildRequest === null && hasRecordedValue(planContextField(plan, "constraints")),
+            plan_constraints_summary: buildRequest === null
+                ? "Plan constraints are represented here as structured safety and fallback policy; run the plan CLI fallback only if full wording is needed."
+                : "Transient no-plan input supplies scope and acceptance only; no plan constraints are inferred.",
             protected_actions: [
                 "no profile refresh",
                 "no installed app refresh",
@@ -121,29 +193,33 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
                 "no commit/push/tag/publication without explicit approval",
             ],
             unsupported_cli_command_policy: "Do not introduce capability-name or slash-alias CLI commands for Build.",
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "summary.constraints"),
+            source_provenance: buildRequest === null
+                ? sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "summary.constraints")
+                : transientSourceProvenance(buildRequest, "scope"),
         },
         scope_boundary: scopeBoundary,
         verification_expectations: {
             latest_progress_verification: progressVerification,
-            expected_commands: ["focused pytest targets", "Build capability validation", "self-validation", "agentera gate", "compaction check", "git diff --check"],
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.acceptance"),
+            ...discoverProjectVerification(projectRoot),
         },
-        artifact_update_requirements: buildArtifactUpdateRequirements(plan, docs),
+        artifact_update_requirements: artifactUpdateRequirements,
         progress_logging_requirements: {
-            append_cycle: true,
-            verified_field_mandatory: true,
+            requirement: progressRequirement,
+            verified_field_mandatory_when_appended: true,
+            policy: progressWritePolicy(),
+            guidance_command: preCutoverCommand("state progress explain --verb append --format json"),
             latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
-            source_provenance: sourceProvenance("progress", "agentera progress --format json"),
+            source_provenance: sourceProvenance("progress", STATE_FAMILY_LIST_COMMANDS.progress),
         },
         changelog_boundary: changelogBoundary,
         git_boundary: {
             remote_push_allowed: false,
             commit_allowed_only_with_explicit_user_request: true,
             tag_or_publication_allowed: false,
-            source_provenance: sourceProvenance("execution_context", "agentera prime --context build --format json", "git_boundary"),
+            source_provenance: sourceProvenance("execution_context", preCutoverCommand("prime --context build --format json"), "git_boundary"),
         },
         plan_completion_sweep: sweep,
+        plan_lifecycle_state: lifecycle,
         state_family_caveats: stateCaveats,
         fallback_commands: fallbackCommands,
         source_contract: {
@@ -152,8 +228,6 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
             raw_artifact_reads_required: false,
             raw_artifact_read_policy: "Use this execution_context and included status state first. Run listed routine/query CLI fallback commands " +
                 "for missing or incomplete execution state; raw artifact reads are last-resort diagnostics, not normal Build startup behavior.",
-            included_state_families: capabilityContract.included_state_families ?? [],
-            missing_state_families: capabilityContract.missing_state_families ?? [],
             required_execution_state: requiredState,
             missing_required_execution_state: missingRequired,
             fallback_commands: fallbackCommands,
@@ -169,9 +243,9 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
                 "scope boundary",
                 "read-only plan completion sweep metadata",
                 "truthful completeness metadata",
+                "plan lifecycle state",
             ],
             deferred: [],
         },
     };
 }
-//# sourceMappingURL=build.js.map