@haaaiawd/loom 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,18 +1,40 @@
 # 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.
+
+## 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.
+
+- 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,10 +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;
-- 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.
@@ -42,7 +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.
+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
 
@@ -93,10 +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."],
-  "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

@@ -105,16 +105,37 @@ loom --version
 Inside a project, the Agent runs:
 
 ```bash
-loom init
-loom context
-```
-
-When a Task is active, `loom context` also restores a compact execution protocol: reconcile the Task with
-the current workspace and version-control state, inspect relevant tests before editing, choose proof by risk
-and exact `done_when` claims, persist `completed/current/next` at meaningful handoffs, and close only with
-reproducible evidence. It does not impose a ceremonial test or pull request on work that does not need one.
-
-The Agent edits `.loom/PROJECT.md`, design documents, and capability dossiers as human-readable project truth. Structured
+loom init
+loom context
+```
+
+When a Task is active, `loom context` also restores a compact execution protocol: reconcile the Task with
+the current workspace and version-control state, inspect relevant tests before editing, choose proof by risk
+and exact `acceptance` criteria, persist `completed/current/next` at meaningful handoffs, show the human real
+working things at milestones, and close only with reproducible evidence. It does not impose a ceremonial test
+or pull request on work that does not need one.
+
+### Unattended and benchmark runs
+
+LOOM does not invent a user when none is reachable. Tell the context compiler that the human channel is
+unavailable; the Agent then resolves uncertainty in order: inspect the workspace and tools, research only
+objective facts when the task permits it, then record a bounded assumption and choose a reversible action or
+block on unavailable authority. Web research never substitutes for user intent, preference, or permission.
+
+```bash
+loom context --human-channel unavailable
+```
+
+Benchmark runners can keep LOOM state out of the scored workspace by using an external sidecar on **every**
+LOOM command. Virtual references such as `.loom/PROJECT.md` still work inside Task context, but `init` does not
+write `.loom/` or `AGENTS.md` into the workspace being scored.
+
+```bash
+loom init --state-dir /runner/run-001/loom-state
+loom context --state-dir /runner/run-001/loom-state --human-channel unavailable
+```
+
+The Agent edits `.loom/PROJECT.md`, design documents, and capability dossiers as human-readable project truth. Structured
 writes use JSON files so long content remains auditable and shell quoting does not corrupt it:
 
 ```bash
@@ -154,10 +175,10 @@ Completion is deliberately explicit:
 
 ```json
 {
-  "evidence": ["npm test: 21 passed, 0 failed"],
-  "checks": [
+  "evidence": ["npm test: 20 passed, 0 failed"],
+  "acceptance_results": [
     {
-      "criterion": "The exact done_when sentence from the Task.",
+      "criterion": "The exact acceptance criterion from the Task.",
       "evidence": ["The command, artifact, or observation that proves this criterion."]
     }
   ]
@@ -182,7 +203,7 @@ observable completion, context isolation, and evidence. They no longer require s
 ## Proving that LOOM helps
 
 `loom eval scaffold --json-file scenario.json` creates an Evil Eval scenario with equal model, tools,
-workspace, user facts, and budget across two conditions. The only intended difference is the availability
+workspace, user-channel availability, facts, and budget across two conditions. The only intended difference is the availability
 of LOOM. Runs are repeated, context is forcibly reset, outputs are blinded and order-swapped, and ceremony,
 user burden, time, and token cost are penalized alongside quality. See [EVIL_EVAL.md](EVIL_EVAL.md).
 
@@ -194,11 +215,11 @@ user burden, time, and token cost are penalized alongside quality. See [EVIL_EVA
 npm test
 ```
 
-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,
-multi-attempt Keeper revision, stale digest and duplicate-run
-rejection, exact-file Task start, block/reopen including disproven completion, per-done-condition evidence,
-and Evil Eval controls. See the
+The v2 test suite (20 end-to-end tests) 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,
+deliverable coverage, decision recording with affected-task warnings, and Evil Eval controls. See the
 [complete UX and loop specification](docs/UX_FLOW.md).
 
 ## Documentation

package/README.zh-CN.md

@@ -87,13 +87,28 @@ loom --version
 进入项目后，Agent 运行：
 
 ```bash
-loom init
-loom context
-```
-
-当存在活跃 Task 时，`loom context` 还会恢复一段紧凑的执行协议：先把 Task 与当前工作区和版本控制状态校准，编辑前检查相关测试，根据风险和精确的 `done_when` 选择证据，在重要交接点写回 `completed/current/next`，最后只用可复现证据关闭 Task。它不会为了形式感强迫所有工作都写一个测试或开一个 PR。
-
-Agent 将 `.loom/PROJECT.md`、设计文档和能力卷宗作为人类可读的项目事实维护。结构化写入通过 JSON 文件完成，让长内容可以审计，也避免 shell 引号损坏数据：
+loom init
+loom context
+```
+
+当存在活跃 Task 时，`loom context` 还会恢复一段紧凑的执行协议：先把 Task 与当前工作区和版本控制状态校准，编辑前检查相关测试，根据风险和精确的 `acceptance` 条件选择证据，在重要交接点写回 `completed/current/next`，在里程碑向人类展示真实可运行的东西，最后只用可复现证据关闭 Task。它不会为了形式感强迫所有工作都写一个测试或开一个 PR。
+
+### 无人值守与 benchmark 运行
+
+当人类不可达时，LOOM 不会凭空编造一次用户对话。向上下文编译器说明人类通道不可用后，Agent 会依次检查工作区和工具、仅在任务许可时研究客观外部事实，然后记录有边界的假设并选择可逆方案；若需要不可逆、高风险或有实质成本的授权，则阻塞。网络搜索永远不能替代用户的意图、偏好或许可。
+
+```bash
+loom context --human-channel unavailable
+```
+
+Benchmark runner 可以通过外部 sidecar 将 LOOM 状态放在评分工作区之外；**每一条** LOOM 命令都要带同一个状态目录。Task 中的 `.loom/PROJECT.md` 等虚拟引用仍能使用，但 `init` 不会在被评分工作区写入 `.loom/` 或 `AGENTS.md`。
+
+```bash
+loom init --state-dir /runner/run-001/loom-state
+loom context --state-dir /runner/run-001/loom-state --human-channel unavailable
+```
+
+Agent 将 `.loom/PROJECT.md`、设计文档和能力卷宗作为人类可读的项目事实维护。结构化写入通过 JSON 文件完成，让长内容可以审计，也避免 shell 引号损坏数据：
 
 ```bash
 loom record --json-file understanding-update.json
@@ -131,10 +146,10 @@ loom task done TASK-001 --json-file evidence.json
 
 ```json
 {
-  "evidence": ["npm test: 21 passed, 0 failed"],
-  "checks": [
+  "evidence": ["npm test: 20 passed, 0 failed"],
+  "acceptance_results": [
     {
-      "criterion": "The exact done_when sentence from the Task.",
+      "criterion": "The exact acceptance criterion from the Task.",
       "evidence": ["The command, artifact, or observation that proves this criterion."]
     }
   ]
@@ -151,7 +166,7 @@ LOOM 2 用一个自适应理解环、可扩展的设计文档图、彼此独立
 
 ## 证明 LOOM 真的有用
 
-`loom eval scaffold --json-file scenario.json` 会创建一个 Evil Eval 场景。在两个条件中，模型、工具、工作区、用户事实和预算完全相同；唯一预期差异是能否使用 LOOM。实验会重复运行、强制重置上下文、匿名并交换产物顺序，同时把仪式成本、用户负担、时间和 token 消耗与质量一起计分。详见 [EVIL_EVAL.md](EVIL_EVAL.md)。
+`loom eval scaffold --json-file scenario.json` 会创建一个 Evil Eval 场景。在两个条件中，模型、工具、工作区、人类通道可用性、用户事实和预算完全相同；唯一预期差异是能否使用 LOOM。实验会重复运行、强制重置上下文、匿名并交换产物顺序，同时把仪式成本、用户负担、时间和 token 消耗与质量一起计分。详见 [EVIL_EVAL.md](EVIL_EVAL.md)。
 
 ![LOOM Evil Eval](docs/loom-eval-loop.svg)
 
@@ -161,7 +176,7 @@ LOOM 2 用一个自适应理解环、可扩展的设计文档图、彼此独立
 npm test
 ```
 
-v2 测试覆盖完整闭环，包括 250 个 Task 的 Work Map、上下文选择、决策替代历史、可扩展设计文档、专业领域分离、能力编译、多轮 Keeper 修订、陈旧 digest 与重复 run 拒绝、精确文件级 Task 启动、阻塞与重开（包括完成证据被推翻）、逐完成条件证据，以及 Evil Eval 的控制变量。详见[完整 UX 与闭环规范](docs/UX_FLOW.md)。
+v2 测试套件（20 个端到端测试）覆盖完整闭环，包括 250 个 Task 的 Work Map、上下文选择、决策替代历史、可扩展设计文档、专业领域分离、能力编译（含 source 引用校验）、多轮 Keeper 修订（含 auto-pass）、陈旧 digest 与重复 run 拒绝、精确文件级 Task 启动、阻塞与重开（包括完成证据被推翻）、逐 acceptance 条件证据、交付物覆盖、决策记录与受影响 Task 警告，以及 Evil Eval 的控制变量。详见[完整 UX 与闭环规范](docs/UX_FLOW.md)。
 
 ## 文档
 

package/cli/bin/loom.js

@@ -4,26 +4,35 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  addDeliverable,
   blockTask,
   checkProject,
+  checkDeliverableCoverage,
   compileContext,
   completeTask,
+  confirmCapability,
+  configureRuntime,
   createCapability,
   createDesign,
+  recordDecision,
   getCapability,
+  getCapabilityStatus,
   getDesign,
   getKeeperPrompt,
   getTask,
   importTasks,
   initProject,
   listCapabilities,
+  listDeliverables,
   listDesigns,
   loadProject,
   markReady,
   recordKeeper,
   recordUnderstanding,
   reopenTask,
+  researchCapability,
   scaffoldEval,
+  synthesizeCapability,
   skipKeeper,
   startTask,
   taskSummary,
@@ -63,19 +72,46 @@ function help() {
 
 The human talks naturally to the Agent. The Agent uses these commands silently.
 
+Typical flow (first pass):
+  1. loom init                          — create .loom/ skeleton
+  2. loom record                        — confirm facts, assumptions, open questions
+  3. loom design add                    — write design documents for consequential systems
+  4. loom capability add → research → synthesize → confirm
+                                        — build professional decision trees for fields that matter
+  5. loom deliverable add               — decompose the delivery surface
+  6. loom task plan                     — write Tasks with acceptance criteria covering deliverables
+  7. loom project ready                 — freeze a digest for Keeper review
+  8. loom keeper prompt → record        — fresh Agent verifies build-readiness (one-time)
+  9. loom task start → done             — execute one Task at a time, fill acceptance evidence
+  10. loom check                        — verify health, coverage, and drift
+
+When a new idea changes an existing decision:
+  loom decision --json-file <decision.json>   — record what changed and affected tasks
+  then update the design document directly; loom check warns which done tasks need reopening.
+
 Start and resume
   loom init
-  loom context [--task TASK-001] [--keeper]
+  loom context [--task TASK-001] [--keeper] [--human-channel available|unavailable]
   loom check
   loom prompts
 
 Preserve understanding
   loom record --json-file <update.json>
+  loom decision --json-file <decision.json>
   loom project ready
   loom design add <slug> --title <text> --kind <product|experience|system|contract|verification|operations|research>
   loom design list|get <slug>
   loom capability add <slug> --title <professional-field>
   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 status <slug>
+
+Map the delivery surface
+  loom deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>
+  loom deliverable list
+  loom deliverable coverage
 
 Maintain the work map
   loom task plan --json-file <tasks.json>
@@ -86,6 +122,10 @@ Maintain the work map
   loom task reopen <id> [--reason <reason>]
   loom task done <id> --json-file <evidence.json>
 
+Each Task should produce one verifiable unit of real work. Use acceptance[] with criterion,
+verify_by, and evidence fields. Task completion fills in each acceptance condition's evidence
+with the actual result (for acceptance tasks) or quotes each done_when criterion (for legacy tasks).
+
 One-time independent handoff
   loom keeper prompt
   loom keeper record --json-file <result.json>
@@ -94,11 +134,18 @@ One-time independent handoff
 Evaluate LOOM itself
   loom eval scaffold --json-file <scenario.json>
 
+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 one check for every exact done_when criterion.`;
+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).`;
 }
 
 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) {
     case '--version':
     case '-v': {
@@ -117,7 +164,7 @@ try {
       break;
     case 'context':
     case 'resume':
-      output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper') }));
+      output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper'), humanChannel: humanChannel || 'available' }));
       break;
     case 'prompts':
       output(promptCatalog());
@@ -125,6 +172,9 @@ try {
     case 'record':
       output(recordUnderstanding(jsonFile()));
       break;
+    case 'decision':
+      output(recordDecision(jsonFile()));
+      break;
     case 'check': {
       const result = checkProject();
       output(result);
@@ -159,7 +209,31 @@ try {
       else if (subcommand === 'get') {
         if (!rest[0]) throw new Error('Usage: loom capability get <slug>');
         output(getCapability(rest[0]));
-      } else throw new Error('Usage: loom capability add|list|get');
+      } else if (subcommand === 'research') {
+        if (!rest[0]) throw new Error('Usage: loom capability research <slug> --field <text>');
+        output(researchCapability(rest[0], { field: option('--field') }));
+      } else if (subcommand === 'synthesize') {
+        if (!rest[0]) throw new Error('Usage: loom capability synthesize <slug>');
+        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') }));
+      } else if (subcommand === 'status') {
+        if (!rest[0]) throw new Error('Usage: loom capability status <slug>');
+        output(getCapabilityStatus(rest[0]));
+      } else throw new Error('Usage: loom capability add|list|get|research|synthesize|confirm|status');
+      break;
+    }
+    case 'deliverable': {
+      if (subcommand === 'add') {
+        const slug = rest[0];
+        const title = option('--title');
+        const kind = option('--kind');
+        if (!slug) throw new Error('Usage: loom deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>');
+        output(addDeliverable(slug, { title, kind, notes: option('--notes') }));
+      } else if (subcommand === 'list') output(listDeliverables());
+      else if (subcommand === 'coverage') output(checkDeliverableCoverage());
+      else throw new Error('Usage: loom deliverable add|list|coverage');
       break;
     }
     case 'task': {