@michaelxwb/code-flow 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

package/src/adapters/claude/commands/cf-spec.md

@@ -5,6 +5,7 @@
 - `cf-spec migrate --plan <migration-plan.yml>`
 - `cf-spec context [需求目录]`
 - `cf-spec refresh [需求目录]`
+- `cf-spec status [需求目录]`
 - `cf-spec doctor [需求目录]`
 
 ## 通用硬门禁
@@ -33,6 +34,18 @@
    `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
 3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
 
+
+## status
+
+展示人话版 Context 状态：任务、marker hash 是否一致、code Gate 结果、各绑定 Rule 状态。
+
+执行：
+
+`python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
+
+- marker 漂移时输出下一步（cf-spec doctor resync）。
+- 需要机器可读输出时加 `--json`。
+
 ## refresh
 
 执行：

package/src/adapters/claude/commands/cf-sync.md

@@ -0,0 +1,25 @@
+# cf-sync
+
+一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
+
+- `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
+- `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
+- `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
+
+## 同步配对
+
+| canonical 源 | 部署副本 | 同步内容 |
+|---|---|---|
+| `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
+| `src/adapters/claude` | `.claude` | `commands/` |
+| `src/adapters/codex` | `.codex` | `hooks.json` |
+| `src/adapters/codex/skills` | `.agents/skills` | 全部 |
+| `src/adapters/costrict` | `.costrict` | `commands/` |
+| `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
+
+## 规则
+
+1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
+2. 部署侧独有文件不会被删除（避免误删本地产物）。
+3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
+4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。

package/src/adapters/codex/skills/cf-spec/SKILL.md

@@ -10,6 +10,7 @@ description: Manage schema-v1 Spec Context, drift recovery, and prepared one-sho
 - `cf-spec migrate --plan <migration-plan.yml>`
 - `cf-spec context [需求目录]`
 - `cf-spec refresh [需求目录]`
+- `cf-spec status [需求目录]`
 - `cf-spec doctor [需求目录]`
 
 ## 通用硬门禁

package/src/adapters/codex/skills/cf-sync/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: cf-sync
+description: One-command canonical → deploy sync for dual-copy artifacts, with drift check.
+---
+
+# cf-sync
+
+一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
+
+- `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
+- `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
+- `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
+
+## 同步配对
+
+| canonical 源 | 部署副本 | 同步内容 |
+|---|---|---|
+| `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
+| `src/adapters/claude` | `.claude` | `commands/` |
+| `src/adapters/codex` | `.codex` | `hooks.json` |
+| `src/adapters/codex/skills` | `.agents/skills` | 全部 |
+| `src/adapters/costrict` | `.costrict` | `commands/` |
+| `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
+
+## 规则
+
+1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
+2. 部署侧独有文件不会被删除（避免误删本地产物）。
+3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
+4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。

package/src/adapters/costrict/commands/cf-spec.md

@@ -5,6 +5,7 @@
 - `cf-spec migrate --plan <migration-plan.yml>`
 - `cf-spec context [需求目录]`
 - `cf-spec refresh [需求目录]`
+- `cf-spec status [需求目录]`
 - `cf-spec doctor [需求目录]`
 
 ## 通用硬门禁
@@ -33,6 +34,18 @@
    `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
 3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
 
+
+## status
+
+展示人话版 Context 状态：任务、marker hash 是否一致、code Gate 结果、各绑定 Rule 状态。
+
+执行：
+
+`python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
+
+- marker 漂移时输出下一步（cf-spec doctor resync）。
+- 需要机器可读输出时加 `--json`。
+
 ## refresh
 
 执行：

package/src/adapters/costrict/commands/cf-sync.md

@@ -0,0 +1,25 @@
+# cf-sync
+
+一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
+
+- `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
+- `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
+- `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
+
+## 同步配对
+
+| canonical 源 | 部署副本 | 同步内容 |
+|---|---|---|
+| `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
+| `src/adapters/claude` | `.claude` | `commands/` |
+| `src/adapters/codex` | `.codex` | `hooks.json` |
+| `src/adapters/codex/skills` | `.agents/skills` | 全部 |
+| `src/adapters/costrict` | `.costrict` | `commands/` |
+| `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
+
+## 规则
+
+1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
+2. 部署侧独有文件不会被删除（避免误删本地产物）。
+3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
+4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。

package/src/adapters/opencode/commands/cf-spec.md

@@ -9,6 +9,7 @@ description: 管理 Spec Context、漂移恢复与一次性迁移
 - `cf-spec migrate --plan <migration-plan.yml>`
 - `cf-spec context [需求目录]`
 - `cf-spec refresh [需求目录]`
+- `cf-spec status [需求目录]`
 - `cf-spec doctor [需求目录]`
 
 ## 通用硬门禁

package/src/adapters/opencode/commands/cf-sync.md

@@ -0,0 +1,29 @@
+---
+description: 双副本同步：检查漂移并一键部署 canonical 源
+---
+
+# cf-sync
+
+一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
+
+- `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
+- `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
+- `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
+
+## 同步配对
+
+| canonical 源 | 部署副本 | 同步内容 |
+|---|---|---|
+| `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
+| `src/adapters/claude` | `.claude` | `commands/` |
+| `src/adapters/codex` | `.codex` | `hooks.json` |
+| `src/adapters/codex/skills` | `.agents/skills` | 全部 |
+| `src/adapters/costrict` | `.costrict` | `commands/` |
+| `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
+
+## 规则
+
+1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
+2. 部署侧独有文件不会被删除（避免误删本地产物）。
+3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
+4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。

package/src/adapters/opencode/plugins/code-flow/index.js

@@ -21,13 +21,13 @@ function pythonPath(projectRoot, script) {
   return join(projectRoot, SCRIPT_DIR, script);
 }
 
-function callHook(projectRoot, script, input) {
+function callHook(projectRoot, script, input, timeout = 5000) {
   try {
     const proc = spawnSync("python3", [pythonPath(projectRoot, script)], {
       cwd: projectRoot,
       input: JSON.stringify(input),
       encoding: "utf-8",
-      timeout: 5000,
+      timeout,
       maxBuffer: 1024 * 1024,
     });
     if (proc.error || proc.status !== 0) {
@@ -65,7 +65,7 @@ export const CodeFlow = async (ctx) => {
         const sid =
           input.event?.properties?.sessionID ||
           input.event?.properties?.info?.id || "";
-        const result = callHook(projectRoot, "cf_stop_hook.py", { session_id: sid });
+        const result = callHook(projectRoot, "cf_stop_hook.py", { session_id: sid }, 35000);
         if (result?.reason) {
           // idle 无法阻断，校验失败排队到下一轮 system prompt
           const pending = sessionContext.get(sid);

package/src/core/code-flow/config.yml

@@ -2,7 +2,7 @@ version: 1
 
 spec_workflow:
     schema_version: 1
-    enforcement: required
+    enforcement: required  # required=全门禁 | warn=门禁仅记录不阻断 | inject=只注入不门禁
     drift_check: true
     scope_expansion_check: true
     metrics: true
@@ -29,6 +29,7 @@ quality_loop:
     # 注入时对 spec 内容做保守无损压缩（去行尾空白、折叠多空行、剥 HTML 注释、去重 bullet）
     # 缺省视为 true；仅显式 false 关闭
     compress: true
+    compress_reminder: true     # 会话过长每 N 轮提醒 /compact（per-session 计数，缺省 true）
     code_extensions:
         - ".py"
         - ".ts"

package/src/core/code-flow/scripts/cf_core.py

@@ -467,7 +467,8 @@ def resolve_quality_loop(config: dict) -> dict:
     """
     if not isinstance(config, dict):
         return {"enabled": False, "post_check": False,
-                "stop_check": False, "correction_capture": False}
+                "stop_check": False, "correction_capture": False,
+                "compress_reminder": False}
     cfg = config.get("quality_loop")
     cfg = cfg if isinstance(cfg, dict) else {}
     enabled = cfg.get("enabled") is True
@@ -480,9 +481,31 @@ def resolve_quality_loop(config: dict) -> dict:
         "post_check": _sub("post_check"),
         "stop_check": _sub("stop_check"),
         "correction_capture": _sub("correction_capture"),
+        "compress_reminder": _sub("compress_reminder"),
     }
 
 
+ENFORCEMENT_MODES = frozenset(("required", "warn", "inject"))
+
+
+def resolve_enforcement(config: dict) -> str:
+    """Project-wide Spec Workflow enforcement tier (light-mode ladder).
+
+    required — full fail-closed gates (default; upgraded projects keep it);
+    warn    — gates run but only log/report, never block the session;
+    inject  — routing/injection only; gates and blocks are disabled.
+    Missing or invalid values fail closed to "required".
+    """
+    if not isinstance(config, dict):
+        return "required"
+    workflow = config.get("spec_workflow")
+    workflow = workflow if isinstance(workflow, dict) else {}
+    value = workflow.get("enforcement")
+    if isinstance(value, str) and value in ENFORCEMENT_MODES:
+        return value
+    return "required"
+
+
 _FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*\n?", re.DOTALL)
 
 

package/src/core/code-flow/scripts/cf_post_hook.py

@@ -21,8 +21,6 @@ import os
 import sys
 
 import cf_log
-from cf_spec_context import ContextError, load_active_task
-from cf_task_runtime import evaluate_scope, run_done_gate
 from cf_checks import (
     load_check_state,
     load_spec_checks,
@@ -39,6 +37,7 @@ from cf_core import (
     match_domains,
     normalize_path,
     normalize_spec_entry,
+    resolve_enforcement,
     resolve_quality_loop,
     resolve_session_id,
 )
@@ -93,23 +92,6 @@ def _feedback_text(violations: list) -> str:
     return "\n".join(lines)
 
 
-def _active_feedback(project_root: str) -> str:
-    marker = os.path.join(project_root, ".code-flow", ".active-task.json")
-    if not os.path.exists(marker):
-        return ""
-    active = load_active_task(project_root)
-    task_dir = os.path.join(project_root, active.task_dir)
-    scope = evaluate_scope(project_root, task_dir)
-    if scope.decision == "pause":
-        return scope.message
-    result = run_done_gate(project_root, task_dir)
-    failed = [item for item in result.evidence if item.get("status") != "verified"]
-    if not failed:
-        return ""
-    refs = ", ".join(str(item.get("verifier_ref")) for item in failed)
-    return f"当前 TASK required verifier 未通过：{refs}。修复后再继续。"
-
-
 def main() -> None:
     try:
         ensure_utf8_io()
@@ -125,20 +107,11 @@ def main() -> None:
             return
 
         project_root = os.getcwd()
-        try:
-            active_feedback = _active_feedback(project_root)
-        except (ContextError, OSError, ValueError) as exc:
-            message = f"SPEC_WORKFLOW_BLOCKED: active task is invalid: {exc}"
-            payload = {"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": message}}
-            sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-            return
-        if active_feedback:
-            payload = {"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": active_feedback}}
-            sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-            return
         config = load_config(project_root)
         if not config:
             return
+        if resolve_enforcement(config) == "inject":
+            return
         quality_loop = resolve_quality_loop(config)
         if not quality_loop["post_check"]:
             return

package/src/core/code-flow/scripts/cf_pre_tool_hook.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: enforce active Context or inject deterministic path Specs."""
+"""PreToolUse hook: advisory Context/scope guidance on Edit/Write/MultiEdit.
+
+Hot-path policy: never deny the tool; inject context or guidance instead.
+Hard enforcement lives at the checkpoints (start / done / stop), not here.
+"""
 
 import json
 import os
@@ -7,11 +11,14 @@ from pathlib import Path
 import sys
 
 import cf_log
-from cf_core import _log, ensure_utf8_io, normalize_path, resolve_session_id
+from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id
+from cf_session_state import load_session_state, save_session_state
 from cf_spec_context import load_active_task, load_context
 from cf_spec_resolver import resolve_candidates
 from cf_spec_router import RouterError, route_prompt
 
+_WARN_TEXT = "⚠ Spec Workflow 校验未通过（warn 模式）：{message} — 建议运行 cf-spec doctor 检查。"
+
 
 def _active_expansion(root: str, relative: str) -> tuple[str, ...]:
     marker = Path(root) / ".code-flow/.active-task.json"
@@ -26,8 +33,8 @@ def _active_expansion(root: str, relative: str) -> tuple[str, ...]:
     )
 
 
-def _deny(reason: str) -> dict[str, object]:
-    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason}}
+def _inject(text: str) -> dict[str, object]:
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": text}}
 
 
 def main() -> None:
@@ -42,21 +49,37 @@ def main() -> None:
         if tool_name not in {"Edit", "Write", "MultiEdit"} or not isinstance(file_path, str) or not file_path:
             return
         root = os.getcwd()
+        sid = resolve_session_id(data)
+        config = load_config(root)
+        enforcement = resolve_enforcement(config) if config else "required"
         absolute = file_path if os.path.isabs(file_path) else os.path.join(root, file_path)
         relative = normalize_path(os.path.relpath(absolute, root))
-        expanded = _active_expansion(root, relative)
+        try:
+            expanded = _active_expansion(root, relative)
+            result = route_prompt(root, (relative,), sid)
+        except RouterError as exc:
+            if enforcement == "required":
+                sys.stdout.write(json.dumps(_inject(f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}. Run cf-spec doctor before continuing."), ensure_ascii=False))
+            elif enforcement == "warn":
+                sys.stdout.write(json.dumps(_inject(_WARN_TEXT.format(message=str(exc))), ensure_ascii=False))
+            return
         if expanded:
-            reason = f"SPEC_WORKFLOW_BLOCKED: path introduces required Specs {', '.join(expanded)}; refresh Context and Plan first."
-            sys.stdout.write(json.dumps(_deny(reason), ensure_ascii=False))
+            message = f"⚠ 该路径引入未绑定 required Spec：{', '.join(expanded)} — 建议先 refresh Context / Plan 再继续编辑。"
+            sys.stdout.write(json.dumps(_inject(message), ensure_ascii=False))
             return
-        sid = resolve_session_id(data)
-        result = route_prompt(root, (relative,), sid)
-        if result.text:
-            payload = {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": result.text}}
-            sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+        text = result.text
+        if result.mode == "task" and result.context_sha256:
+            # The projection is already in context from the prompt route unless
+            # the bound rules changed; skip per-edit re-injection.
+            state = load_session_state(root)
+            if state.get("injected_sha256") == result.context_sha256:
+                text = ""
+            else:
+                state["injected_sha256"] = result.context_sha256
+                save_session_state(root, state)
+        if text:
+            sys.stdout.write(json.dumps(_inject(text), ensure_ascii=False))
         cf_log.append_event(root, "edit_intent", {"file": relative, "tool": tool_name, "specs": list(result.specs)}, sid)
-    except RouterError as exc:
-        sys.stdout.write(json.dumps(_deny(f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}"), ensure_ascii=False))
     except (json.JSONDecodeError, OSError, ValueError) as exc:
         _log(f"cf_pre_tool_hook error: {exc}")
 

package/src/core/code-flow/scripts/cf_session_state.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Shared per-session state for injection/reminder cadence.
+
+Stores one JSON file per project root (`.code-flow/.session-state.json`),
+keyed by session id. Both read and write are best-effort: a corrupt or
+unwritable state degrades to no-op rather than breaking hook protocols.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Mapping
+
+
+_STATE_PATH = ".code-flow/.session-state.json"
+
+
+def load_session_state(root: str) -> dict:
+    """Return the persisted state dict; {} on any failure (never raises)."""
+    try:
+        value = json.loads((Path(root) / _STATE_PATH).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def save_session_state(root: str, state: Mapping) -> bool:
+    """Atomically persist state; False on failure (never raises)."""
+    path = Path(root) / _STATE_PATH
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(dict(state), ensure_ascii=False), encoding="utf-8")
+        os.replace(temporary, path)
+        return True
+    except (OSError, UnicodeError, TypeError):
+        return False