@haaaiawd/loom 2.0.1 → 2.1.0

package/cli/src/protocol.js

@@ -12,6 +12,21 @@ answers, update the emerging whole and ask again only where important uncertaint
 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
@@ -19,7 +34,7 @@ CLI silently and never make the human maintain LOOM files or state.
 
 ## Shape the whole before material execution
 
-Maintain four distinct layers:
+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
@@ -31,8 +46,18 @@ Maintain four distinct layers:
    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
@@ -44,9 +69,21 @@ be observed.
 
 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.
+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
@@ -54,10 +91,36 @@ fields, preserve each field's identity and synthesize them explicitly in the aff
 
 ## 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.
+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,
@@ -70,66 +133,100 @@ answers and decisions -> update design and capability maps -> repeat while mater
 
 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.
+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 ->
-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 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, exact done_when criteria, boundaries, dependencies, reads, expected
-   touches, progress, next action, and existing evidence. Read every injected Task context file.
-2. 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.
-3. 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 exact done_when criterion has reproducible
-  evidence. 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.
-
-Do not narrate this protocol to the human unless it helps them understand a decision, risk, or handoff.`;
+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.`;
+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}`;
@@ -184,7 +281,41 @@ You are a fresh Agent with no access to the shaping conversation. Do not repair
 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:
+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
@@ -202,7 +333,10 @@ This is Keeper attempt ${attemptNumber || '<unknown>'}. The frozen prepared dige
 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:
+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
 {
@@ -213,6 +347,7 @@ receives the reason and closure evidence without interpretation loss:
   "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>"
     }
@@ -225,13 +360,15 @@ Record the result with \`loom keeper record --json-file <result.json>\`. Use \`p
 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.`;
+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
 
@@ -256,16 +393,98 @@ decision surface it owns. Complex subsystems should have their own files under \
 
 ## 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.
+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?
 
-## Work map
+## 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
 
-Explain the delivery shape and point to \`.loom/tasks.json\`; do not duplicate volatile Task state here.
+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 = {
@@ -291,53 +510,115 @@ 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 decisions this field changes
+## Project scenario
 
-Identify the consequential questions, design choices, risks, or verification methods that would be
-weaker without this field.
+> 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>\`.
 
-## Project-specific diagnosis
+State the project scenario that determines which branches of the decision tree are active.
 
-Interpret this project's users, constraints, existing evidence, and tensions through this field. Show
-authored judgment rather than a generic overview.
+## Decision tree
 
-## Principles, evidence, and sources
+> 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.
 
-Record specialist principles and opened sources when research is used. State what each source changed,
-where sources disagree, and what remains uncertain.
+### C1: <node name>
 
-## Distinctive stance and rejected defaults
+- 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>
 
-State what this project will do, why, the important tradeoffs, and which common or generic approaches it
-will deliberately refuse.
+### C2: <node name>
 
-## Consequences for design, implementation, and verification
+<repeat the structure above for each decision node>
 
-Translate the field's stance into concrete requirements and link the design documents it affects.
+## Stance and rejected defaults
 
-## Questions that could change the stance
+> The stance is subordinate to the decision tree. It records what this project refuses and why, but
+> the decision tree carries the thinking process.
 
-Keep only unresolved questions whose answers would materially alter this field's contribution.
+State what this project will do, why, the important tradeoffs, and which common or generic approaches it
+will deliberately refuse.
 
-## Failure modes and proof signals
+## Failure signals
 
 Describe characteristic weak, generic, or harmful outcomes and the observable evidence that distinguishes
-a strong result.
+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 function evalConditionPrompt({ brief, loom }) {
+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\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.`;
+    ? `# 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() {
@@ -378,20 +659,23 @@ export function promptCatalog() {
   };
   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,
-      execution_protocol: EXECUTION_PROTOCOL,
+    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>.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',
+      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.',
@@ -400,11 +684,13 @@ export function promptCatalog() {
     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', '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'],
+    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'],
     },
   };