@haaaiawd/loom 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog
 
-## Unreleased
-
-- Added environment-aware clarification through `loom context --human-channel available|unavailable`. Unattended Agents inspect first, research only permitted objective facts, and then use bounded assumptions or blocks rather than fabricating users or substituting web search for intent.
-- Added `--state-dir <outside-workspace-dir>` sidecars for isolated benchmark and sandbox runs. Sidecars preserve virtual `.loom/` Task references without mutating the scored workspace or its `AGENTS.md`.
-- Added equal human-channel controls and unattended condition prompts to Evil Eval scaffolding.
+## Unreleased
+
+## 2.1.2
+
+- Added environment-aware clarification through `loom context --human-channel available|unavailable`. Unattended Agents inspect first, research only permitted objective facts, and then use bounded assumptions or blocks rather than fabricating users or substituting web search for intent.
+- Added `--state-dir <outside-workspace-dir>` sidecars for isolated benchmark and sandbox runs. Sidecars preserve virtual `.loom/` Task references without mutating the scored workspace or its `AGENTS.md`.
+- Added equal human-channel controls and unattended condition prompts to Evil Eval scaffolding.
+- Added explicit capability authority provenance: human selections become confirmed, while Agent selections remain visibly provisional until human confirmation.
+- Required independent Keeper review provenance for a passing handoff; known self-review can no longer be recorded as an independent pass.
+- Added Task integrity enforcement for design links, capability hooks or explicit exemptions, plus declared output existence checks before completion.
+- Added command-specific canonical JSON help and recovery pointers for every structured-write command.
+- Updated generated Agent guidance and both public READMEs so installed and source-checkout invocation paths are unambiguous.
 
 ## 2.1.1
 

package/README.md

@@ -12,9 +12,9 @@
 
 <p align="center"><strong>The human talks to the Agent. LOOM helps the Agent remember, understand, and continue.</strong></p>
 
-LOOM is invisible project-understanding and continuity infrastructure for AI Agents. It supports
-any work that can be materially advanced through code or command-line tools: software, operations,
-research workflows, office automation, data work, and highly personalized projects.
+LOOM is spec-driven continuity, proof, and project understanding infrastructure for AI coding agents.
+It supports any work that can be materially advanced through code or command-line tools: software,
+operations, research workflows, office automation, data work, and highly personalized projects.
 
 The human does not learn a framework or operate a CLI. They describe what they want, answer useful
 questions, disagree, delegate decisions, and watch the work become real. The Agent uses LOOM in the
@@ -65,10 +65,13 @@ understand or verify it independently. `PROJECT.md` maps the whole instead of be
 
 A dossier exists only when specialist knowledge would change a question, design choice,
 implementation, risk, or verification method. Each dossier represents one recognizable professional
-field—such as UI/UX design, visual art direction, game design, psychology, security, or distributed
-systems. Different fields remain separate even when tightly coupled; their synthesis belongs in the
-design document whose decision they jointly shape. A task technique such as triage, ranking, parsing,
-or caching is not allowed to masquerade as the project's entire capability surface.
+field—such as UI/UX design, visual art direction, game design, psychology, security, or distributed
+systems. Different fields remain separate even when tightly coupled; their synthesis belongs in the
+design document whose decision they jointly shape. A task technique such as triage, ranking, parsing,
+or caching is not allowed to masquerade as the project's entire capability surface.
+
+Capability scenario authority remains visible: `--source human` confirms a user-selected scenario;
+`--source agent` records a provisional selection when the human is unavailable.
 
 ### Work Map and Task
 
@@ -82,7 +85,8 @@ Agent:
 - what observable result to create;
 - what proves completion;
 - what must not be damaged;
-- which project and capability documents matter;
+- which project and capability documents matter;
+- which design decision and capability nodes apply, or why they do not;
 - what has happened, what is happening, and what comes next;
 - which evidence already exists and which exact done condition it proves.
 
@@ -144,8 +148,9 @@ loom design add product --title "Product definition" --kind product
 loom design add local-analysis --title "Local analysis system" --kind system
 loom design add acceptance --title "Vertical-slice verification" --kind verification
 loom capability add ui-ux-design --title "UI/UX design"
-loom capability add behavioral-psychology --title "Behavioral psychology"
-loom task plan --json-file initial-work-map.json
+loom capability add behavioral-psychology --title "Behavioral psychology"
+loom capability confirm behavioral-psychology --scenario "<project-specific expert situation>" --source human
+loom task plan --json-file initial-work-map.json
 loom project ready
 ```
 
@@ -155,7 +160,11 @@ At the transition to material execution, open a fresh Agent thread and give it o
 Run loom keeper prompt in this project and follow it. Decide whether you can responsibly start.
 ```
 
-If Keeper returns `needs_revision` or `blocked`, those exact gaps reappear in `loom context`. The Agent
+Keeper pass JSON records `review.mode: "independent"`, a reviewer identity, and concrete isolation evidence.
+Known self-review cannot pass; if the host cannot isolate a fresh Agent, use `loom keeper skip` with the
+reason so reduced confidence stays visible.
+
+If Keeper returns `needs_revision` or `blocked`, those exact gaps reappear in `loom context`. The Agent
 repairs the relevant project, design, capability, or Task source, prepares a changed digest, and opens a
 different fresh Keeper. If the host cannot create a subagent, the human can open a new window and use the
 same sentence. After the one-time handoff passes, the execution Agent starts and maintains Tasks normally:
@@ -175,17 +184,19 @@ Completion is deliberately explicit:
 
 ```json
 {
-  "evidence": ["npm test: 20 passed, 0 failed"],
+  "evidence": ["npm test: 21 passed, 0 failed"],
   "acceptance_results": [
     {
       "criterion": "The exact acceptance criterion from the Task.",
-      "evidence": ["The command, artifact, or observation that proves this criterion."]
+      "evidence": "The command, artifact, or observation that proves this criterion."
     }
   ]
 }
 ```
 
-Run `loom --help` for the complete command surface. Run `loom check` for structural health. Run
+Run `loom --help` for the complete command surface. Structured-write commands expose canonical payloads
+through command-specific help such as `loom record --help` and `loom task done --help`. Run `loom check`
+for structural health. Run
 `loom prompts` to print every cognitive message LOOM can inject: the stable collaboration core,
 runtime protocol, dynamic state layer, all document templates, Keeper prompt, eval conditions, judge
 prompt, and their composition order. See the [prompt and message catalog](docs/PROMPT_CATALOG.md).
@@ -215,7 +226,7 @@ user burden, time, and token cost are penalized alongside quality. See [EVIL_EVA
 npm test
 ```
 
-The v2 test suite (20 end-to-end tests) exercises the complete loop, including a 250-Task Work Map, context selection,
+The v2 test suite exercises the complete loop, including a 250-Task Work Map, context selection,
 superseding decisions, scalable design documents, professional-field separation, capability compilation with
 source-citation validation, multi-attempt Keeper revision with auto-pass, stale digest and duplicate-run
 rejection, exact-file Task start, block/reopen including disproven completion, per-acceptance-criterion evidence,

package/README.zh-CN.md

@@ -12,7 +12,7 @@
 
 <p align="center"><strong>人只需要和 Agent 自然聊天。LOOM 在背后帮助 Agent 记住、理解，并继续工作。</strong></p>
 
-LOOM 是为 AI Agent 准备的、隐形的项目理解与连续性基础设施。凡是能够通过代码或命令行获得实质推进的工作——软件、运维、科研流程、办公自动化、数据处理，以及高度个性化的项目——都在它的能力边界内。
+LOOM 是为 AI 编码 Agent 准备的 spec 驱动连续性、证据与项目理解基础设施。凡是能够通过代码或命令行获得实质推进的工作——软件、运维、科研流程、办公自动化、数据处理，以及高度个性化的项目——都在它的能力边界内。
 
 用户不需要学习一套框架，也不需要亲自操作 CLI。他只需要描述想要什么、回答真正有价值的问题、提出异议、把某些判断交给 Agent，然后看着结果逐渐成为现实。Agent 在后台使用 LOOM，让项目全貌在上下文压缩、会话切换和长期施工中保持连续。
 
@@ -115,19 +115,22 @@ loom record --json-file understanding-update.json
 loom design add product --title "Product definition" --kind product
 loom design add local-analysis --title "Local analysis system" --kind system
 loom design add acceptance --title "Vertical-slice verification" --kind verification
-loom capability add ui-ux-design --title "UI/UX design"
-loom capability add behavioral-psychology --title "Behavioral psychology"
-loom task plan --json-file initial-work-map.json
-loom project ready
-```
+loom capability add ui-ux-design --title "UI/UX design"
+loom capability add behavioral-psychology --title "Behavioral psychology"
+loom capability confirm behavioral-psychology --scenario "<项目特定的专家情境>" --source human
+loom task plan --json-file initial-work-map.json
+loom project ready
+```
 
 准备从项目成型进入实质施工时，打开一个全新的 Agent 线程，只给它一句简短指令：
 
 ```text
-Run loom keeper prompt in this project and follow it. Decide whether you can responsibly start.
-```
-
-如果 Keeper 返回 `needs_revision` 或 `blocked`，这些具体缺口会重新出现在 `loom context` 中。Agent 修复对应的项目、设计、能力或 Task 源文件，生成发生变化的新 digest，再打开另一个全新的 Keeper。若宿主不支持子代理，用户可以新开一个窗口并使用同一句提示词。
+Run loom keeper prompt in this project and follow it. Decide whether you can responsibly start.
+```
+
+Keeper 通过记录必须包含 `review.mode: "independent"`、审查者标识和具体的隔离证据。已知的自我审查不能通过；如果宿主无法隔离出全新的 Agent，应使用 `loom keeper skip` 并写明原因，让置信度降低这件事保持可见。
+
+如果 Keeper 返回 `needs_revision` 或 `blocked`，这些具体缺口会重新出现在 `loom context` 中。Agent 修复对应的项目、设计、能力或 Task 源文件，生成发生变化的新 digest，再打开另一个全新的 Keeper。若宿主不支持子代理，用户可以新开一个窗口并使用同一句提示词。
 
 一次性交接通过后，施工 Agent 正常启动并维护 Task：
 
@@ -146,17 +149,17 @@ loom task done TASK-001 --json-file evidence.json
 
 ```json
 {
-  "evidence": ["npm test: 20 passed, 0 failed"],
+  "evidence": ["npm test: 21 passed, 0 failed"],
   "acceptance_results": [
-    {
-      "criterion": "The exact acceptance criterion from the Task.",
-      "evidence": ["The command, artifact, or observation that proves this criterion."]
-    }
-  ]
-}
-```
-
-运行 `loom --help` 查看全部命令，运行 `loom check` 检查结构健康度。`loom prompts` 会打印 LOOM 可能注入的全部认知消息：稳定协作核心、运行时协议、动态状态层、所有文档模板、Keeper 提示词、Eval 条件、裁判提示词，以及它们的组合顺序。详见[提示词与消息目录](docs/PROMPT_CATALOG.md)。
+    {
+      "criterion": "The exact acceptance criterion from the Task.",
+      "evidence": "The command, artifact, or observation that proves this criterion."
+    }
+  ]
+}
+```
+
+运行 `loom --help` 查看全部命令。所有结构化写入命令都通过命令级帮助给出可直接使用的标准 JSON，例如 `loom record --help` 和 `loom task done --help`；校验失败也会保留具体错误，并指向对应帮助。运行 `loom check` 检查结构健康度。`loom prompts` 会打印 LOOM 可能注入的全部认知消息：稳定协作核心、运行时协议、动态状态层、所有文档模板、Keeper 提示词、Eval 条件、裁判提示词，以及它们的组合顺序。详见[提示词与消息目录](docs/PROMPT_CATALOG.md)。
 
 ## LOOM 刻意删除了什么
 
@@ -176,7 +179,7 @@ LOOM 2 用一个自适应理解环、可扩展的设计文档图、彼此独立
 npm test
 ```
 
-v2 测试套件（20 个端到端测试）覆盖完整闭环，包括 250 个 Task 的 Work Map、上下文选择、决策替代历史、可扩展设计文档、专业领域分离、能力编译（含 source 引用校验）、多轮 Keeper 修订（含 auto-pass）、陈旧 digest 与重复 run 拒绝、精确文件级 Task 启动、阻塞与重开（包括完成证据被推翻）、逐 acceptance 条件证据、交付物覆盖、决策记录与受影响 Task 警告，以及 Evil Eval 的控制变量。详见[完整 UX 与闭环规范](docs/UX_FLOW.md)。
+v2 测试套件（21 个端到端测试）覆盖完整闭环，包括 250 个 Task 的 Work Map、上下文选择、决策替代历史、可扩展设计文档、专业领域分离、能力编译（含 source 引用校验和人类/Agent 权限来源）、Task 设计与能力关联、声明产物存在性、多轮 Keeper 修订（含独立审查来源与 auto-pass）、陈旧 digest 与重复 run 拒绝、精确文件级 Task 启动、阻塞与重开（包括完成证据被推翻）、逐 acceptance 条件证据、交付物覆盖、决策记录与受影响 Task 警告，以及 Evil Eval 的控制变量。详见[完整 UX 与闭环规范](docs/UX_FLOW.md)。
 
 ## 文档
 

package/cli/bin/loom.js

@@ -67,7 +67,7 @@ function jsonFile() {
   }
 }
 
-function help() {
+function help() {
   return `loom — continuity infrastructure for Agents
 
 The human talks naturally to the Agent. The Agent uses these commands silently.
@@ -105,7 +105,8 @@ Preserve understanding
   loom capability list|get <slug>
   loom capability research <slug> --field <text>      (creates research/_guide.md — add .md files there)
   loom capability synthesize <slug>                   (builds decision tree from research, validates sources)
-  loom capability confirm <slug> --scenario <text>    (user confirms which expert scenario applies)
+  loom capability confirm <slug> --scenario <text> --source human|agent
+                                        — human confirms, or Agent records a provisional selection
   loom capability status <slug>
 
 Map the delivery surface
@@ -137,16 +138,73 @@ Evaluate LOOM itself
 Use \`--state-dir <outside-workspace-dir>\` on every command to keep LOOM state in an isolated sidecar
 (for example, a benchmark runner's per-run state directory). Sidecar initialization never edits AGENTS.md.
 
-Use JSON files for structured writes so long content and shell quoting remain auditable.
-Task completion JSON includes evidence plus either acceptance_results[] (one per acceptance criterion,
-each with concrete evidence) or checks[] (one per done_when criterion, for legacy tasks).`;
-}
+Use \`loom <command> --help\` or \`loom help <topic>\` for canonical JSON payloads. Topics:
+  record, decision, task-plan, task-update, task-block, task-done, keeper-record, eval-scaffold
+
+Use JSON files for structured writes so long content and shell quoting remain auditable.
+Task completion JSON includes evidence plus either acceptance_results[] (one per acceptance criterion,
+each with concrete evidence) or checks[] (one per done_when criterion, for legacy tasks).`;
+}
+
+const STRUCTURED_HELP = {
+  record: {
+    usage: 'loom record --json-file <update.json>',
+    example: {
+      confirmed: ['A fact confirmed by the human or workspace.'],
+      assumptions: [{ text: 'A bounded, reversible Agent assumption.', source: 'agent' }],
+      unresolved: [{ question: 'A consequential question still open?', impact: 'high' }],
+      decisions: [{ title: 'Decision title', decision: 'Current decision.', rationale: 'Why it follows.', supersedes: [], affects: ['.loom/PROJECT.md'] }],
+    },
+  },
+  decision: {
+    usage: 'loom decision --json-file <decision.json>',
+    example: { summary: 'What changed and why.', changes: ['.loom/design/system.md', 'src/system.js'], affected_tasks: ['TASK-001'] },
+  },
+  'task-plan': {
+    usage: 'loom task plan --json-file <tasks.json>',
+    example: { tasks: [{ title: 'Create one verifiable result', outcome: 'A concrete artifact behaves as specified.', acceptance: [{ criterion: 'Observable condition', verify_by: 'Exact command or review method', evidence: '' }], boundaries: ['Does not change unrelated behavior'], depends_on: [], reads: ['.loom/PROJECT.md', '.loom/design/system.md'], touches: ['src/result.js'], implements: '.loom/design/system.md#Decision', capability_hooks: [{ node: 'field#C1', at: 'decision point', must_produce: 'project-specific choice' }], covers: ['DLV-001'] }] },
+  },
+  'task-update': {
+    usage: 'loom task update <id> --json-file <patch.json>',
+    example: { progress: { completed: ['Finished checkpoint'], current: 'Verifying behavior', next: 'Run the named acceptance check' } },
+  },
+  'task-block': {
+    usage: 'loom task block <id> --json-file <block.json>',
+    example: { reason: 'A concrete dependency or authority is unavailable.', recovery_conditions: ['Observable condition that permits resuming'], evidence: ['Inspection or command output showing the block'] },
+  },
+  'task-done': {
+    usage: 'loom task done <id> --json-file <evidence.json>',
+    example: { evidence: ['Overall reproducible verification result'], acceptance_results: [{ criterion: 'Exact acceptance criterion from the Task', evidence: 'Concrete command, artifact, or observation' }] },
+  },
+  'keeper-record': {
+    usage: 'loom keeper record --json-file <result.json>',
+    example: { run_id: 'fresh-agent-run-001', prepared_digest: '<digest from loom project ready>', verdict: 'passed', review: { mode: 'independent', reviewer_id: 'fresh-agent-001', evidence: 'Host opened a separate Agent without the shaping conversation.' }, summary: 'Build-readiness judgment.', gaps: [], evidence: ['Files and observations supporting the verdict'] },
+  },
+  'eval-scaffold': {
+    usage: 'loom eval scaffold --json-file <scenario.json>',
+    example: { id: 'EVAL-001', title: 'Ambiguous real project', brief: 'Identical brief for both conditions.', hidden_user_facts: ['Fact revealed by the same answer script'], human_channel: 'unavailable', success_criteria: ['Observable result'], context_reset_points: ['after-shaping', 'mid-task'], repetitions: 3 },
+  },
+};
+
+function structuredHelp(topic) {
+  const entry = STRUCTURED_HELP[topic];
+  if (!entry) throw new Error(`Unknown help topic: ${topic}. Available topics: ${Object.keys(STRUCTURED_HELP).join(', ')}`);
+  return `${entry.usage}\n\nCanonical JSON payload:\n${JSON.stringify(entry.example, null, 2)}`;
+}
+
+function activeStructuredHelpTopic() {
+  if (command === 'record' || command === 'decision') return command;
+  if (command === 'task' && ['plan', 'update', 'block', 'done'].includes(subcommand)) return `task-${subcommand}`;
+  if (command === 'keeper' && subcommand === 'record') return 'keeper-record';
+  if (command === 'eval' && subcommand === 'scaffold') return 'eval-scaffold';
+  return '';
+}
 
 try {
   configureRuntime({ stateDir: option('--state-dir') });
   const humanChannel = option('--human-channel');
   if (humanChannel && !['available', 'unavailable'].includes(humanChannel)) throw new Error('--human-channel must be available or unavailable');
-  switch (command) {
+  switch (command) {
     case '--version':
     case '-v': {
       const here = dirname(fileURLToPath(import.meta.url));
@@ -154,11 +212,14 @@ try {
       output(`loom ${pkg.version}`);
       break;
     }
-    case '--help':
+    case '--help':
     case '-h':
     case undefined:
-      output(help());
-      break;
+      output(help());
+      break;
+    case 'help':
+      output(subcommand ? structuredHelp(subcommand) : help());
+      break;
     case 'init':
       output(initProject());
       break;
@@ -169,11 +230,11 @@ try {
     case 'prompts':
       output(promptCatalog());
       break;
-    case 'record':
-      output(recordUnderstanding(jsonFile()));
-      break;
-    case 'decision':
-      output(recordDecision(jsonFile()));
+    case 'record':
+      output(subcommand === '--help' ? structuredHelp('record') : recordUnderstanding(jsonFile()));
+      break;
+    case 'decision':
+      output(subcommand === '--help' ? structuredHelp('decision') : recordDecision(jsonFile()));
       break;
     case 'check': {
       const result = checkProject();
@@ -217,7 +278,7 @@ try {
         output(synthesizeCapability(rest[0]));
       } else if (subcommand === 'confirm') {
         if (!rest[0]) throw new Error('Usage: loom capability confirm <slug> --scenario <text>');
-        output(confirmCapability(rest[0], { scenario: option('--scenario') }));
+        output(confirmCapability(rest[0], { scenario: option('--scenario'), source: option('--source') }));
       } else if (subcommand === 'status') {
         if (!rest[0]) throw new Error('Usage: loom capability status <slug>');
         output(getCapabilityStatus(rest[0]));
@@ -236,8 +297,9 @@ try {
       else throw new Error('Usage: loom deliverable add|list|coverage');
       break;
     }
-    case 'task': {
-      if (subcommand === 'plan') output(importTasks(jsonFile()));
+    case 'task': {
+      if (argv.includes('--help') && ['plan', 'update', 'block', 'done'].includes(subcommand)) output(structuredHelp(`task-${subcommand}`));
+      else if (subcommand === 'plan') output(importTasks(jsonFile()));
       else if (subcommand === 'status') output(taskSummary(loadProject().taskStore.tasks));
       else if (subcommand === 'next') output(getTask());
       else if (subcommand === 'get') {
@@ -261,20 +323,26 @@ try {
       } else throw new Error('Usage: loom task plan|status|next|get|start|update|block|reopen|done');
       break;
     }
-    case 'keeper': {
-      if (subcommand === 'prompt') output(getKeeperPrompt());
+    case 'keeper': {
+      if (argv.includes('--help') && subcommand === 'record') output(structuredHelp('keeper-record'));
+      else if (subcommand === 'prompt') output(getKeeperPrompt());
       else if (subcommand === 'record') output(recordKeeper(jsonFile()));
       else if (subcommand === 'skip') output(skipKeeper(option('--reason')));
       else throw new Error('Usage: loom keeper prompt|record|skip');
       break;
     }
-    case 'eval':
-      if (subcommand !== 'scaffold') throw new Error('Usage: loom eval scaffold --json-file <scenario.json>');
-      output(scaffoldEval(jsonFile()));
+    case 'eval':
+      if (argv.includes('--help') && subcommand === 'scaffold') output(structuredHelp('eval-scaffold'));
+      else {
+        if (subcommand !== 'scaffold') throw new Error('Usage: loom eval scaffold --json-file <scenario.json>');
+        output(scaffoldEval(jsonFile()));
+      }
       break;
     default:
       throw new Error(`Unknown command: ${command}\n\n${help()}`);
   }
-} catch (error) {
-  fail(error.message);
-}
+} catch (error) {
+  const topic = activeStructuredHelpTopic();
+  const pointer = topic && !argv.includes('--help') ? `\nRun ${STRUCTURED_HELP[topic].usage.replace(/ --json-file .+$/, ' --help').replace(/ <id>/, '')} for a canonical payload.` : '';
+  fail(`${error.message}${pointer}`);
+}

package/cli/src/protocol.js

@@ -75,10 +75,12 @@ list. Each decision node carries an entry condition, options, judgment criteria,
 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
+Build dossiers in four steps: research (collect expert narratives, case studies, and methodology
+sources), synthesize (construct the project-specific decision tree from research), select the scenario,
+and confirm its authority. Use \`loom capability confirm <slug> --scenario <text> --source human\` when
+the user confirms which expert situation applies. Use \`--source agent\` only for a reversible provisional
+selection when the human is unavailable; it remains visibly provisional until a human confirms it.
+\`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
@@ -110,8 +112,12 @@ Each Task records:
 - **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.
+- **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.
+- **implements**: the design decision this Task realizes. If no design applies, use a concrete
+  \`design_exemption\` instead of leaving the relationship implicit.
+- **capability_hooks**: the professional decision-tree nodes activated by this Task. If no dossier
+  applies, use a concrete \`capability_exemption\`; an empty array alone is not a decision.
 - **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
@@ -216,17 +222,34 @@ The human's patience is the project's fuel. Do not let several Tasks pass in sil
   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.
 
+## Handle user feedback before changing code
+
+When the human gives feedback, a fix suggestion, or a direction change, do not jump straight to editing
+code. First judge whether the feedback changes the project's design intent, Task scope, or acceptance
+conditions.
+
+- **Consequential feedback** (changes design, scope, boundaries, or what "done" means): record it with
+  \`loom decision --json-file\` before editing. Update the affected design document or Task. If a done Task
+  is affected, \`loom check\` will warn — reopen it if the change invalidates prior evidence. Then edit
+  code.
+- **Implementation detail** (a small bug, a color tweak, a wording fix, a test that broke): fix it
+  directly. No decision record needed.
+- **When you are not sure**: lean toward recording. A decision record for a small change costs almost
+  nothing; skipping one for a consequential change creates silent drift that is expensive to trace later.
+
 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, before substantial work, and when the human gives feedback or a direction
+change. 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. The installed
+\`loom\` command is the stable project-local invocation. If it is not on PATH in a source checkout, use
+the absolute path to that checkout's \`cli/bin/loom.js\`; do not guess a relative path from this project.`;
 
 function renderKeeperGap(item) {
   if (typeof item === 'string') return `  - ${item}`;
@@ -341,9 +364,14 @@ 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>",
+  "prepared_digest": "<digest-above>",
+  "verdict": "passed | needs_revision | blocked",
+  "review": {
+    "mode": "independent | self",
+    "reviewer_id": "<fresh Agent or current Agent identity>",
+    "evidence": "<how the host isolated this review from shaping context>"
+  },
+  "summary": "<concise handoff judgment>",
   "gaps": [
     {
       "gap": "<missing or contradictory truth>",
@@ -356,8 +384,12 @@ after the gaps are fixed without requiring another Keeper round:
 }
 \`\`\`
 
-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
+Record the result with \`loom keeper record --json-file <result.json>\`. Use \`passed\` only when you are
+a genuinely fresh Agent, could responsibly begin the first Task, and can record \`review.mode\` as
+\`independent\` with concrete isolation evidence.
+If you shaped this project, do not review your own work as independent; ask the host for a fresh Agent,
+or use \`loom keeper skip --reason <concrete limitation>\` when isolation is unavailable. 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\`
@@ -395,7 +427,8 @@ decision surface it owns. Complex subsystems should have their own files under \
 
 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).
+four steps: \`loom capability research\` → \`synthesize\` → \`confirm --source human\` (user-confirmed)
+or \`confirm --source agent\` (explicitly provisional when the human is unavailable).
 
 ## Project structure
 
@@ -521,9 +554,9 @@ Name the established field, what expertise it contributes, and what belongs to a
 
 ## 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>\`.
+> This section records which expert situation the project most closely resembles. Use
+> \`loom capability confirm <slug> --scenario <text> --source human\` for user confirmation. When the
+> human is unavailable, use \`--source agent\`; LOOM records the selection as provisional.
 
 State the project scenario that determines which branches of the decision tree are active.
 

package/cli/src/store.js

@@ -196,7 +196,10 @@ function validateTasks(tasks) {
         if (acc.evidence !== undefined && typeof acc.evidence !== 'string') throw new Error(`${task.id} acceptance evidence must be a string`);
       }
     }
-    if (task.implements !== undefined && typeof task.implements !== 'string') throw new Error(`${task.id} implements must be a string referencing a design decision`);
+    if (task.implements !== undefined && typeof task.implements !== 'string') throw new Error(`${task.id} implements must be a string referencing a design decision`);
+    if (task.design_exemption !== undefined && (typeof task.design_exemption !== 'string' || (task.design_exemption && task.design_exemption.length < 10))) throw new Error(`${task.id} design_exemption must be a concrete reason`);
+    if (task.capability_exemption !== undefined && (typeof task.capability_exemption !== 'string' || (task.capability_exemption && task.capability_exemption.length < 10))) throw new Error(`${task.id} capability_exemption must be a concrete reason`);
+    if (task.integrity_version !== undefined && task.integrity_version !== 1) throw new Error(`${task.id} integrity_version is unsupported`);
     if (task.capability_hooks !== undefined) {
       if (!Array.isArray(task.capability_hooks)) throw new Error(`${task.id} capability_hooks must be an array`);
       for (const hook of task.capability_hooks) {
@@ -404,18 +407,21 @@ export function synthesizeCapability(slug, root = findRoot()) {
   return { slug, status: 'synthesized', nodes: nodes.length, materials: materials.length };
 }
 
-export function confirmCapability(slug, options = {}, root = findRoot()) {
-  if (!options.scenario || options.scenario.length < 20) throw new Error('Confirm requires --scenario <text> (at least 20 characters describing which expert situation this project most resembles)');
+export function confirmCapability(slug, options = {}, root = findRoot()) {
+  if (!options.scenario || options.scenario.length < 20) throw new Error('Confirm requires --scenario <text> (at least 20 characters describing which expert situation this project most resembles)');
+  if (!['human', 'agent'].includes(options.source)) throw new Error('Capability confirmation requires explicit provenance: --source human|agent');
   const { paths } = loadProject(root);
   const dir = join(paths.capabilities, slug);
   if (!existsSync(dir)) throw new Error(`Capability not found: ${slug}`);
   const statusPath = join(dir, 'status.json');
   if (!existsSync(statusPath)) throw new Error(`Capability ${slug} is not a research-directory dossier`);
   const status = readJson(statusPath, 'status.json');
-  if (status.status !== 'synthesized') throw new Error(`Capability ${slug} must be synthesized before confirmation. Run loom capability synthesize ${slug} first.`);
-  status.scenario = options.scenario;
-  status.status = 'confirmed';
-  status.confirmed_at = now();
+  if (!['synthesized', 'provisional'].includes(status.status)) throw new Error(`Capability ${slug} must be synthesized before confirmation. Run loom capability synthesize ${slug} first.`);
+  status.scenario = options.scenario;
+  status.source = options.source;
+  status.status = options.source === 'human' ? 'confirmed' : 'provisional';
+  status.selected_at = now();
+  status.confirmed_at = options.source === 'human' ? now() : '';
   status.updated_at = now();
   atomicJson(statusPath, status);
   const capabilityPath = join(dir, 'capability.md');
@@ -429,7 +435,7 @@ export function confirmCapability(slug, options = {}, root = findRoot()) {
     const updated = content.replace(/## Project scenario\n[\s\S]*?\n## /, `${prefix}${blockquoteText}\n${options.scenario}\n${suffix}`);
     writeFileSync(capabilityPath, updated, 'utf8');
   }
-  return { slug, status: 'confirmed', scenario: options.scenario };
+  return { slug, status: status.status, scenario: options.scenario, source: options.source };
 }
 
 export function getCapabilityStatus(slug, root = findRoot()) {
@@ -533,9 +539,12 @@ export function importTasks(payload, root = findRoot()) {
       boundaries: raw.boundaries || [],
       depends_on: raw.depends_on || [],
       reads: raw.reads || ['.loom/PROJECT.md'],
-      touches: raw.touches || [],
-      implements: raw.implements || '',
-      capability_hooks: raw.capability_hooks || [],
+      touches: raw.touches || [],
+      implements: raw.implements || '',
+      design_exemption: raw.design_exemption || '',
+      capability_hooks: raw.capability_hooks || [],
+      capability_exemption: raw.capability_exemption || '',
+      integrity_version: 1,
       covers: raw.covers || [],
       status: 'open',
       progress: raw.progress || { completed: [], current: '', next: '' },
@@ -566,18 +575,48 @@ export function getTask(id, root = findRoot()) {
   return task;
 }
 
-function nextTask(tasks) {
+function nextTask(tasks) {
   const active = tasks.find((task) => task.status === 'active');
   if (active) return active;
   const done = new Set(tasks.filter((task) => task.status === 'done').map((task) => task.id));
   return tasks.find((task) => task.status === 'open' && task.depends_on.every((id) => done.has(id))) || null;
-}
-
-export function updateTask(id, patch, root = findRoot()) {
+}
+
+function taskIntegrityFindings(task, designs, capabilities) {
+  if (task.integrity_version !== 1) return [];
+  const findings = [];
+  if (designs.length && !task.implements?.trim() && !task.design_exemption?.trim()) findings.push('is missing implements or design_exemption');
+  if (capabilities.length && !(task.capability_hooks || []).length && !task.capability_exemption?.trim()) findings.push('is missing capability_hooks or capability_exemption');
+  return findings;
+}
+
+function assertTaskIntegrityClassification(task, root) {
+  const findings = taskIntegrityFindings(task, listDesigns(root), listCapabilities(root));
+  if (findings.length) throw new Error(`${task.id} has unresolved integrity classification:\n- ${findings.join('\n- ')}\nAdd the relevant link or a concrete exemption before execution.`);
+}
+
+function declaredArtifactPath(paths, ref) {
+  const normalized = ref.replaceAll('\\', '/');
+  if (isAbsolute(normalized) || normalized.startsWith('/') || normalized.includes('..')) throw new Error(`Unsafe declared artifact path: ${ref}`);
+  const fromLoom = normalized === '.loom' || normalized.startsWith('.loom/');
+  const base = fromLoom ? paths.loom : paths.root;
+  const relativeRef = fromLoom ? normalized.slice('.loom'.length).replace(/^\//, '') : normalized;
+  const absolute = resolve(base, relativeRef);
+  const prefix = `${base}${process.platform === 'win32' ? '\\' : '/'}`;
+  if (!absolute.startsWith(prefix) && absolute !== base) throw new Error(`Unsafe declared artifact path: ${ref}`);
+  return absolute;
+}
+
+function missingTaskOutputs(task, paths) {
+  if (task.integrity_version !== 1) return [];
+  return task.touches.filter((ref) => !existsSync(declaredArtifactPath(paths, ref)));
+}
+
+export function updateTask(id, patch, root = findRoot()) {
   const { paths, taskStore } = loadProject(root);
   const task = taskStore.tasks.find((item) => item.id === id);
   if (!task) throw new Error(`Task not found: ${id}`);
-  const allowed = ['title', 'outcome', 'acceptance', 'done_when', 'boundaries', 'depends_on', 'reads', 'touches', 'implements', 'capability_hooks', 'covers', 'progress', 'evidence'];
+  const allowed = ['title', 'outcome', 'acceptance', 'done_when', 'boundaries', 'depends_on', 'reads', 'touches', 'implements', 'design_exemption', 'capability_hooks', 'capability_exemption', 'covers', 'progress', 'evidence'];
   for (const key of Object.keys(patch)) if (!allowed.includes(key)) throw new Error(`Task field cannot be updated: ${key}`);
   Object.assign(task, patch, { updated_at: now() });
   validateTasks(taskStore.tasks);
@@ -628,12 +667,13 @@ export function reopenTask(id, options = {}, root = findRoot()) {
   return task;
 }
 
-export function startTask(id, root = findRoot()) {
-  const { paths, state, taskStore } = loadProject(root);
+export function startTask(id, root = findRoot()) {
+  const { paths, state, taskStore } = loadProject(root);
   if (!['passed', 'skipped'].includes(state.keeper.status)) throw new Error('The one-time Keeper handoff has not passed. Run loom keeper prompt.');
   if (taskStore.tasks.some((task) => task.status === 'active')) throw new Error('Another Task is already active');
-  const task = taskStore.tasks.find((item) => item.id === id);
-  if (!task || task.status !== 'open') throw new Error(`${id} is not open`);
+  const task = taskStore.tasks.find((item) => item.id === id);
+  if (!task || task.status !== 'open') throw new Error(`${id} is not open`);
+  assertTaskIntegrityClassification(task, root);
   const done = new Set(taskStore.tasks.filter((item) => item.status === 'done').map((item) => item.id));
   const missing = task.depends_on.filter((dep) => !done.has(dep));
   if (missing.length) throw new Error(`${id} has incomplete dependencies: ${missing.join(', ')}`);
@@ -648,12 +688,15 @@ export function startTask(id, root = findRoot()) {
   return task;
 }
 
-export function completeTask(id, payload, root = findRoot()) {
+export function completeTask(id, payload, root = findRoot()) {
   const { paths, state, taskStore } = loadProject(root);
   const task = taskStore.tasks.find((item) => item.id === id);
   if (!task) throw new Error(`Task not found: ${id}`);
-  if (task.status !== 'active') throw new Error(`${id} is not active`);
-  if (!Array.isArray(payload.evidence) || !payload.evidence.length) throw new Error('Completing a Task requires concrete evidence');
+  if (task.status !== 'active') throw new Error(`${id} is not active`);
+  if (!Array.isArray(payload.evidence) || !payload.evidence.length) throw new Error('Completing a Task requires concrete evidence');
+  assertTaskIntegrityClassification(task, root);
+  const missingOutputs = missingTaskOutputs(task, paths);
+  if (missingOutputs.length) throw new Error(`${id} declared output does not exist:\n- ${missingOutputs.join('\n- ')}`);
   const hasAcceptance = Array.isArray(task.acceptance) && task.acceptance.length > 0;
   if (hasAcceptance) {
     if (!Array.isArray(payload.acceptance_results)) throw new Error('Completing a Task with acceptance[] requires acceptance_results[]');
@@ -757,11 +800,15 @@ export function getKeeperPrompt(root = findRoot()) {
   return keeperProtocol({ attemptNumber: state.keeper.prepared_attempt, preparedDigest: state.keeper.prepared_digest });
 }
 
-export function recordKeeper(payload, root = findRoot()) {
+export function recordKeeper(payload, root = findRoot()) {
   const { paths, state, taskStore } = loadProject(root);
   if (state.project.status !== 'ready_for_keeper') throw new Error('Keeper result cannot be recorded before loom project ready');
-  if (!['passed', 'needs_revision', 'blocked'].includes(payload.verdict)) throw new Error('Keeper verdict must be passed, needs_revision, or blocked');
-  if (!payload.summary || !Array.isArray(payload.evidence) || !payload.evidence.length) throw new Error('Keeper result requires summary and evidence');
+  if (!['passed', 'needs_revision', 'blocked'].includes(payload.verdict)) throw new Error('Keeper verdict must be passed, needs_revision, or blocked');
+  if (!payload.summary || !Array.isArray(payload.evidence) || !payload.evidence.length) throw new Error('Keeper result requires summary and evidence');
+  if (payload.verdict === 'passed') {
+    if (!payload.review || payload.review.mode !== 'independent') throw new Error('Keeper pass requires an independent review; use review.mode="independent" from a fresh Agent, or loom keeper skip with a concrete reason');
+    if (!payload.review.reviewer_id || payload.review.reviewer_id.length < 6 || !payload.review.evidence || payload.review.evidence.length < 10) throw new Error('Independent Keeper review requires reviewer_id and concrete review evidence');
+  }
   if (payload.evidence.some((item) => typeof item !== 'string' || !item.trim())) throw new Error('Keeper evidence entries must be non-empty strings');
   if (payload.gaps !== undefined && !Array.isArray(payload.gaps)) throw new Error('Keeper gaps must be an array');
   for (const gap of payload.gaps || []) {
@@ -784,7 +831,7 @@ export function recordKeeper(payload, root = findRoot()) {
   if (!payload.prepared_digest || payload.prepared_digest !== state.keeper.prepared_digest) throw new Error('Keeper result prepared_digest does not match the current ready state');
   const currentDigest = projectDigest(paths, taskStore.tasks);
   if (currentDigest !== state.keeper.prepared_digest) throw new Error('Project truth changed after loom project ready; prepare a new Keeper attempt');
-  const attempt = { run_id: payload.run_id, prepared_digest: payload.prepared_digest, verdict: payload.verdict, summary: payload.summary, evidence: payload.evidence, gaps: payload.gaps || [], can_auto_pass: canAutoPass, at: now() };
+  const attempt = { run_id: payload.run_id, prepared_digest: payload.prepared_digest, verdict: payload.verdict, summary: payload.summary, evidence: payload.evidence, gaps: payload.gaps || [], review: payload.review || { mode: 'unverified', reviewer_id: '', evidence: '' }, can_auto_pass: canAutoPass, at: now() };
   state.keeper.attempts.push(attempt);
   state.keeper.status = payload.verdict;
   if (payload.verdict === 'passed') state.project.status = 'build_ready';
@@ -818,7 +865,7 @@ export function recordDecision(payload, root = findRoot()) {
   return { id, summary: payload.summary, changes: payload.changes, affected_tasks: payload.affected_tasks || [] };
 }
 
-export function compileContext(options = {}, root = findRoot()) {
+export function compileContext(options = {}, root = findRoot()) {
   const { paths, state, taskStore } = loadProject(root);
   const designs = listDesigns(root);
   const capabilities = listCapabilities(root);
@@ -834,8 +881,12 @@ export function compileContext(options = {}, root = findRoot()) {
         : state.project.status === 'shaping'
           ? 'Project is still shaping. Confirm the intended result, identify open questions, and build the Work Map before starting material work.'
           : 'No executable Task. Create or update Tasks so the Work Map matches the project goal.';
-  const statusBlock = `## Current LOOM state and recommended action\n\n- Project status: ${state.project.status}\n- Active task: ${summary.active || 'none'}\n- Work map: ${summary.total} total, ${summary.open} open, ${summary.done} done, ${summary.blocked} blocked\n- Design documents: ${designs.length}\n- Capability dossiers: ${capabilities.length}\n- Keeper status: ${state.keeper.status}\n\n**Recommended next action:** ${recommendation}\n\nThis is a recommendation, not a script. Use your judgment; if you choose differently, record the reason in \`.loom/DECISIONS.md\` or the active Task evidence.`;
-  const blocks = [statusBlock, agentProtocol({ humanChannel: options.humanChannel || 'available' }), shapingContext({ state, taskSummary: summary, capabilityNames: capabilities, designNames: designs, forKeeper: Boolean(options.keeper) })];
+  const capabilityStates = capabilities.map((name) => {
+    const statusPath = join(paths.capabilities, name, 'status.json');
+    return existsSync(statusPath) ? `${name} (${readJson(statusPath, 'status.json').status || 'unknown'})` : `${name} (legacy)`;
+  });
+  const statusBlock = `## Current LOOM state and recommended action\n\n- Project status: ${state.project.status}\n- Active task: ${summary.active || 'none'}\n- Work map: ${summary.total} total, ${summary.open} open, ${summary.done} done, ${summary.blocked} blocked\n- Design documents: ${designs.length}\n- Capability dossiers: ${capabilityStates.length ? capabilityStates.join(', ') : 'none'}\n- Keeper status: ${state.keeper.status}\n\n**Recommended next action:** ${recommendation}\n\nThis is a recommendation, not a script. Use your judgment; if you choose differently, record the reason in \`.loom/DECISIONS.md\` or the active Task evidence.`;
+  const blocks = [statusBlock, agentProtocol({ humanChannel: options.humanChannel || 'available' }), shapingContext({ state, taskSummary: summary, capabilityNames: capabilityStates, designNames: designs, forKeeper: Boolean(options.keeper) })];
   blocks.push(`## Project whole (${normalizeRef(paths, paths.project)})\n\n${readFileSync(paths.project, 'utf8')}`);
   if (existsSync(paths.structure)) blocks.push(`## Project structure (${normalizeRef(paths, paths.structure)})\n\n${readFileSync(paths.structure, 'utf8')}`);
   if (options.keeper) {
@@ -889,20 +940,31 @@ function readContextDocument(paths, ref) {
   return readFileSync(absolute, 'utf8');
 }
 
-export function checkProject(root = findRoot()) {
-  const { paths, state, taskStore } = loadProject(root);
-  const errors = [];
-  const warnings = [];
+export function checkProject(root = findRoot()) {
+  const { paths, state, taskStore } = loadProject(root);
+  const designs = listDesigns(root);
+  const capabilities = listCapabilities(root);
+  const errors = [];
+  const warnings = [];
   for (const task of taskStore.tasks) {
     for (const ref of task.reads) {
       try { readContextDocument(paths, ref); } catch (error) { errors.push(`${task.id}: ${error.message}`); }
     }
-    if (task.capability_hooks) {
+    if (task.capability_hooks) {
       for (const hook of task.capability_hooks) {
         const nodeContent = extractCapabilityNode(paths, hook.node);
         if (nodeContent === null) warnings.push(`${task.id} references missing capability node: ${hook.node}`);
-      }
-    }
+      }
+    }
+    if (task.integrity_version === 1) {
+      const classificationFindings = taskIntegrityFindings(task, designs, capabilities);
+      const target = ['active', 'done'].includes(task.status) ? errors : warnings;
+      target.push(...classificationFindings.map((finding) => `${task.id} ${finding}`));
+      if (task.status === 'done') {
+        const missingOutputs = missingTaskOutputs(task, paths);
+        errors.push(...missingOutputs.map((output) => `${task.id} declared output does not exist: ${output}`));
+      }
+    }
     const hasAcceptance = Array.isArray(task.acceptance) && task.acceptance.length > 0;
     const hasDoneWhen = Array.isArray(task.done_when) && task.done_when.length > 0;
     if (!hasAcceptance && hasDoneWhen) warnings.push(`${task.id} uses done_when[] without acceptance[] — consider migrating to structured acceptance for clearer verification`);
@@ -919,23 +981,25 @@ export function checkProject(root = findRoot()) {
     const task = taskStore.tasks.find((item) => item.id === taskId);
     if (task && task.status === 'done') warnings.push(`${taskId} is done but was marked affected by a decision; consider reopening if the change invalidates prior work`);
   }
-  if (!listCapabilities(root).length) warnings.push('No capability dossier exists; acceptable only when specialist judgment would not change the work');
-  if (!listDesigns(root).length) warnings.push('No design document exists; PROJECT.md should remain a concise map of the whole');
+  if (!capabilities.length) warnings.push('No capability dossier exists; acceptable only when specialist judgment would not change the work');
+  if (!designs.length) warnings.push('No design document exists; PROJECT.md should remain a concise map of the whole');
   if (!existsSync(paths.structure)) warnings.push('No STRUCTURE.md exists; declare where files go so the Agent does not guess');
   else if (readFileSync(paths.structure, 'utf8').includes('Where implementation files go. Example:')) warnings.push('STRUCTURE.md still contains template instructions; customize it for this project');
-  for (const name of listDesigns(root)) {
+  for (const name of designs) {
     if (readFileSync(join(paths.design, name), 'utf8').includes('Describe the project-specific decision, mechanism, boundary, or evidence owned by this section.')) warnings.push(`Design document still contains template instructions: ${name}`);
   }
-  for (const name of listCapabilities(root)) {
+  for (const name of capabilities) {
     const content = readFileSync(capabilityPath(paths, name), 'utf8');
     if (capabilityTemplateResidue(content)) warnings.push(`Capability dossier still contains template instructions: ${name}`);
     if (content.includes('### C') && !content.includes('source:')) warnings.push(`Capability dossier has decision tree nodes without source citations: ${name}`);
     const statusPath = join(paths.capabilities, name, 'status.json');
     if (existsSync(statusPath)) {
       const capStatus = readJson(statusPath, 'status.json');
-      if (capStatus.status && capStatus.status !== 'confirmed') warnings.push(`Capability ${name} is ${capStatus.status}, not confirmed; tasks referencing it proceed provisionally`);
-    }
-  }
+      if (capStatus.status && capStatus.status !== 'confirmed') warnings.push(`Capability ${name} is ${capStatus.status}, not confirmed; tasks referencing it proceed provisionally`);
+    }
+  }
+  const latestKeeper = state.keeper.attempts.at(-1);
+  if (state.keeper.status === 'passed' && latestKeeper && latestKeeper.review?.mode !== 'independent') warnings.push('Keeper pass has no independently attested review provenance; prepare a fresh review before relying on it');
   const coverage = checkDeliverableCoverage(root);
   if (coverage.uncovered > 0) warnings.push(`Uncovered deliverables: ${coverage.uncovered_items.map((item) => item.slug).join(', ')}`);
   return { healthy: errors.length === 0, errors, warnings, summary: taskSummary(taskStore.tasks), deliverable_coverage: { total: coverage.total, covered: coverage.covered, uncovered: coverage.uncovered } };

package/design.md

@@ -75,8 +75,12 @@ Cross-field synthesis lives in the design document whose decision it changes. A
 - generic failure modes and observable verification signals;
 - opened sources, what each changed, conflicts, and uncertainty when research is used.
 
-Acquisition can happen quietly. The Agent may briefly name the capability it is obtaining, but does not
-turn research logistics into user workflow.
+Acquisition can happen quietly. The Agent may briefly name the capability it is obtaining, but does not
+turn research logistics into user workflow.
+
+Scenario authority is explicit. `capability confirm --source human` records a confirmed scenario;
+`--source agent` records a provisional, reversible selection when the human is unavailable. Context and
+health checks preserve that distinction instead of allowing an Agent assumption to masquerade as user confirmation.
 
 ### Work Map and Task
 
@@ -94,8 +98,10 @@ Task is the single execution contract:
   "done_when": ["A forced-reset transcript resumes correctly"],
   "boundaries": ["The human never operates LOOM"],
   "depends_on": [],
-  "reads": [".loom/PROJECT.md", ".loom/design/context-system.md", ".loom/capabilities/human-agent-interaction.md", "fixtures/reset-case.md"],
-  "touches": ["cli/src/context.js"],
+  "reads": [".loom/PROJECT.md", ".loom/design/context-system.md", ".loom/capabilities/human-agent-interaction.md", "fixtures/reset-case.md"],
+  "touches": ["cli/src/context.js"],
+  "implements": ".loom/design/context-system.md#Context selection",
+  "capability_hooks": [{ "node": "human-agent-interaction#C1", "at": "selecting reset context" }],
   "status": "active",
   "progress": {
     "completed": [],
@@ -106,17 +112,23 @@ Task is the single execution contract:
 }
 ```
 
-There is at most one active Task. Completion requires a concrete evidence mapping for every exact `done_when`
-criterion. A completed Task can be reopened with a reason when later evidence disproves it. The Task plan may change without
-human approval when the change is a reversible implementation refinement inside the agreed whole; outcome,
-authority, risk, or material cost changes return to the conversation.
+There is at most one active Task. Completion requires a concrete evidence mapping for every exact `done_when`
+criterion. A completed Task can be reopened with a reason when later evidence disproves it. The Task plan may change without
+human approval when the change is a reversible implementation refinement inside the agreed whole; outcome,
+authority, risk, or material cost changes return to the conversation.
+
+New Tasks must make design and capability applicability explicit: use `implements` and `capability_hooks`, or
+record a concrete `design_exemption` / `capability_exemption`. Task start rejects an unclassified active horizon.
+Completion verifies that every declared local `touches` path exists, and `loom check` detects later filesystem drift.
 
 ### One-time Keeper
 
 Keeper is not a recurring role. It is a single isolation test at the transition from shaping to material
 execution. A fresh Agent receives no prior conversation, runs `loom context --keeper`, explains the whole,
 selects a first Task, navigates its design documents and professional capabilities, and identifies concrete evidence. Every attempt binds a unique
-fresh-thread `run_id` to the digest frozen by `project ready`. It may return gaps; summary, evidence and exact gaps
+fresh-thread `run_id` to the digest frozen by `project ready`. A passing record also carries an explicit independent
+review attestation (`review.mode`, reviewer identity, and isolation evidence); known self-review cannot be recorded as
+passed. This is an auditable host assertion, not cryptographic identity proof. It may return gaps; summary, evidence and exact gaps
 are injected into the main Agent's next context. Revision must change project truth or Task definitions before a
 new digest and fresh Keeper run are allowed. Once passed, normal Task evidence replaces further Keeper ceremony.
 
@@ -157,11 +169,12 @@ ready_for_keeper ⇄ fresh Keeper needs_revision or blocked → shaping
 build_ready → building ⇄ Task repair or block or reopen → complete
 ```
 
-`project ready` checks only structural prerequisites: PROJECT.md is no longer a template, at least one design
-document and a Work Map exist, and no high-impact open question remains. Keeper judges semantic build-readiness. Task start requires Keeper
-pass or an explicit recorded skip. An unchanged revision, duplicate Keeper run, wrong digest, or stale prepared
-state is rejected. Imported Tasks start open, `task start` rejects missing or directory-level context reads,
-generic updates cannot change status, and completion requires criterion-by-criterion evidence.
+`project ready` checks only structural prerequisites: PROJECT.md is no longer a template, at least one design
+document and a Work Map exist, and no high-impact open question remains. Keeper judges semantic build-readiness. Task start requires Keeper
+pass or an explicit recorded skip. An unchanged revision, duplicate Keeper run, wrong digest, or stale prepared
+state is rejected. Imported Tasks start open, `task start` rejects missing or directory-level context reads and
+unclassified design/capability applicability, generic updates cannot change status, and completion requires
+criterion-by-criterion evidence plus existence of every declared local output.
 
 ## Context selection
 
@@ -209,7 +222,8 @@ an automated semantic migration can be designed only after real v1 projects reve
 
 - External capability acquisition is represented but not automated yet; the host Agent performs research.
 - Markdown is intentionally human-editable. LOOM validates file existence and structured state, not prose truth.
-- Keeper independence depends on the host creating a fresh thread or window.
+- Keeper independence depends on the host creating a fresh thread or window. LOOM requires and records the
+  host's independent-review attestation but cannot cryptographically prove Agent identity.
 - Evil Eval scaffolding controls experiment design but does not itself launch model runs.
 - A one-time Keeper verifies build-readiness, not the eventual quality of every implementation Task.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haaaiawd/loom",
-  "version": "2.1.1",
-  "description": "LOOM — invisible project understanding and continuity infrastructure for AI agents",
+  "version": "2.1.2",
+  "description": "LOOM — Spec-driven continuity, proof, and project understanding infrastructure for AI coding agents",
   "type": "module",
   "bin": {
     "loom": "cli/bin/loom.js"
@@ -33,11 +33,15 @@
   },
   "keywords": [
     "loom",
-    "agent",
+    "spec-driven",
+    "ai-agent",
+    "ai-coding",
     "continuity",
     "project-understanding",
-    "task-context",
-    "cli"
+    "agent-framework",
+    "context-management",
+    "task-tracking",
+    "llm"
   ],
   "license": "MIT",
   "repository": {