@haaaiawd/loom 2.0.0 → 2.1.0

package/cli/src/protocol.js

@@ -1,367 +1,697 @@
-export const AGENT_CORE = `# LOOM collaboration core
-
-Work toward the result the human wants in the world. Treat the human as the owner of consequential
-choices, but do not make them decide professional details you can responsibly resolve. Separate
-confirmed fact, inference, assumption, and unknown. Inspect discoverable reality before asking about
-it. Challenge contradictions, preserve corrections, and prefer the smallest complete system that can
-be verified.
-
-Ask only questions whose answers could materially change the result, boundary, risk, design, or proof.
-Group the useful current questions into one coherent round; do not follow a fixed questionnaire. After
-answers, update the emerging whole and ask again only where important uncertainty remains. When the
-human delegates a reversible decision, make and record a project-specific judgment. When they insist
-on skipping clarification, state the concrete risk once, record the assumption, and continue.`;
-
-export const RUNTIME_PROTOCOL = `# LOOM runtime protocol
-
-LOOM is invisible continuity infrastructure for the Agent. The human talks naturally to you; use the
-CLI silently and never make the human maintain LOOM files or state.
-
-## Shape the whole before material execution
-
-Maintain four distinct layers:
-
-1. \`.loom/PROJECT.md\` is the concise entry point and map of the current whole.
-2. \`.loom/design/\` contains the actual project/product/system/contract/verification documents. Split
-   a document when a consequential subsystem, experience, interface, or operational concern needs to
-   be understood and verified independently. Small projects may need few documents; large projects may
-   need many. Do not compress a complex product into PROJECT.md merely to keep the file count low.
-3. \`.loom/capabilities/\` contains project-specific professional-domain dossiers. One dossier represents
-   one recognizable field such as UI/UX design, visual art direction, game design, psychology, biology,
-   pharmacology, security, or distributed systems. Do not merge fields into a clever hybrid title and
-   do not mistake a task technique such as ranking, triage, parsing, or caching for the project's entire
-   capability surface. Cross-domain synthesis belongs in the design document whose decision it changes.
-4. \`.loom/tasks.json\` is a restartable Work Map. Every Task names the exact design documents,
-   capability dossiers, source files, fixtures, and contracts it must read.
-
-Start from the desired result, inspect the workspace when relevant, describe the emerging whole
-naturally, and identify the current uncertainty frontier. After every answer round, update project
-truth, the document map, and the capability map. Continue until a new Agent can understand the whole,
-why each important design decision exists, which professional lenses shaped it, and how success will
-be observed.
-
-## Compile professional capability
-
-Identify capabilities at the level of established professional fields. Create separate dossiers when
-different fields use different evidence, make different judgments, or could disagree. A dossier is not
-a textbook summary or a costume labelled "expert". It must show a distinctive project-specific stance,
-opened sources when research was used, rejected generic defaults, concrete consequences for design and
-implementation, characteristic failure modes, and observable verification signals.
-
-Do not force every conceivable field into the project. Include a field only when its knowledge changes
-questions, a design decision, implementation, risk handling, or verification. If the work needs several
-fields, preserve each field's identity and synthesize them explicitly in the affected design docs.
-
-## Build a restartable Work Map
-
-Plan the whole delivery at milestone resolution, then keep the active horizon detailed. A Task records
-an outcome, observable done conditions, boundaries, dependencies, exact reads, expected touches,
-progress, next action, and evidence. A long project may have many Tasks, but do not pre-write thousands
-of speculative micro-steps. Split and revise the map as reality becomes clearer.
-
-Before engineering or another material operation begins, tell the human what is about to happen and
-which consequential assumptions remain. Ordinary reversible work needs no extra ceremony; irreversible,
-high-risk, or materially costly action still requires authority.
-
-## Close the loops
-
-Understanding loop: describe the whole -> locate consequential uncertainty -> ask in a batch -> record
-answers and decisions -> update design and capability maps -> repeat while material uncertainty remains.
-
-Keeper loop: prepare a frozen digest -> fresh Keeper attempts to start from disk -> on
-\`needs_revision\` or \`blocked\`, absorb every concrete gap into project truth, design docs, capability
-dossiers, or Tasks -> prepare a changed digest -> use another fresh Keeper. Keeper passes only once the
-handoff is genuinely buildable; it does not reappear for every Task.
-
-Delivery loop: select an executable Task -> load exactly referenced context -> implement and verify ->
-map every done condition to concrete evidence -> complete, block with recovery conditions, or reopen a
-blocked or disproven completion after upstream correction ->
-continue. When the human changes a consequential prior answer, preserve the superseding decision and
-repair affected documents and Tasks before continuing.`;
-
-export const AGENT_PROTOCOL = `${AGENT_CORE}\n\n${RUNTIME_PROTOCOL}`;
-
-export const AGENT_ANCHOR = `<!-- loom:v2 -->
-## LOOM
-
-This project uses LOOM as Agent-only continuity infrastructure. Run \`loom context\` before substantial
-work, keep project truth, design documents, professional capability dossiers, and Tasks current through
-the CLI, and never ask the human to operate LOOM.`;
-
-function renderKeeperGap(item) {
-  if (typeof item === 'string') return `  - ${item}`;
-  if (!item || typeof item !== 'object') return `  - ${String(item)}`;
-  const title = item.gap || item.title || '<unnamed gap>';
-  const why = item.why_it_blocks_start || item.why || '';
-  const proof = item.evidence_to_close || item.close_when || '';
-  return [`  - gap: ${title}`, why ? `    why: ${why}` : '', proof ? `    evidence to close: ${proof}` : ''].filter(Boolean).join('\n');
-}
-
-export function shapingContext({ state, taskSummary, capabilityNames, designNames, forKeeper = false }) {
-  const open = state.understanding.unresolved.filter((item) => item.status === 'open');
-  const assumptions = state.understanding.assumptions.filter((item) => item.status === 'active');
-  const latestKeeper = state.keeper.attempts.at(-1);
-  const keeperFeedback = ['needs_revision', 'blocked'].includes(state.keeper.status) && latestKeeper
-    ? `### ${forKeeper ? 'Prior Keeper feedback this prepared revision claims to close' : 'Keeper feedback that must enter the next iteration'}
-
-- verdict: ${latestKeeper.verdict}
-- run: ${latestKeeper.run_id}
-- summary: ${latestKeeper.summary}
-- gaps:
-${latestKeeper.gaps.length ? latestKeeper.gaps.map(renderKeeperGap).join('\n') : '  - none recorded'}
-- evidence:
-${latestKeeper.evidence.map((item) => `  - ${item}`).join('\n')}
-
-${forKeeper
-    ? 'Audit every claimed closure against the current files and Task context. Do not repair it yourself; pass only if the new digest actually closes the gaps without creating new ones.'
-    : 'Trace each gap to the project index, a design document, a professional capability dossier, or a Task.\nRepair the source of truth rather than answering the review in prose. Ask the human only when the gap\ndepends on their consequential choice. Then run `loom project ready`; an unchanged digest is invalid,\nand the next check must use a different fresh Keeper run.'}`
-    : '';
-  return `## Current LOOM state
-
-- project status: ${state.project.status}
-- confirmed facts: ${state.understanding.confirmed.length}
-- active assumptions: ${assumptions.length}
-- open questions: ${open.length}
-- design documents: ${designNames.length ? designNames.join(', ') : 'none yet'}
-- professional capability dossiers: ${capabilityNames.length ? capabilityNames.join(', ') : 'none yet'}
-- work map: ${taskSummary.total} tasks (${taskSummary.done} done, ${taskSummary.open} open, ${taskSummary.blocked} blocked)
-- active task: ${taskSummary.active || 'none'}
-
-${open.length ? `### Open uncertainty\n\n${open.map((item) => `- ${item.id} [${item.impact}]: ${item.question}`).join('\n')}` : 'No open uncertainty is recorded.'}
-
-${assumptions.length ? `### Active assumptions\n\n${assumptions.map((item) => `- ${item.id}: ${item.text}`).join('\n')}` : ''}
-
-${keeperFeedback}`;
-}
-
-export function keeperProtocol({ attemptNumber, preparedDigest } = {}) {
-  return `# LOOM independent Keeper handoff
-
-You are a fresh Agent with no access to the shaping conversation. Do not repair the project and do not
-edit implementation. Use only this workspace and the LOOM CLI. Run \`loom context --keeper\`, inspect
-the referenced files, and attempt a real handoff from disk.
-
-Judge buildability, not document polish or document count. Demonstrate whether you can:
-
-1. Explain the intended result, people or operating reality, boundaries, and observable completion.
-2. Navigate PROJECT.md into the necessary product, experience, system, contract, operations, and
-   verification documents without prior chat memory.
-3. Identify every professional field that materially shapes the project, keep those fields distinct,
-   and explain the project-specific stance each contributes.
-4. Select the first executable Task, justify its dependencies, load every file it names, and state the
-   concrete first edit or command.
-5. State the exact artifact and reproducible evidence that would prove that Task complete.
-6. Expose contradictions, missing systems, absent capability domains, generic expertise, inaccessible
-   context, invented certainty, or any point where a new Agent would have to guess.
-
-This is Keeper attempt ${attemptNumber || '<unknown>'}. The frozen prepared digest is
-\`${preparedDigest || '<run loom project ready>'}\`. Generate a unique run_id for this fresh Agent and
-include both run_id and prepared_digest in the result.
-
-Use this result shape. Keep \`gaps\` empty on pass; otherwise prefer structured gaps so the next Agent
-receives the reason and closure evidence without interpretation loss:
-
-\`\`\`json
-{
-  "run_id": "<unique-id>",
-  "prepared_digest": "<digest-above>",
-  "verdict": "passed | needs_revision | blocked",
-  "summary": "<concise handoff judgment>",
-  "gaps": [
-    {
-      "gap": "<missing or contradictory truth>",
-      "why_it_blocks_start": "<concrete consequence for a fresh Agent>",
-      "evidence_to_close": "<observable condition that would close it>"
-    }
-  ],
-  "evidence": ["<file, command, or observation supporting the verdict>"]
-}
-\`\`\`
-
-Record the result with \`loom keeper record --json-file <result.json>\`. Use \`passed\` only when you
-could responsibly begin the first Task. Otherwise use \`needs_revision\` with concrete gaps and the
-observable evidence that would close each one, or \`blocked\` when progress requires unavailable
-authority or external state. A failed attempt returns the project to shaping; revision requires a
-changed digest and another fresh Keeper.`;
-}
-
-export const PROJECT_TEMPLATE = `# Project Whole and Document Map
-
-> This is the concise entry point, not the container for every design decision. Describe the whole and
-> link the documents that make it buildable. Add or remove documents according to project complexity.
-
-## Intended result
-
-What should exist or become possible when this project succeeds?
-
-## People and operating reality
-
-Who or what experiences the result, and in what real situation?
-
-## Whole experience or behavior
-
-Describe the coherent end-to-end result rather than a feature inventory.
-
-## Boundaries and consequential assumptions
-
-What must not be changed, lost, invented, or expanded without authority?
-
-## Design document map
-
-Link every product, experience, system, contract, verification, or operations document and state the
-decision surface it owns. Complex subsystems should have their own files under \`.loom/design/\`.
-
-## Professional capability map
-
-Link each separate field dossier under \`.loom/capabilities/\` and state which design decisions it
-changes. Do not merge distinct fields into one dossier.
-
-## Completion and failure
-
-What observable evidence means the project worked? What could look complete while actually failing?
-
-## Work map
-
-Explain the delivery shape and point to \`.loom/tasks.json\`; do not duplicate volatile Task state here.
-`;
-
-const DESIGN_SECTIONS = {
-  product: ['Outcome and users', 'Problem and operating reality', 'Product principles', 'Scope and non-goals', 'End-to-end behavior', 'Success and failure signals', 'Decisions and open questions', 'Related documents and capabilities'],
-  experience: ['Experience intent', 'Users and contexts', 'Journey and information architecture', 'Interaction states and transitions', 'Content, visual, and accessibility direction', 'Errors, empty states, and recovery', 'Usability verification', 'Related documents and capabilities'],
-  system: ['Responsibility in the whole', 'Inputs, outputs, and boundaries', 'Components and control flow', 'Data and state', 'Interfaces and dependencies', 'Failure, safety, and recovery', 'Implementation constraints', 'Verification strategy', 'Related documents and capabilities'],
-  contract: ['Consumers and purpose', 'Schema or command surface', 'Invariants and permissions', 'Errors and compatibility', 'Examples and fixtures', 'Contract tests', 'Related documents and capabilities'],
-  verification: ['Claims under test', 'Environments and fixtures', 'Acceptance matrix', 'Commands and evidence', 'Negative and failure tests', 'Known blind spots', 'Related documents and capabilities'],
-  operations: ['Operational outcome', 'Preconditions and authority', 'Procedure and commands', 'Safety boundaries', 'Failure detection and recovery', 'Evidence and audit trail', 'Related documents and capabilities'],
-  research: ['Decision to inform', 'Current evidence and unknowns', 'Method and sources', 'Findings', 'Conflicts and limitations', 'Project consequences', 'Follow-up verification', 'Related documents and capabilities'],
-};
-
-export const DESIGN_KINDS = Object.freeze(Object.keys(DESIGN_SECTIONS));
-
-export function designTemplate({ title, kind }) {
-  const sections = DESIGN_SECTIONS[kind];
-  if (!sections) throw new Error(`Unknown design kind: ${kind}`);
-  return `# ${title}\n\n- Kind: ${kind}\n- Status: shaping\n\n${sections.map((section) => `## ${section}\n\nDescribe the project-specific decision, mechanism, boundary, or evidence owned by this section.`).join('\n\n')}\n`;
-}
-
-export const CAPABILITY_TEMPLATE = ({ title }) => `# ${title}
-
-> One dossier covers one recognizable professional field. Keep UI/UX, visual art direction, game
-> design, psychology, biology, security, and other fields separate when their evidence and judgments
-> differ. Put cross-field synthesis in the affected design document, not in a hybrid capability title.
-
-## Field identity and boundary
-
-Name the established field, what expertise it contributes, and what belongs to another dossier.
-
-## Project decisions this field changes
-
-Identify the consequential questions, design choices, risks, or verification methods that would be
-weaker without this field.
-
-## Project-specific diagnosis
-
-Interpret this project's users, constraints, existing evidence, and tensions through this field. Show
-authored judgment rather than a generic overview.
-
-## Principles, evidence, and sources
-
-Record specialist principles and opened sources when research is used. State what each source changed,
-where sources disagree, and what remains uncertain.
-
-## Distinctive stance and rejected defaults
-
-State what this project will do, why, the important tradeoffs, and which common or generic approaches it
-will deliberately refuse.
-
-## Consequences for design, implementation, and verification
-
-Translate the field's stance into concrete requirements and link the design documents it affects.
-
-## Questions that could change the stance
-
-Keep only unresolved questions whose answers would materially alter this field's contribution.
-
-## Failure modes and proof signals
-
-Describe characteristic weak, generic, or harmful outcomes and the observable evidence that distinguishes
-a strong result.
-
-## Relationships without merger
-
-Link adjacent capability dossiers and explain the tension or handoff. Do not absorb their expertise here.
-`;
-
-export function evalConditionPrompt({ brief, loom }) {
-  return loom
-    ? `# Evaluation condition\n\n${brief}\n\nWork with all ordinary Agent capabilities and tools. Use LOOM as invisible continuity infrastructure: run \`loom context\`, maintain its disk state, and never ask the human to operate it. This condition has no extra authority or information.`
-    : `# Evaluation condition\n\n${brief}\n\nWork as a normal capable Agent with all ordinary capabilities and tools. LOOM and its files are unavailable in this condition. Use any normal planning or documentation you judge useful.`;
-}
-
-export function evalJudgePrompt() {
-  return `# Blind Evil Eval judge
-
-You receive two anonymized runs in randomized order. Do not infer framework identity. Judge observable
-work, not framework-shaped filenames or document volume. Cite evidence for every score. Compare intent
-fidelity, question value, whole-project coverage, professional capability depth, buildability, continuity
-after forced resets, implementation evidence, user burden, and cost/time. Penalize unnecessary ceremony,
-questions that do not change decisions, and documentation that a fresh Agent cannot use. Swap order and
-judge again; mark order-sensitive conclusions unstable. Attribute missing files or path failures to a run
-only after the anonymized packet passed its relative-layout and declared-test preflight. A system wins only if its benefit survives equal
-model, tools, workspace, user facts, reset points, and budget.`;
-}
-
-export function promptCatalog() {
-  const placeholderState = {
-    project: { status: '<project-status>' },
-    understanding: {
-      confirmed: [],
-      assumptions: [{ id: '<assumption-id>', text: '<assumption>', status: 'active' }],
-      unresolved: [{ id: '<question-id>', question: '<material uncertainty>', impact: 'high', status: 'open' }],
-    },
-    keeper: { status: 'not_run', attempts: [] },
-  };
-  const revisionState = {
-    ...placeholderState,
-    keeper: {
-      status: 'needs_revision',
-      attempts: [{
-        verdict: 'needs_revision',
-        run_id: '<fresh-run-id>',
-        summary: '<why the handoff cannot start>',
-        gaps: ['<concrete gap>'],
-        evidence: ['<observable evidence>'],
-      }],
-    },
-  };
-  return {
-    purpose: 'Complete inventory of LOOM cognitive messages. Validation errors and JSON status payloads enforce state but are not Agent prompts.',
-    layers: {
-      stable_core: AGENT_CORE,
-      runtime_protocol: RUNTIME_PROTOCOL,
-      project_state: shapingContext({ state: placeholderState, taskSummary: { total: 0, done: 0, open: 0, blocked: 0, active: null }, capabilityNames: [], designNames: [] }),
-      project_state_after_keeper_failure: shapingContext({ state: revisionState, taskSummary: { total: 1, done: 0, open: 1, blocked: 0, active: null }, capabilityNames: ['<field>.md'], designNames: ['<system>.md'] }),
-      keeper_review_of_prior_failure: shapingContext({ state: revisionState, taskSummary: { total: 1, done: 0, open: 1, blocked: 0, active: null }, capabilityNames: ['<field>.md'], designNames: ['<system>.md'], forKeeper: true }),
-      current_task: '## Active Task\n\n<exact Task JSON>\n\n---\n\n## Task context: <path from Task.reads>\n\n<exact file content>\n\n(repeated for every read path)',
-      on_demand_map: '## On-demand project context\n\n- Decision history: .loom/DECISIONS.md (read when correction or lineage matters)\n- Design: .loom/design/<document>.md\n- Professional capability: .loom/capabilities/<field>.md',
-      keeper_context: '## Decision history (...)\n\n<exact DECISIONS.md>\n\n---\n\n## Work map summary\n\n<summary and first executable Task>\n\n---\n\n## Design document: <name>\n\n<exact content>\n\n---\n\n## Capability dossier: <name>\n\n<exact content>',
-    },
-    workspace_anchor: AGENT_ANCHOR,
-    templates: {
-      project_index: PROJECT_TEMPLATE,
-      design_documents: Object.fromEntries(DESIGN_KINDS.map((kind) => [kind, designTemplate({ title: `<${kind}-title>`, kind })])),
-      professional_capability: CAPABILITY_TEMPLATE({ title: '<recognizable-professional-field>' }),
-      decision_history: '# Decision History\n\nCurrent truth belongs in PROJECT.md and linked design documents. This file preserves consequential superseding decisions.',
-    },
-    keeper: keeperProtocol({ attemptNumber: '<attempt-number>', preparedDigest: '<prepared-digest>' }),
-    evaluation: {
-      baseline_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: false }),
-      loom_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: true }),
-      blind_judge: evalJudgePrompt(),
-    },
-    composition: {
-      normal_resume: ['stable_core', 'runtime_protocol', 'project_state', 'PROJECT.md', 'on-demand document and capability map'],
-      active_task: ['normal_resume', 'active Task JSON', 'exact files in Task.reads'],
-      keeper_handoff: ['keeper', 'normal_resume', 'DECISIONS.md', 'Work Map summary and first executable Task', 'all design documents', 'all professional capability dossiers'],
-    },
-  };
-}
+export const AGENT_CORE = `# LOOM collaboration core
+
+Work toward the result the human wants in the world. Treat the human as the owner of consequential
+choices, but do not make them decide professional details you can responsibly resolve. Separate
+confirmed fact, inference, assumption, and unknown. Inspect discoverable reality before asking about
+it. Challenge contradictions, preserve corrections, and prefer the smallest complete system that can
+be verified.
+
+Ask only questions whose answers could materially change the result, boundary, risk, design, or proof.
+Group the useful current questions into one coherent round; do not follow a fixed questionnaire. After
+answers, update the emerging whole and ask again only where important uncertainty remains. When the
+human delegates a reversible decision, make and record a project-specific judgment. When they insist
+on skipping clarification, state the concrete risk once, record the assumption, and continue.`;
+
+export function environmentProtocol({ humanChannel = 'available' } = {}) {
+  if (!['available', 'unavailable'].includes(humanChannel)) throw new Error('humanChannel must be available or unavailable');
+  if (humanChannel === 'available') return `## Environment availability
+
+A human response channel is available. First inspect facts discoverable from the workspace, tests, tools, and
+permitted sources. Ask the human only for consequential intent, authority, preference, or information they uniquely hold.`;
+  return `## Environment availability
+
+Human response channel: unavailable. Do not fabricate a user interaction. First inspect facts discoverable from
+the workspace, tests, and available tools. Research only objective external facts when the task and host permit it;
+never use web research as a substitute for user intent, preference, or authority. When a consequential answer remains
+unavailable, record a bounded assumption and choose a safe reversible action, or block when the action is irreversible,
+high-risk, or materially costly.`;
+}
+
+export const RUNTIME_PROTOCOL = `# LOOM runtime protocol
+
+LOOM is invisible continuity infrastructure for the Agent. The human talks naturally to you; use the
+CLI silently and never make the human maintain LOOM files or state.
+
+## Shape the whole before material execution
+
+Maintain five distinct layers:
+
+1. \`.loom/PROJECT.md\` is the concise entry point and map of the current whole.
+2. \`.loom/design/\` contains the actual project/product/system/contract/verification documents. Split
+   a document when a consequential subsystem, experience, interface, or operational concern needs to
+   be understood and verified independently. Small projects may need few documents; large projects may
+   need many. Do not compress a complex product into PROJECT.md merely to keep the file count low.
+3. \`.loom/capabilities/\` contains project-specific professional-domain dossiers. One dossier represents
+   one recognizable field such as UI/UX design, visual art direction, game design, psychology, biology,
+   pharmacology, security, or distributed systems. Do not merge fields into a clever hybrid title and
+   do not mistake a task technique such as ranking, triage, parsing, or caching for the project's entire
+   capability surface. Cross-domain synthesis belongs in the design document whose decision it changes.
+   Each dossier is a research directory containing a decision-tree capability file, a research folder of
+   expert narratives and sources, and a status file tracking the shaping lifecycle. The kernel of a
+   dossier is a conditional-branch decision tree — how an expert in this field thinks through this
+   project's problems — not a fixed step list or a declarative stance. Every decision node carries a
+   source citation and a counterexample. The tree is a resource for the Agent, not a script; when
+   evidence points outside it, the Agent updates the tree rather than ignoring the evidence.
+4. \`.loom/tasks.json\` is a restartable Work Map. Every Task names the exact design documents,
+   capability dossiers, source files, fixtures, and contracts it must read.
+5. \`.loom/STRUCTURE.md\` declares where project files live — source code, tests, docs, configs,
+   assets. The Agent reads this before creating or moving files so the project stays organized
+   without the human having to redirect every placement. Customize it for each project; LOOM does
+   not prescribe a fixed directory layout.
+
+Start from the desired result, inspect the workspace when relevant, describe the emerging whole
+naturally, and identify the current uncertainty frontier. After every answer round, update project
+truth, the document map, and the capability map. Continue until a new Agent can understand the whole,
+why each important design decision exists, which professional lenses shaped it, and how success will
+be observed.
+
+## Compile professional capability
+
+Identify capabilities at the level of established professional fields. Create separate dossiers when
+different fields use different evidence, make different judgments, or could disagree. A dossier is not
+a textbook summary or a costume labelled "expert". Its kernel is a conditional-branch decision tree
+that captures how an expert in this field thinks through this project's problems — not a fixed step
+list. Each decision node carries an entry condition, options, judgment criteria, a source citation,
+a counterexample, and an output. Nodes without sources are not accepted; branches without
+counterexamples are fixed steps in disguise.
+
+Build dossiers in four steps: research (collect expert narratives, case studies, and methodology
+sources), synthesize (construct the project-specific decision tree from research), confirm (the user
+confirms which expert scenario this project most resembles — the Agent must not decide this alone),
+and confirmed. \`loom capability research\` creates a \`_guide.md\` in the research directory explaining
+what to write — create one .md file per source, citing where the knowledge came from. \`loom capability
+synthesize\` reads those files and validates that every decision tree node has a source citation and a
+counterexample. A dossier that has not been confirmed should not be referenced by Tasks, but the
+Agent may proceed provisionally when the user is unavailable and record the assumption. Confirmed
+dossiers can be reopened when new evidence changes the professional reasoning.
+
+Do not force every conceivable field into the project. Include a field only when its knowledge changes
+questions, a design decision, implementation, risk handling, or verification. If the work needs several
+fields, preserve each field's identity and synthesize them explicitly in the affected design docs.
+
+## Build a restartable Work Map
+
+Plan the whole delivery surface first, then decompose into Tasks at a granularity where each Task
+produces one verifiable unit of real work. A Task that says "implement the feature" is too large; a
+Task that says "add one field to one struct" is too small. The right granularity is: one Task produces
+one piece of evidence you can point to and say "this is done and here is how I know."
+
+Each Task records:
+- **outcome**: what changes in the world when this Task is done — not a summary of activity, but the
+  observable difference. At least one sentence with a concrete noun.
+- **acceptance**: an array of conditions, each pairing three things —
+  - \`criterion\`: what must be true for this condition to pass (observable, not aspirational)
+  - \`verify_by\`: how to check — run a test, walk through a flow, review against a design, inspect a
+    dashboard, ask an editor. LOOM does not prescribe the method; the field does.
+  - \`evidence\`: what the proof looks like when done — a test log, a screenshot, a review record, a
+    monitoring snapshot. Plan it before starting; fill in the actual result when completing.
+- **boundaries**: what this Task does NOT do. At least one. Without boundaries a Task grows until it
+  becomes the whole project.
+- **reads**: every file, document, or artifact the Agent must consume to do this Task. Must be specific
+  paths, not categories. If the Agent needs it, list it; if it is not listed, the Agent should not
+  depend on it.
+- **touches**: every file, document, or artifact the Task is expected to produce or modify. Must be
+  specific paths. A Task that touches nothing is not a Task.
+- **depends_on**: other Tasks that must be done first. Empty is valid only when this Task has no
+  prerequisites.
+- **covers**: which delivery units this Task advances. Use this to check that the delivery surface is
+  fully covered.
+
+A long project may have many Tasks. Do not pre-write thousands of speculative micro-steps — split and
+revise the map as reality becomes clearer. But do not leave the map at five vague placeholders either.
+Each Task should be small enough that its acceptance conditions are concrete, and large enough that
+completing it means something real shipped.
+
+Before engineering or another material operation begins, tell the human what is about to happen and
+which consequential assumptions remain. Ordinary reversible work needs no extra ceremony; irreversible,
+high-risk, or materially costly action still requires authority.
+
+## Close the loops
+
+Understanding loop: describe the whole -> locate consequential uncertainty -> ask in a batch -> record
+answers and decisions -> update design and capability maps -> repeat while material uncertainty remains.
+
+Keeper loop: prepare a frozen digest -> fresh Keeper attempts to start from disk -> on
+\`needs_revision\` or \`blocked\`, absorb every concrete gap into project truth, design docs, capability
+dossiers, or Tasks -> prepare a changed digest. When all gaps are minor and 3 or fewer, fixing them
+and running \`loom project ready\` auto-passes without a new Keeper round; otherwise another fresh
+Keeper is required. Keeper does not reappear for every Task.
+
+Delivery loop: select an executable Task -> load exactly referenced context -> implement and verify ->
+fill in each acceptance condition's evidence with the actual result -> complete, block with recovery
+conditions, or reopen a blocked or disproven completion after upstream correction ->
+continue.
+
+Evolution loop: when a new idea changes an existing decision, record what changed and why with
+\`loom decision --json-file\` (listing affected files and tasks), then update the design document
+directly — the current truth always lives in \`.loom/\`, not in versioned snapshots. If the change
+affects completed Tasks, \`loom check\` warns which done Tasks were marked affected; reopen them when
+the change invalidates prior work. Git history preserves old versions; LOOM does not duplicate version
+numbers. The project has one current truth at a time.`;
+
+export function agentProtocol(options = {}) {
+  return `${AGENT_CORE}\n\n${environmentProtocol(options)}\n\n${RUNTIME_PROTOCOL}`;
+}
+
+export const AGENT_PROTOCOL = agentProtocol();
+
+export const EXECUTION_PROTOCOL = `# LOOM active Task execution protocol
+
+This block applies only when a Task is active or explicitly loaded. Treat the disk state below as the
+recovery source; conversation memory may be incomplete.
+
+## Recover before changing anything
+
+1. Re-read the Task outcome, acceptance conditions (criterion, verify_by, evidence), boundaries,
+   dependencies, reads, expected touches, progress, next action, and existing evidence. Read every
+   injected Task context file.
+2. If the Task carries capability_hooks, treat them as professional reasoning you can use — not a script
+   you must follow. Each hook points to a specific node (e.g. \`ui-ux-design#C2\`) with entry conditions,
+   options, judgment criteria, a source citation, and a counterexample. Use them to inform your judgment.
+   If the node's entry condition is not met, skip it. If the evidence points somewhere the tree does not
+   cover, trust the evidence and update the capability. If a hook's must_produce field names an artifact,
+   produce it before completing the Task.
+3. Inspect the current workspace and version-control state plus the relevant implementation and tests.
+   Preserve user changes. If the Task conflicts with discoverable reality, update or block the Task instead
+   of silently following stale context or inventing missing facts.
+4. Resume from progress.next when it remains valid. Otherwise choose the smallest complete next action
+   that advances the outcome and can be checked against a done condition.
+
+## Build and prove the smallest complete change
+
+- Stay inside the outcome and boundaries. If implementation requires a wider system, authority, risk, or
+  file surface than the Task describes, repair the Task or upstream design first.
+- Inspect the relevant existing tests before editing. When observable behavior changes and a stable test
+  seam exists, add or update the smallest test that can fail for the missing behavior, then implement and
+  run it. Documentation, research, configuration, and operational Tasks use the verification appropriate
+  to their claim; do not manufacture a ceremonial unit test.
+- Iterate on local failures while the Task remains active. If the failure exposes an upstream design gap,
+  unavailable authority, or external dependency, block with concrete recovery conditions rather than
+  broadening scope invisibly.
+
+## Leave a restartable handoff
+
+- After a material checkpoint, before an expected context reset, or when handing work to another Agent,
+  persist concise completed, current, and executable next progress with loom task update.
+  Record evidence only after the referenced command, artifact, or observation actually exists.
+- Complete through loom task done only after every acceptance condition has its evidence filled
+  with a reproducible result. Report known blind spots and unverified boundaries honestly.
+- A branch, commit, or pull request is a delivery mechanism, not a universal Task requirement. Create one
+  when the human or repository workflow asks for it, map it to the Task outcome, and include the verification
+  evidence; do not use a PR to disguise an incomplete Task.
+
+## Show progress and review at checkpoints
+
+The human's patience is the project's fuel. Do not let several Tasks pass in silence.
+
+- **After each Task**: if the Task produced something the human can see or run, show it — run the command,
+  open the page, display the output. One real working thing is worth more than a status line.
+- **Every few Tasks or at a natural milestone**: do a staged review. Run the project's own tests, inspect
+  code quality against the design intent, and tell the human what passed and what surprised you. Catch
+  drift while it is cheap to fix.
+- **Before declaring a batch done**: run \`loom check\` and the project's own tests together. Both must
+  pass. If tests fail or coverage drops, fix before moving on — do not let partial work accumulate behind
+  a green-looking summary.
+- **Prioritize the exciting surface**: if the project has a surface the human will enjoy — a UI, clean CLI
+  output, a visualization, a working demo — reach an early slice of it sooner rather than saving it for
+  last. The human's "I want to see more" feeling is real project fuel.
+
+Do not narrate this protocol to the human unless it helps them understand a decision, risk, or handoff.`;
+
+export const AGENT_ANCHOR = `<!-- loom:v2 -->
+## LOOM
+
+This project uses LOOM as Agent-only continuity infrastructure. Run \`loom context\` when entering the
+project, after a context reset, and before substantial work. When a Task is active, the command restores
+its execution protocol, exact state, and declared context; rerun it before editing after any interruption.
+Keep project truth, design documents, professional capability dossiers, and Tasks current through the CLI,
+and never ask the human to operate LOOM. Do not rerun LOOM before every tool call: persist and restore at
+meaningful work boundaries.`;
+
+function renderKeeperGap(item) {
+  if (typeof item === 'string') return `  - ${item}`;
+  if (!item || typeof item !== 'object') return `  - ${String(item)}`;
+  const title = item.gap || item.title || '<unnamed gap>';
+  const why = item.why_it_blocks_start || item.why || '';
+  const proof = item.evidence_to_close || item.close_when || '';
+  return [`  - gap: ${title}`, why ? `    why: ${why}` : '', proof ? `    evidence to close: ${proof}` : ''].filter(Boolean).join('\n');
+}
+
+export function shapingContext({ state, taskSummary, capabilityNames, designNames, forKeeper = false }) {
+  const open = state.understanding.unresolved.filter((item) => item.status === 'open');
+  const assumptions = state.understanding.assumptions.filter((item) => item.status === 'active');
+  const latestKeeper = state.keeper.attempts.at(-1);
+  const keeperFeedback = ['needs_revision', 'blocked'].includes(state.keeper.status) && latestKeeper
+    ? `### ${forKeeper ? 'Prior Keeper feedback this prepared revision claims to close' : 'Keeper feedback that must enter the next iteration'}
+
+- verdict: ${latestKeeper.verdict}
+- run: ${latestKeeper.run_id}
+- summary: ${latestKeeper.summary}
+- gaps:
+${latestKeeper.gaps.length ? latestKeeper.gaps.map(renderKeeperGap).join('\n') : '  - none recorded'}
+- evidence:
+${latestKeeper.evidence.map((item) => `  - ${item}`).join('\n')}
+
+${forKeeper
+    ? 'Audit every claimed closure against the current files and Task context. Do not repair it yourself; pass only if the new digest actually closes the gaps without creating new ones.'
+    : 'Trace each gap to the project index, a design document, a professional capability dossier, or a Task.\nRepair the source of truth rather than answering the review in prose. Ask the human only when the gap\ndepends on their consequential choice. Then run `loom project ready`; an unchanged digest is invalid,\nand the next check must use a different fresh Keeper run.'}`
+    : '';
+  return `## Current LOOM state
+
+- project status: ${state.project.status}
+- confirmed facts: ${state.understanding.confirmed.length}
+- active assumptions: ${assumptions.length}
+- open questions: ${open.length}
+- design documents: ${designNames.length ? designNames.join(', ') : 'none yet'}
+- professional capability dossiers: ${capabilityNames.length ? capabilityNames.join(', ') : 'none yet'}
+- work map: ${taskSummary.total} tasks (${taskSummary.done} done, ${taskSummary.open} open, ${taskSummary.blocked} blocked)
+- active task: ${taskSummary.active || 'none'}
+
+${open.length ? `### Open uncertainty\n\n${open.map((item) => `- ${item.id} [${item.impact}]: ${item.question}`).join('\n')}` : 'No open uncertainty is recorded.'}
+
+${assumptions.length ? `### Active assumptions\n\n${assumptions.map((item) => `- ${item.id}: ${item.text}`).join('\n')}` : ''}
+
+${keeperFeedback}`;
+}
+
+export function keeperProtocol({ attemptNumber, preparedDigest } = {}) {
+  return `# LOOM independent Keeper handoff
+
+You are a fresh Agent with no access to the shaping conversation. Do not repair the project and do not
+edit implementation. Use only this workspace and the LOOM CLI. Run \`loom context --keeper\`, inspect
+the referenced files, and attempt a real handoff from disk.
+
+Your job is a Crux review: check that the chain from responsible intent to verifiable behavior is intact.
+Do not judge document polish or count. Judge whether a fresh Agent could start from disk and still
+produce what the human actually wants.
+
+## Integrity chain check
+
+Walk this chain and look for the six distortions:
+
+1. **Responsible intent** — What should exist or become possible? Who or what experiences it? What are
+   the non-negotiable boundaries and accepted tradeoffs?
+2. **Project promises** — Does PROJECT.md still express that intent, or has it drifted into document
+   self-reference? Are the design documents and capability maps tied to the same goal?
+3. **Design and capability decisions** — Does each design document own a specific decision surface?
+   Does each capability dossier represent a recognizable field with source-cited, counterexample-backed
+   decision nodes? Are capability and design synthesis in the right place?
+4. **Work Map** — Are Tasks at evidence granularity? Do they read the right documents, touch the right
+   files, and state clear boundaries and acceptance conditions? Is the first executable Task responsible?
+5. **Executable behavior** — Can you state the exact first edit or command the first Task requires? Can
+   you find or infer the tests, commands, or observations that would prove completion?
+6. **Human feedback loop** — Is there a clear, observable completion signal? Could the human recognize
+   whether the result matched their intent without being a LOOM operator?
+
+Look for these specific distortions:
+
+- **Omission**: intent, boundary, or decision that exists in conversation but not in the documents.
+- **Substitution**: a document, metric, or local optimization presented as the real result.
+- **Drift**: a later design or Task that silently changed the intent, boundary, or accepted tradeoff.
+- **Leap**: a claim that jumps from design to implementation without a verifiable bridge.
+- **Blindness**: a key state the project cannot observe, such as whether a fresh Agent can start, whether
+  a done Task has real evidence, or whether a design document is stale.
+- **Ownerless**: an exception, contradiction, or long-term maintenance item with no responsible party.
+
+## Buildability check
+
+After the integrity chain, also demonstrate whether you can:
+
+1. Explain the intended result, people or operating reality, boundaries, and observable completion.
+2. Navigate PROJECT.md into the necessary product, experience, system, contract, operations, and
+   verification documents without prior chat memory.
+3. Identify every professional field that materially shapes the project, keep those fields distinct,
+   and explain the project-specific stance each contributes.
+4. Select the first executable Task, justify its dependencies, load every file it names, and state the
+   concrete first edit or command.
+5. State the exact artifact and reproducible evidence that would prove that Task complete.
+6. Expose contradictions, missing systems, absent capability domains, generic expertise, inaccessible
+   context, invented certainty, or any point where a new Agent would have to guess.
+
+This is Keeper attempt ${attemptNumber || '<unknown>'}. The frozen prepared digest is
+\`${preparedDigest || '<run loom project ready>'}\`. Generate a unique run_id for this fresh Agent and
+include both run_id and prepared_digest in the result.
+
+Use this result shape. Keep \`gaps\` empty on pass; otherwise prefer structured gaps so the next Agent
+receives the reason and closure evidence without interpretation loss. Mark each gap with severity
+\`blocking\` (a fresh Agent cannot start without this being fixed) or \`minor\` (an improvement that
+does not block the first Task). When all gaps are minor and there are 3 or fewer, LOOM will auto-pass
+after the gaps are fixed without requiring another Keeper round:
+
+\`\`\`json
+{
+  "run_id": "<unique-id>",
+  "prepared_digest": "<digest-above>",
+  "verdict": "passed | needs_revision | blocked",
+  "summary": "<concise handoff judgment>",
+  "gaps": [
+    {
+      "gap": "<missing or contradictory truth>",
+      "severity": "blocking | minor",
+      "why_it_blocks_start": "<concrete consequence for a fresh Agent>",
+      "evidence_to_close": "<observable condition that would close it>"
+    }
+  ],
+  "evidence": ["<file, command, or observation supporting the verdict>"]
+}
+\`\`\`
+
+Record the result with \`loom keeper record --json-file <result.json>\`. Use \`passed\` only when you
+could responsibly begin the first Task. Otherwise use \`needs_revision\` with concrete gaps and the
+observable evidence that would close each one, or \`blocked\` when progress requires unavailable
+authority or external state. A failed attempt returns the project to shaping; revision requires a
+changed digest. When all gaps are minor and 3 or fewer, fixing them and running \`loom project ready\`
+will auto-pass without a new Keeper round; otherwise another fresh Keeper is required.`;
+}
+
+export const PROJECT_TEMPLATE = `# Project Whole and Document Map
+
+> This is the concise entry point, not the container for every design decision. Describe the whole and
+> link the documents that make it buildable. Add or remove documents according to project complexity.
+> The Agent uses \`loom context\` to compile this with the active Task and referenced files.
+
+## Intended result
+
+What should exist or become possible when this project succeeds?
+
+## People and operating reality
+
+Who or what experiences the result, and in what real situation?
+
+## Whole experience or behavior
+
+Describe the coherent end-to-end result rather than a feature inventory.
+
+## Boundaries and consequential assumptions
+
+What must not be changed, lost, invented, or expanded without authority?
+
+## Design document map
+
+Link every product, experience, system, contract, verification, or operations document and state the
+decision surface it owns. Complex subsystems should have their own files under \`.loom/design/\`.
+
+## Professional capability map
+
+Link each separate field dossier under \`.loom/capabilities/<field>/capability.md\` and state which
+design decisions it changes. Do not merge distinct fields into one dossier. Capabilities are shaped in
+four steps: \`loom capability research\` → \`synthesize\` → \`confirm\` (user confirms the scenario).
+
+## Project structure
+
+Point to \`.loom/STRUCTURE.md\` — where source code, tests, docs, assets, and configuration files live.
+The Agent reads this before creating or moving files.
+
+## Work map
+
+Point to \`.loom/tasks.json\`; do not duplicate volatile Task state here. Each Task uses
+\`acceptance[]\` with \`criterion\`, \`verify_by\`, and \`evidence\` fields. Completion requires one
+\`acceptance_results\` entry per criterion with concrete evidence. Use \`done_when[]\` only for legacy
+Tasks.
+
+## Decision history
+
+Consequential changes to existing decisions go in \`.loom/DECISIONS.md\`. Use \`loom decision --json-file\`
+to record what changed, why, and which tasks were affected. \`loom check\` warns when a done Task is
+marked affected by a later decision.
+
+## Completion and failure
+
+What observable evidence means the project worked? What could look complete while actually failing?
+
+## Staged visibility and review
+
+The human funds this project with attention and patience. Long stretches without visible progress
+erode that patience, even when the work is sound. Design the Work Map so the human sees the project
+growing, not just LOOM state changing.
+
+- **Human-visible acceptance**: when designing Tasks, prefer acceptance criteria whose evidence is
+  something the human can see or feel — a command running, a page rendering, a file with real content,
+  a test passing in front of them. Machine-only verification is valid but should not be the only thing
+  the human sees for long stretches.
+- **Staged showcase**: every few Tasks, or at each natural project milestone, show the human something
+  real that now works. Run the CLI, open the page, display the data, walk through the flow. A working
+  thing creates momentum; a status update does not.
+- **Staged review**: at material checkpoints, review what was built — run tests, inspect code quality,
+  check against design intent. Catch drift early while it is cheap to fix. Tell the human what passed
+  and what surprised you.
+- **Verification gate**: after a batch of Tasks, run \`loom check\` and the project's own tests together.
+  Both should pass before telling the human the batch is done. If tests fail or coverage drops, fix
+  before moving on — do not let partial work accumulate behind a green-looking summary.
+- **Excitement is a feature**: if the project has a surface the human will enjoy seeing — a UI, a CLI
+  with clean output, a visualization, a working demo — prioritize reaching that surface early. The
+  human's "I want to see more of this" feeling is real project fuel. Do not save the satisfying part
+  for last if an early slice can deliver it.
+
+## Keeper handoff
+
+Before material execution, run \`loom project ready\` to freeze a digest, then ask a fresh Agent to
+run \`loom keeper prompt\` and \`loom keeper record\`. If the Keeper returns only minor gaps (3 or fewer),
+fixing them and running \`loom project ready\` again auto-passes without another Keeper round.
+`;
+
+export const STRUCTURE_TEMPLATE = `# Project structure
+
+> Where things live in this project. The Agent reads this before creating or moving files.
+> Update this when the structure changes. Delete sections that do not apply. Add sections
+> that do. This is a map, not a prescription — each project declares its own conventions.
+
+## Source code
+
+Where implementation files go. Example: \`src/\` for application logic, \`src/core/\` for
+domain logic, \`src/cli/\` for command-line interface.
+
+## Tests
+
+Where test files go and how they mirror source structure. Example: \`tests/\` mirroring
+\`src/\` layout, or \`__tests__/\` co-located with source.
+
+## Documents
+
+Where project documentation goes (excluding \`.loom/\` which is LOOM state). Example:
+\`docs/\` for user-facing docs, \`README.md\` at root for entry.
+
+## Configuration and build
+
+Where build configs, CI definitions, and dependency manifests go. Example:
+\`package.json\`, \`.github/workflows/\`, \`tsconfig.json\`.
+
+## Assets and fixtures
+
+Where static assets, test fixtures, and data files go. Example: \`assets/\`, \`fixtures/\`,
+\`data/\`.
+
+## Conventions
+
+Any naming or placement conventions the Agent should follow. Example: "one module per
+file", "test files end with \`.test.\`", "config files are JSON not YAML".
+`;
+
+const DESIGN_SECTIONS = {
+  product: ['Outcome and users', 'Problem and operating reality', 'Product principles', 'Scope and non-goals', 'End-to-end behavior', 'Success and failure signals', 'Decisions and open questions', 'Related documents and capabilities'],
+  experience: ['Experience intent', 'Users and contexts', 'Journey and information architecture', 'Interaction states and transitions', 'Content, visual, and accessibility direction', 'Errors, empty states, and recovery', 'Usability verification', 'Related documents and capabilities'],
+  system: ['Responsibility in the whole', 'Inputs, outputs, and boundaries', 'Components and control flow', 'Data and state', 'Interfaces and dependencies', 'Failure, safety, and recovery', 'Implementation constraints', 'Verification strategy', 'Related documents and capabilities'],
+  contract: ['Consumers and purpose', 'Schema or command surface', 'Invariants and permissions', 'Errors and compatibility', 'Examples and fixtures', 'Contract tests', 'Related documents and capabilities'],
+  verification: ['Claims under test', 'Environments and fixtures', 'Acceptance matrix', 'Commands and evidence', 'Negative and failure tests', 'Known blind spots', 'Related documents and capabilities'],
+  operations: ['Operational outcome', 'Preconditions and authority', 'Procedure and commands', 'Safety boundaries', 'Failure detection and recovery', 'Evidence and audit trail', 'Related documents and capabilities'],
+  research: ['Decision to inform', 'Current evidence and unknowns', 'Method and sources', 'Findings', 'Conflicts and limitations', 'Project consequences', 'Follow-up verification', 'Related documents and capabilities'],
+};
+
+export const DESIGN_KINDS = Object.freeze(Object.keys(DESIGN_SECTIONS));
+
+export function designTemplate({ title, kind }) {
+  const sections = DESIGN_SECTIONS[kind];
+  if (!sections) throw new Error(`Unknown design kind: ${kind}`);
+  return `# ${title}\n\n- Kind: ${kind}\n- Status: shaping\n\n${sections.map((section) => `## ${section}\n\nDescribe the project-specific decision, mechanism, boundary, or evidence owned by this section.`).join('\n\n')}\n`;
+}
+
+export const CAPABILITY_TEMPLATE = ({ title }) => `# ${title}
+
+> One dossier covers one recognizable professional field. Keep UI/UX, visual art direction, game
+> design, psychology, biology, security, and other fields separate when their evidence and judgments
+> differ. Put cross-field synthesis in the affected design document, not in a hybrid capability title.
+> The kernel of a capability is a decision tree with conditional branches that captures how an expert
+> in this field thinks — not a fixed step list or a declarative stance document. It is a resource for
+> the Agent to use, not a script it must follow. When evidence points outside the tree, trust the
+> evidence and update the tree.
+
+## Field identity and boundary
+
+Name the established field, what expertise it contributes, and what belongs to another dossier.
+
+## Project scenario
+
+> This section records the user-confirmed project scenario: which expert situation this project most
+> closely resembles. The Agent must not fill this alone; it requires user confirmation via
+> \`loom capability confirm <slug> --scenario <text>\`.
+
+State the project scenario that determines which branches of the decision tree are active.
+
+## Decision tree
+
+> Each node is a named decision point an expert reaches in this field. Nodes have entry conditions,
+> conditional options, judgment criteria, source citations, counterexamples, and outputs. A node
+> without a source citation is not accepted. A branch without a counterexample is a fixed step in
+> disguise.
+
+### C1: <node name>
+
+- entry_when: <condition under which an expert arrives at this node>
+- options:
+  - A: <option A> → leads_to: <next node or output>
+  - B: <option B> → leads_to: <next node or output>
+- decide_by: <evidence that determines which option to take>
+- source: <which research material or expert narrative supports this node>
+- counterexample: <a situation where an expert would NOT walk this path>
+- output: <what this node produces — typically a design decision>
+
+### C2: <node name>
+
+<repeat the structure above for each decision node>
+
+## Stance and rejected defaults
+
+> The stance is subordinate to the decision tree. It records what this project refuses and why, but
+> the decision tree carries the thinking process.
+
+State what this project will do, why, the important tradeoffs, and which common or generic approaches it
+will deliberately refuse.
+
+## Failure signals
+
+Describe characteristic weak, generic, or harmful outcomes and the observable evidence that distinguishes
+a strong result. Experts know when they have gone wrong — record those signals here.
+
+## Relationships without merger
+
+Link adjacent capability dossiers and explain the tension or handoff. Do not absorb their expertise here.
+`;
+
+export const RESEARCH_GUIDE = `# Research guide for this capability
+
+> This file guides what to write in the research/ directory. Delete it when you have added your own
+> research materials. \`loom capability synthesize\` reads all .md files in this directory (except this
+> guide) and expects them to contain expert narratives, case studies, or methodology sources that
+> inform the decision tree.
+
+## What to write
+
+Create one .md file per research source. Each file should answer: **how does an expert in this field
+think through the problems this project faces?**
+
+Good research materials include:
+- Expert narratives: how a practitioner describes their own decision process
+- Case studies: real projects where this field's decisions mattered, and what happened
+- Methodology sources: established frameworks, heuristics, or principles from the field
+- Failure accounts: what went wrong when the field's judgment was absent or ignored
+
+Bad research materials (will produce weak decision trees):
+- Generic textbook summaries with no project-specific relevance
+- Tool documentation or API references (those are not professional judgment)
+- Marketing copy or opinion pieces without evidence
+
+## File format
+
+Name files descriptively: \`expert-decision-process.md\`, \`case-study-X.md\`, \`failure-account-Y.md\`.
+Each file should be 1-3 paragraphs of substantive content. Include the source at the top:
+
+\`\`\`markdown
+# <descriptive title>
+
+Source: <book, article, interview, observation, or personal experience>
+
+<content: how the expert thinks, what they decided, what evidence they used, what happened>
+\`\`\`
+
+## How this feeds synthesize
+
+\`loom capability synthesize\` checks that:
+1. At least one .md file exists in research/ (besides this guide)
+2. Every decision tree node (### C1, C2, ...) in capability.md has a \`source:\` field
+3. Every node has a \`counterexample:\` field
+
+The source field in each node should reference which research file supports it. Write research that
+you can cite by name when you build the decision tree.
+`;
+
+export function evalConditionPrompt({ brief, loom, humanChannel = 'available' }) {
+  const environment = environmentProtocol({ humanChannel }).replace('## Environment availability\n\n', '');
+  return loom
+    ? `# Evaluation condition\n\n${brief}\n\n${environment}\n\nWork with all ordinary Agent capabilities and tools. Use LOOM as invisible continuity infrastructure: run \`loom context --human-channel ${humanChannel}\`, maintain its disk state, and never ask the human to operate it. This condition has no extra authority or information.`
+    : `# Evaluation condition\n\n${brief}\n\n${environment}\n\nWork as a normal capable Agent with all ordinary capabilities and tools. LOOM and its files are unavailable in this condition. Use any normal planning or documentation you judge useful.`;
+}
+
+export function evalJudgePrompt() {
+  return `# Blind Evil Eval judge
+
+You receive two anonymized runs in randomized order. Do not infer framework identity. Judge observable
+work, not framework-shaped filenames or document volume. Cite evidence for every score. Compare intent
+fidelity, question value, whole-project coverage, professional capability depth, buildability, continuity
+after forced resets, implementation evidence, user burden, and cost/time. Penalize unnecessary ceremony,
+questions that do not change decisions, and documentation that a fresh Agent cannot use. Swap order and
+judge again; mark order-sensitive conclusions unstable. Attribute missing files or path failures to a run
+only after the anonymized packet passed its relative-layout and declared-test preflight. A system wins only if its benefit survives equal
+model, tools, workspace, user facts, reset points, and budget.`;
+}
+
+export function promptCatalog() {
+  const placeholderState = {
+    project: { status: '<project-status>' },
+    understanding: {
+      confirmed: [],
+      assumptions: [{ id: '<assumption-id>', text: '<assumption>', status: 'active' }],
+      unresolved: [{ id: '<question-id>', question: '<material uncertainty>', impact: 'high', status: 'open' }],
+    },
+    keeper: { status: 'not_run', attempts: [] },
+  };
+  const revisionState = {
+    ...placeholderState,
+    keeper: {
+      status: 'needs_revision',
+      attempts: [{
+        verdict: 'needs_revision',
+        run_id: '<fresh-run-id>',
+        summary: '<why the handoff cannot start>',
+        gaps: ['<concrete gap>'],
+        evidence: ['<observable evidence>'],
+      }],
+    },
+  };
+  return {
+    purpose: 'Complete inventory of LOOM cognitive messages. Validation errors and JSON status payloads enforce state but are not Agent prompts.',
+    layers: {
+      stable_core: AGENT_CORE,
+      environment_adaptation_available: environmentProtocol({ humanChannel: 'available' }),
+      environment_adaptation_unavailable: environmentProtocol({ humanChannel: 'unavailable' }),
+      runtime_protocol: RUNTIME_PROTOCOL,
+      execution_protocol: EXECUTION_PROTOCOL,
+      project_state: shapingContext({ state: placeholderState, taskSummary: { total: 0, done: 0, open: 0, blocked: 0, active: null }, capabilityNames: [], designNames: [] }),
+      project_state_after_keeper_failure: shapingContext({ state: revisionState, taskSummary: { total: 1, done: 0, open: 1, blocked: 0, active: null }, capabilityNames: ['<field>'], designNames: ['<system>.md'] }),
+      keeper_review_of_prior_failure: shapingContext({ state: revisionState, taskSummary: { total: 1, done: 0, open: 1, blocked: 0, active: null }, capabilityNames: ['<field>'], designNames: ['<system>.md'], forKeeper: true }),
+      current_task: '## Active Task\n\n<exact Task JSON including acceptance, implements, capability_hooks, and covers if present>\n\n---\n\n## Task context: <path from Task.reads>\n\n<exact file content>\n\n(repeated for every read path)\n\n---\n\n## Capability decision points\n\n<extracted decision-tree nodes referenced by capability_hooks, with options, criteria, sources, and counterexamples>',
+      on_demand_map: '## On-demand project context\n\n- Decision history: .loom/DECISIONS.md (read when correction or lineage matters; records what changed and why)\n- Design: .loom/design/<document>.md\n- Professional capability: .loom/capabilities/<field>/capability.md\n- Project structure: .loom/STRUCTURE.md (read before creating or moving files)',
+      keeper_context: '## Decision history (...)\n\n<exact DECISIONS.md>\n\n---\n\n## Work map summary\n\n<summary and first executable Task>\n\n---\n\n## Design document: <name>\n\n<exact content>\n\n---\n\n## Capability dossier: <name>\n\n<exact content>',
+    },
+    workspace_anchor: AGENT_ANCHOR,
+    templates: {
+      project_index: PROJECT_TEMPLATE,
+      project_structure: STRUCTURE_TEMPLATE,
+      design_documents: Object.fromEntries(DESIGN_KINDS.map((kind) => [kind, designTemplate({ title: `<${kind}-title>`, kind })])),
+      professional_capability: CAPABILITY_TEMPLATE({ title: '<recognizable-professional-field>' }),
+      decision_history: '# Decision History\n\nCurrent truth belongs in PROJECT.md and linked design documents. This file preserves consequential superseding decisions.',
+    },
+    keeper: keeperProtocol({ attemptNumber: '<attempt-number>', preparedDigest: '<prepared-digest>' }),
+    evaluation: {
+      baseline_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: false }),
+      loom_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: true }),
+      unattended_baseline_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: false, humanChannel: 'unavailable' }),
+      unattended_loom_condition: evalConditionPrompt({ brief: '<identical-raw-brief>', loom: true, humanChannel: 'unavailable' }),
+      blind_judge: evalJudgePrompt(),
+    },
+    composition: {
+      normal_resume: ['stable_core', 'environment_adaptation', 'runtime_protocol', 'project_state', 'PROJECT.md', 'on-demand document and capability map'],
+      active_task: ['normal_resume', 'execution_protocol', 'active Task JSON', 'exact files in Task.reads'],
+      keeper_handoff: ['keeper', 'normal_resume', 'DECISIONS.md', 'Work Map summary and first executable Task', 'all design documents', 'all professional capability dossiers'],
+    },
+  };
+}