@haaaiawd/loom 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,40 +1,51 @@
-# Changelog
-
+# Changelog
+
 ## 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.
-
-## 2.1.0
-
-- Added a current-state and recommended-action header to `loom context` output. Agents entering a project or resuming after compression now see project status, active task, work-map counts, and a recommended next action before the full protocol. The recommendation is advisory, not a script.
-- Rewrote `AGENTS.md` with explicit LOOM trigger conditions (project entry, context reset, before substantial work, between Tasks) and a standard work rhythm that keeps Agent judgment while making the next step obvious.
-- Integrated Crux integrity-chain review into the Keeper handoff. The Keeper now checks that responsible intent, project promises, design and capability decisions, Work Map, executable behavior, and human feedback loop form an intact chain, and looks for omission, substitution, drift, unsupported leaps, blindness, and ownerless gaps.
-- Added staged visibility and review guidance to the project template and active-Task execution protocol. Tasks should prefer human-visible acceptance evidence, the Agent should show real working things at milestones, run `loom check` and project tests together before declaring a batch done, and prioritize reaching an exciting surface early to sustain the human's momentum.
-- Strengthened capability source validation: `loom capability synthesize` now requires each decision-tree node's `source:` citation to reference a real `.md` file in the dossier's `research/` directory.
-- Added `research/_guide.md` generation in `loom capability research` so Agents know what good research material looks like, what to avoid, and how to cite sources.
-- Added `.loom/STRUCTURE.md` as a fifth project-truth layer declaring where source code, tests, docs, assets, and configuration files live. `loom check` warns when it is missing or still templated.
-- Added `loom decision --json-file` for recording consequential superseding decisions with affected files and tasks. `loom check` warns when a done Task is marked affected by a later decision.
-- Added `acceptance[]` as the primary Task completion structure, pairing `criterion`, `verify_by`, and `evidence`. Legacy `done_when[]` remains supported.
-- Added Keeper auto-pass: when all Keeper gaps are minor and 3 or fewer, fixing them and running `loom project ready` auto-passes without another Keeper round.
-- Added deliverable coverage tracking through `loom deliverable add` and Task `covers` field. `loom check` reports uncovered delivery units.
-- Added `loom capability research → synthesize → confirm` lifecycle with status tracking per dossier.
-- Updated help text with a typical first-pass flow and capability lifecycle sequence.
-
-## 2.0.1
-
-- Added an active-Task execution protocol that restores workspace-aware coding guidance, risk-based testing, restartable progress, criterion-level proof, and conditional commit/PR boundaries after context resets.
-- Strengthened the generated `AGENTS.md` anchor so Agents reload LOOM at project entry, after context loss, and before resumed editing without invoking it before every tool call.
-
-## 2.0.0
-
-- Rebuilt LOOM as invisible Agent infrastructure around project understanding, a scalable design-document graph, separate professional-field dossiers, a broad Work Map, and one active Task.
-- Replaced fixed roles and stages with an adaptive clarification protocol and explicit convergence conditions.
-- Added human-editable project truth, structured continuity state, and superseding decision history.
-- Added context selection that keeps very large Task maps on disk and injects only the active horizon.
-- Added seven adaptable design-document templates and `loom prompts` as a complete live prompt inventory.
-- Reduced Keeper to one independent build-readiness handoff with revision, changed-digest, fresh-run, and stale-state enforcement.
-- Added controlled Evil Eval scaffolding for equal-condition, repeated, reset-heavy blind comparison.
-- Added bilingual English/Chinese release documentation and a flat, minimal visual system with editable loop diagrams.
-- Deliberately stopped automatic mutation of legacy `.loom/v1` projects.
+- 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
+
+- Re-published 2.1.0 content with corrected CHANGELOG line endings.
+
+## 2.1.0
+
+- Added a current-state and recommended-action header to `loom context` output. Agents entering a project or resuming after compression now see project status, active task, work-map counts, and a recommended next action before the full protocol. The recommendation is advisory, not a script.
+- Rewrote `AGENTS.md` with explicit LOOM trigger conditions (project entry, context reset, before substantial work, between Tasks) and a standard work rhythm that keeps Agent judgment while making the next step obvious.
+- Integrated Crux integrity-chain review into the Keeper handoff. The Keeper now checks that responsible intent, project promises, design and capability decisions, Work Map, executable behavior, and human feedback loop form an intact chain, and looks for omission, substitution, drift, unsupported leaps, blindness, and ownerless gaps.
+- Added staged visibility and review guidance to the project template and active-Task execution protocol. Tasks should prefer human-visible acceptance evidence, the Agent should show real working things at milestones, run `loom check` and project tests together before declaring a batch done, and prioritize reaching an exciting surface early to sustain the human's momentum.
+- Strengthened capability source validation: `loom capability synthesize` now requires each decision-tree node's `source:` citation to reference a real `.md` file in the dossier's `research/` directory.
+- Added `research/_guide.md` generation in `loom capability research` so Agents know what good research material looks like, what to avoid, and how to cite sources.
+- Added `.loom/STRUCTURE.md` as a fifth project-truth layer declaring where source code, tests, docs, assets, and configuration files live. `loom check` warns when it is missing or still templated.
+- Added `loom decision --json-file` for recording consequential superseding decisions with affected files and tasks. `loom check` warns when a done Task is marked affected by a later decision.
+- Added `acceptance[]` as the primary Task completion structure, pairing `criterion`, `verify_by`, and `evidence`. Legacy `done_when[]` remains supported.
+- Added Keeper auto-pass: when all Keeper gaps are minor and 3 or fewer, fixing them and running `loom project ready` auto-passes without another Keeper round.
+- Added deliverable coverage tracking through `loom deliverable add` and Task `covers` field. `loom check` reports uncovered delivery units.
+- Added `loom capability research → synthesize → confirm` lifecycle with status tracking per dossier.
+- Updated help text with a typical first-pass flow and capability lifecycle sequence.
+
+## 2.0.1
+
+- Added an active-Task execution protocol that restores workspace-aware coding guidance, risk-based testing, restartable progress, criterion-level proof, and conditional commit/PR boundaries after context resets.
+- Strengthened the generated `AGENTS.md` anchor so Agents reload LOOM at project entry, after context loss, and before resumed editing without invoking it before every tool call.
+
+## 2.0.0
+
+- Rebuilt LOOM as invisible Agent infrastructure around project understanding, a scalable design-document graph, separate professional-field dossiers, a broad Work Map, and one active Task.
+- Replaced fixed roles and stages with an adaptive clarification protocol and explicit convergence conditions.
+- Added human-editable project truth, structured continuity state, and superseding decision history.
+- Added context selection that keeps very large Task maps on disk and injects only the active horizon.
+- Added seven adaptable design-document templates and `loom prompts` as a complete live prompt inventory.
+- Reduced Keeper to one independent build-readiness handoff with revision, changed-digest, fresh-run, and stale-state enforcement.
+- Added controlled Evil Eval scaffolding for equal-condition, repeated, reset-heavy blind comparison.
+- Added bilingual English/Chinese release documentation and a flat, minimal visual system with editable loop diagrams.
+- Deliberately stopped automatic mutation of legacy `.loom/v1` projects.

package/EVIL_EVAL.md

@@ -22,11 +22,11 @@ baseline and does not answer whether LOOM itself adds value.
 
 A scenario records:
 
-- the identical raw brief;
-- workspace setup and immutable snapshot;
-- hidden user facts and a deterministic answer script;
-- human-channel availability (`available` or `unavailable`), identical across conditions;
-- success criteria that judges can observe;
+- the identical raw brief;
+- workspace setup and immutable snapshot;
+- hidden user facts and a deterministic answer script;
+- human-channel availability (`available` or `unavailable`), identical across conditions;
+- success criteria that judges can observe;
 - context-reset points;
 - equal token, time, and tool budgets;
 - at least three repetitions per condition.
@@ -43,18 +43,18 @@ decision.
 4. Change one consequential user answer after the first plan is formed.
 5. Give both conditions equal access to discoverable repository facts.
 6. Penalize unnecessary questions, ceremony, document volume, time, and token cost.
-7. Require an implementation attempt or operational transcript; documents alone cannot win.
-
-## Unattended external benchmarks
-
-An external benchmark such as a terminal-use suite may provide no human response channel. In that condition,
-set `human_channel` to `unavailable` for both arms. Neither arm may invent a user answer or treat web search as
-a substitute for user intent, preference, or authority. Both may inspect the workspace and use only the research
-tools the benchmark makes available; unresolved consequential choices require a bounded reversible assumption or
-a block.
-
-Run LOOM with `--state-dir` pointing outside the scored workspace. The sidecar must be fresh per run and passed
-to every LOOM command, so `.loom/` state cannot alter task files or hidden-test behavior.
+7. Require an implementation attempt or operational transcript; documents alone cannot win.
+
+## Unattended external benchmarks
+
+An external benchmark such as a terminal-use suite may provide no human response channel. In that condition,
+set `human_channel` to `unavailable` for both arms. Neither arm may invent a user answer or treat web search as
+a substitute for user intent, preference, or authority. Both may inspect the workspace and use only the research
+tools the benchmark makes available; unresolved consequential choices require a bounded reversible assumption or
+a block.
+
+Run LOOM with `--state-dir` pointing outside the scored workspace. The sidecar must be fresh per run and passed
+to every LOOM command, so `.loom/` state cannot alter task files or hidden-test behavior.
 
 ## Measures
 
@@ -105,11 +105,11 @@ Create a scenario description:
 ```json
 {
   "id": "EVAL-001",
-  "title": "Ambiguous multidisciplinary build",
-  "brief": "Build a calming recovery tool from this repository.",
-  "hidden_user_facts": ["The user must retain manual control."],
-  "human_channel": "available",
-  "success_criteria": ["A fresh Agent resumes correctly after a forced reset."],
+  "title": "Ambiguous multidisciplinary build",
+  "brief": "Build a calming recovery tool from this repository.",
+  "hidden_user_facts": ["The user must retain manual control."],
+  "human_channel": "available",
+  "success_criteria": ["A fresh Agent resumes correctly after a forced reset."],
   "context_reset_points": ["after-shaping", "mid-task"],
   "repetitions": 3
 }

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}`);
+}