dream-wf 0.1.1 → 0.1.2

package/templates/hooks/codex/dream-wf-guard.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# Codex PreToolUse guard。
+# Codex CLI 支持 PreToolUse 阻塞式 hook，配置在 .codex/hooks.json。
+# stdin 收 JSON payload，stdout 返回 permissionDecision，或 exit code 2 表示 block。
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# Codex 的变更类 tool name：shell、apply_patch（文件编辑）。
+MUTATING_TOOLS = {"Write", "Edit", "MultiEdit", "Delete", "apply_patch", "shell", "Bash"}
+MUTATING_SHELL = re.compile(r"\b(rm|mv|cp|mkdir|touch|npm\s+install|pnpm\s+add|yarn\s+add|bun\s+add|git\s+commit|git\s+push)\b")
+
+
+def find_root(cwd):
+    current = Path(cwd).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".trellis").exists():
+            return candidate
+    return current
+
+
+def active_tasks(root):
+    tasks_dir = root / ".trellis" / "tasks"
+    if not tasks_dir.exists():
+        return []
+
+    result = []
+    for task_json in tasks_dir.glob("*/task.json"):
+        try:
+            data = json.loads(task_json.read_text())
+        except Exception:
+            continue
+        if data.get("status") in {"planning", "in_progress"}:
+            result.append((task_json.parent, data))
+    return result
+
+
+def is_prd_confirmed(task_dir):
+    prd = task_dir / "prd.md"
+    if not prd.exists():
+        return False
+    text = prd.read_text(errors="ignore").lower()
+    markers = ["prd confirmed", "confirmed: true", "status: confirmed", "用户已确认", "已确认"]
+    return any(marker in text for marker in markers)
+
+
+def is_planning_artifact(root, tool_input):
+    if not isinstance(tool_input, dict):
+        return False
+
+    candidate = tool_input.get("path") or tool_input.get("file_path") or tool_input.get("target_file") or ""
+    if not candidate:
+        return False
+
+    try:
+        root_resolved = root.resolve()
+        file_path = Path(candidate)
+        if not file_path.is_absolute():
+            file_path = (root_resolved / file_path)
+        relative = file_path.resolve().relative_to(root_resolved).as_posix()
+    except Exception:
+        return False
+
+    if not relative.startswith(".trellis/tasks/"):
+        return False
+
+    name = Path(relative).name
+    return (
+        name in {"prd.md", "design.md", "implement.md", "implement.jsonl", "check.jsonl"}
+        or "/research/" in relative
+    )
+
+
+def deny(message):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": message
+        }
+    }))
+    sys.exit(0)
+
+
+def allow():
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow"
+        }
+    }))
+    sys.exit(0)
+
+
+def main():
+    # 逃生舱：DREAM_WF_MODE=advisory 时跳过 strict 检查。
+    if os.environ.get("DREAM_WF_MODE", "").lower() == "advisory":
+        allow()
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        allow()
+
+    tool_name = payload.get("tool_name") or payload.get("tool", "")
+    tool_input = payload.get("tool_input") or payload.get("input") or {}
+    cwd = payload.get("cwd") or os.environ.get("CODEX_PROJECT_DIR") or os.getcwd()
+    root = find_root(cwd)
+
+    is_mutating = tool_name in MUTATING_TOOLS
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if tool_name in {"Shell", "Bash", "shell"} and MUTATING_SHELL.search(command):
+        is_mutating = True
+
+    if not is_mutating:
+        allow()
+
+    tasks = active_tasks(root)
+    if not tasks:
+        deny("dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode (DREAM_WF_MODE=advisory).")
+
+    if is_planning_artifact(root, tool_input):
+        allow()
+
+    in_progress_confirmed = any(
+        task.get("status") == "in_progress" and is_prd_confirmed(task_dir)
+        for task_dir, task in tasks
+    )
+    if in_progress_confirmed:
+        allow()
+
+    in_progress_any = any(task.get("status") == "in_progress" for _, task in tasks)
+    if in_progress_any:
+        allow()
+
+    planning_unconfirmed = [
+        task_dir for task_dir, task in tasks
+        if task.get("status") == "planning" and not is_prd_confirmed(task_dir)
+    ]
+    if planning_unconfirmed:
+        deny("dream-wf strict: implementation is blocked while all active tasks are in planning and at least one PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.")
+
+    allow()
+
+
+if __name__ == "__main__":
+    main()

package/templates/hooks/cursor/dream-wf-guard.py

@@ -52,10 +52,12 @@ def is_planning_artifact(root, tool_input):
         return False
 
     try:
+        root_resolved = root.resolve()
         file_path = Path(candidate)
         if not file_path.is_absolute():
-            file_path = (root / file_path).resolve()
-        relative = file_path.relative_to(root).as_posix()
+            file_path = (root_resolved / file_path)
+        # 规范化符号链接，避免 /tmp vs /private/tmp 导致 relative_to 失败。
+        relative = file_path.resolve().relative_to(root_resolved).as_posix()
     except Exception:
         return False
 
@@ -84,6 +86,10 @@ def allow():
 
 
 def main():
+    # 逃生舱：DREAM_WF_MODE=advisory 时跳过 strict 检查。
+    if os.environ.get("DREAM_WF_MODE", "").lower() == "advisory":
+        allow()
+
     try:
         payload = json.load(sys.stdin)
     except Exception:
@@ -104,15 +110,28 @@ def main():
 
     tasks = active_tasks(root)
     if not tasks:
-        deny("dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or explicitly switch dream-wf to advisory mode.")
-
-    planning_tasks = [(task_dir, task) for task_dir, task in tasks if task.get("status") == "planning"]
-    if planning_tasks:
-        if is_planning_artifact(root, tool_input):
-            allow()
-        unconfirmed = [task for task_dir, task in planning_tasks if not is_prd_confirmed(task_dir)]
-        if unconfirmed:
-            deny("dream-wf strict: implementation is blocked while this task is in planning and its PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.")
+        deny("dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode (DREAM_WF_MODE=advisory).")
+
+    if is_planning_artifact(root, tool_input):
+        allow()
+
+    in_progress_confirmed = any(
+        task.get("status") == "in_progress" and is_prd_confirmed(task_dir)
+        for task_dir, task in tasks
+    )
+    if in_progress_confirmed:
+        allow()
+
+    in_progress_any = any(task.get("status") == "in_progress" for _, task in tasks)
+    if in_progress_any:
+        allow()
+
+    planning_unconfirmed = [
+        task_dir for task_dir, task in tasks
+        if task.get("status") == "planning" and not is_prd_confirmed(task_dir)
+    ]
+    if planning_unconfirmed:
+        deny("dream-wf strict: implementation is blocked while all active tasks are in planning and at least one PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.")
 
     allow()
 

package/templates/hooks/opencode/dream-wf-guard.js

@@ -1,13 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const mutatingTools = new Set(['Write', 'Edit', 'MultiEdit', 'Delete']);
+const mutatingTools = new Set(['Write', 'Edit', 'MultiEdit', 'Delete', 'apply_patch', 'shell']);
 const mutatingShell = /\b(rm|mv|cp|mkdir|touch|npm\s+install|pnpm\s+add|yarn\s+add|bun\s+add|git\s+commit|git\s+push)\b/;
 
 export default function dreamWfGuard() {
   return {
     name: 'dream-wf-guard',
-    async 'tool.before'(input) {
+    async 'tool.execute.before'(input) {
+      // 逃生舱：DREAM_WF_MODE=advisory 时跳过 strict 检查。
+      if (process.env.DREAM_WF_MODE?.toLowerCase() === 'advisory') {
+        return;
+      }
+
       const toolName = input?.tool || input?.tool_name || '';
       const toolInput = input?.input || input?.tool_input || {};
       const cwd = input?.cwd || process.cwd();
@@ -21,17 +26,29 @@ export default function dreamWfGuard() {
 
       const tasks = activeTasks(root);
       if (tasks.length === 0) {
-        throw new Error('dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode.');
+        throw new Error('dream-wf strict: mutating actions require an active Trellis task. Create or start a Trellis task first, or switch dream-wf to advisory mode (DREAM_WF_MODE=advisory).');
+      }
+
+      // 规划产物始终允许，便于在 planning 阶段编写 prd/design 等。
+      if (isPlanningArtifact(root, toolInput)) {
+        return;
+      }
+
+      // 若存在已确认的 in_progress 任务，允许实现操作，不被其它 stale planning 任务阻塞。
+      const hasConfirmedInProgress = tasks.some(({ taskDir, task }) => task.status === 'in_progress' && isPrdConfirmed(taskDir));
+      if (hasConfirmedInProgress) {
+        return;
       }
 
-      const hasPlanningTask = tasks.some(({ task }) => task.status === 'planning');
-      if (hasPlanningTask && isPlanningArtifact(root, toolInput)) {
+      const hasAnyInProgress = tasks.some(({ task }) => task.status === 'in_progress');
+      if (hasAnyInProgress) {
         return;
       }
 
-      const hasUnconfirmedPlanningTask = tasks.some(({ taskDir, task }) => task.status === 'planning' && !isPrdConfirmed(taskDir));
-      if (hasUnconfirmedPlanningTask) {
-        throw new Error('dream-wf strict: implementation is blocked while this task is in planning and its PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.');
+      // 剩余情况：所有活跃任务都是 planning。若任一未确认 PRD，则阻塞实现。
+      const hasUnconfirmedPlanning = tasks.some(({ taskDir, task }) => task.status === 'planning' && !isPrdConfirmed(taskDir));
+      if (hasUnconfirmedPlanning) {
+        throw new Error('dream-wf strict: implementation is blocked while all active tasks are in planning and at least one PRD is not confirmed. Continue grill-me PRD clarification first. Planning artifacts under .trellis/tasks/** are allowed.');
       }
     }
   };
@@ -93,8 +110,9 @@ function isPlanningArtifact(root, toolInput) {
 
   let relative;
   try {
-    const filePath = path.isAbsolute(candidate) ? candidate : path.resolve(root, candidate);
-    relative = path.relative(root, filePath).split(path.sep).join('/');
+    const rootResolved = fs.realpathSync(root);
+    const filePath = path.isAbsolute(candidate) ? candidate : path.resolve(rootResolved, candidate);
+    relative = path.relative(rootResolved, fs.realpathSync(filePath)).split(path.sep).join('/');
   } catch {
     return false;
   }

package/templates/rules/claude-code/dream-wf-block.md

@@ -13,6 +13,8 @@ For every software engineering request in this project, use the Dream WF profile
 
 During planning, do not start by drafting and writing a speculative PRD. Use `dream-wf-grill-prd` behavior first: inspect available context, ask exactly one high-value question at a time, provide 2-3 options and a recommended answer, then update `prd.md` after the user answers.
 
+Before requesting PRD confirmation, verify technical assumptions against latest knowledge using `grok-search-mcp` (`web_search`, `web_fetch`). Record results in the `## Knowledge Verification` section of `prd.md`. Correct any outdated assumptions. Add `knowledge verified` to the PRD after verification is complete.
+
 Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
 
 ## MCP Policy

package/templates/rules/codex/dream-wf-block.md

@@ -0,0 +1,43 @@
+<!-- DREAM-WF:START -->
+# Dream WF Entry
+
+For every software engineering request in this project, use the Dream WF profile on top of Trellis by default. The user does not need to mention Trellis or dream-wf.
+
+## Default Routing
+
+- First classify the request using Trellis task classification.
+- For conversation-only or tiny inline work, ask whether a Trellis task is needed only if durable tracking would help.
+- For feature work, bug fixes with uncertainty, refactors, architecture decisions, multi-file changes, or any unclear request, create/use a Trellis planning task before implementation.
+
+## PRD First, Grill-Me Style
+
+During planning, do not start by drafting and writing a speculative PRD. Use `dream-wf-grill-prd` behavior first: inspect available context, ask exactly one high-value question at a time, provide 2-3 options and a recommended answer, then update `prd.md` after the user answers.
+
+Before requesting PRD confirmation, verify technical assumptions against latest knowledge using `grok-search-mcp` (`web_search`, `web_fetch`). Record results in the `## Knowledge Verification` section of `prd.md`. Correct any outdated assumptions. Add `knowledge verified` to the PRD after verification is complete.
+
+Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
+
+## MCP Policy
+
+- Use `fast-context-mcp` for codebase semantic context.
+- Use `grok-search-mcp` for external docs, live web information, and webpage fetch.
+- If a preferred MCP is unavailable, state the fallback reason before using another tool.
+
+## Accuracy Policy
+
+- Do not guess or fabricate facts, APIs, package behavior, release status, or external documentation when the answer is not already known from model knowledge or project context.
+- When current or missing knowledge is required, actively use the preferred web search/fetch MCP tools, or ask the user for authoritative information.
+- Continue searching or asking until the information is accurate enough to proceed safely.
+
+## Language Policy
+
+- Write README and project documentation in Chinese.
+- Write code comments in Chinese when comments are necessary.
+- Avoid obvious comments; only explain non-obvious intent, constraints, or trade-offs.
+
+## Naming Policy
+
+- Prefer concise file names.
+- Use one word when one word clearly describes the purpose, such as `pipeline`.
+- When multiple words are necessary, use lowercase snake_case, such as `paper_extract`.
+<!-- DREAM-WF:END -->

package/templates/rules/cursor/dream-wf.mdc

@@ -25,7 +25,8 @@ Instead:
 4. Provide 2-3 options and a recommended answer.
 5. After the user answers, update `prd.md`.
 6. Repeat until blocking open questions are resolved.
-7. Ask for explicit PRD confirmation before implementation.
+7. **Knowledge Verification**: before asking for PRD confirmation, verify technical assumptions against latest knowledge using `grok-search-mcp` (`web_search`, `web_fetch`). Record results in the `## Knowledge Verification` section of `prd.md`. Correct any outdated assumptions. Add `knowledge verified` to the PRD after verification is complete.
+8. Ask for explicit PRD confirmation before implementation.
 
 ## Implementation Gate
 

package/templates/rules/opencode/dream-wf-block.md

@@ -13,6 +13,8 @@ For every software engineering request in this project, use the Dream WF profile
 
 During planning, do not start by drafting and writing a speculative PRD. Use `dream-wf-grill-prd` behavior first: inspect available context, ask exactly one high-value question at a time, provide 2-3 options and a recommended answer, then update `prd.md` after the user answers.
 
+Before requesting PRD confirmation, verify technical assumptions against latest knowledge using `grok-search-mcp` (`web_search`, `web_fetch`). Record results in the `## Knowledge Verification` section of `prd.md`. Correct any outdated assumptions. Add `knowledge verified` to the PRD after verification is complete.
+
 Do not start implementation until the active Trellis task has a confirmed PRD. Planning artifacts such as `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, and `research/**` are allowed during planning.
 
 ## MCP Policy

package/templates/skills/dream-wf-grill-prd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dream-wf-grill-prd
 description: |
-  Use during Trellis planning when creating or refining a PRD. Applies grill-me style clarification: ask one question at a time, inspect code before asking, provide options and a recommended answer, update prd.md after each decision, and require PRD confirmation before implementation.
+  Use during Trellis planning when creating or refining a PRD. Applies grill-me style clarification: ask one question at a time, inspect code before asking, provide options and a recommended answer, update prd.md after each decision, verify technical facts against latest knowledge with grok-search-mcp before confirmation, and require PRD confirmation before implementation.
 ---
 
 # Dream WF Grill PRD
@@ -33,7 +33,52 @@ If the task is a small inline change and the user declined Trellis task creation
 8. Move confirmed answers into `Requirements`, `Acceptance Criteria`, `Decisions`, `Technical Notes`, or `Out of Scope`.
 9. Add spec candidates when a user answer or design decision should become a project convention.
 10. Continue until no blocking open questions remain.
-11. Show the complete PRD and ask for explicit confirmation before implementation starts.
+11. **Knowledge Verification** — before asking the user for PRD confirmation, perform a knowledge verification pass (see below).
+12. Show the complete PRD (including the Knowledge Verification section) and ask for explicit confirmation before implementation starts.
+
+## Knowledge Verification
+
+Before requesting PRD confirmation, verify that the technical assumptions in the PRD are aligned with the latest knowledge. This prevents executing on outdated or incorrect information.
+
+### When to Verify
+
+Identify technical points in the PRD that could be outdated or wrong:
+
+- API names, signatures, or behavior of external packages or services.
+- Framework or library version-specific behavior, deprecations, or breaking changes.
+- Tool configuration formats, hook event names, or feature flags.
+- Platform-specific conventions (e.g., Codex hook events, Cursor hooks.json format, Claude Code PreToolUse schema).
+- Release status or availability of packages, features, or APIs.
+- Any fact that the PRD relies on which, if wrong, would invalidate the plan.
+
+### How to Verify
+
+1. Prefer `grok-search-mcp` (`web_search`, `web_fetch`) for external docs, live technical information, and release notes.
+2. If `grok-search-mcp` is unavailable, state the fallback reason before using another web tool.
+3. For each verified point, record: what was searched, the source, and whether the PRD assumption was confirmed or corrected.
+4. If a search reveals that a PRD assumption is wrong or outdated, update the relevant PRD section immediately and note the correction.
+5. If a technical point cannot be verified (no reliable source found), flag it as an open question rather than assuming it is correct.
+
+### Recording Results
+
+Write results in the `## Knowledge Verification` section of `prd.md`:
+
+```markdown
+## Knowledge Verification
+
+- Verified: <what was checked>
+  Search: <query or topic searched>
+  Source: <URL or reference>
+  Result: confirmed | corrected | inconclusive
+  Correction: <if corrected, what changed>
+```
+
+### Stop Condition for Verification
+
+- All identified technical risk points have been searched and recorded, OR
+- Remaining unverified points have been moved to `Open Questions` with a clear note that they need verification before implementation.
+
+Only after this step is complete, add `knowledge verified` to the PRD and ask the user for final confirmation.
 
 ## PRD Structure
 
@@ -65,6 +110,13 @@ Use or preserve these sections:
 ## Technical Notes
 - ...
 
+## Knowledge Verification
+- Verified: ...
+  Search: ...
+  Source: ...
+  Result: confirmed | corrected | inconclusive
+  Correction: ...
+
 ## Spec Candidates
 - Candidate: ...
   Evidence: ...

package/templates/spec/guides/dream-wf-prd-policy.md

@@ -12,11 +12,24 @@ This project uses `dream-wf` on top of Trellis.
 - Inspect code, docs, config, existing specs, and task history before asking the user.
 - Update `prd.md` only after each confirmed answer, confirmed existing fact, or explicit decision.
 - Treat task creation consent and implementation approval as separate gates.
+- **Before PRD confirmation, verify technical assumptions against latest knowledge using `grok-search-mcp` (`web_search`, `web_fetch`).** Record verification results in the `## Knowledge Verification` section of `prd.md`. If a search reveals an outdated assumption, correct it immediately. If a point cannot be verified, move it to `Open Questions`.
 - Do not start implementation until the PRD is confirmed.
 - Write README and project documentation in Chinese.
 - Write code comments in Chinese when comments are necessary, and avoid obvious comments.
 - Prefer concise file names: one word when clear, or lowercase snake_case for necessary multi-word names.
 
+## Knowledge Verification
+
+Before requesting PRD confirmation, identify technical risk points that could be outdated or wrong, and verify them with `grok-search-mcp`:
+
+- API names, signatures, behavior of external packages or services.
+- Framework or library version-specific behavior, deprecations, or breaking changes.
+- Tool configuration formats, hook event names, or feature flags.
+- Platform-specific conventions (e.g., Codex hook events, Cursor hooks.json format, Claude Code PreToolUse schema).
+- Release status or availability of packages, features, or APIs.
+
+Record each verification in `prd.md` under `## Knowledge Verification`. Add `knowledge verified` to the PRD after all risk points have been verified or moved to `Open Questions`.
+
 ## Initial Spec Candidates
 
 During bootstrap or planning, spec candidates may come from:
@@ -25,6 +38,7 @@ During bootstrap or planning, spec candidates may come from:
 - PRD decisions.
 - Design decisions.
 - Verified codebase facts.
+- Knowledge verification results (confirmed or corrected).
 - Existing tests, configs, docs, and conventions.
 
 Initial spec candidates require user review before they become stable project conventions.