@chenmk/superflow 0.5.11 → 0.5.13

package/README.md

@@ -46,6 +46,31 @@ real verified delivery. SuperBridge Flow makes that gap explicit:
 The CLI installs skills, hooks or command aliases, rules, scripts, handoff
 state, and dependency guards for Claude Code and Codex.
 
+In OpenSpec/SDD Java repositories, hooks also block unsafe MyBatis `${}`
+interpolation, Git hook bypasses, and staged secrets. Java/build edits are
+accumulated and compiled once at Stop for affected Maven/Gradle modules. Missing
+build tools or compilation failures are reported as failed verification.
+Native session observation hooks warn once on the sixth edit to one file in
+ten minutes or the third consecutive failure of one tool in five minutes. A
+successful call resets that tool's failure count, and SessionEnd clears the
+observation state. These warnings do not block tools or alter managed budgets.
+`superflow context-audit` provides a read-only check for `CONTEXT.md`
+terminology and required ADR fields. A missing ADR is advisory and does not add
+an approval gate.
+`superflow docs-audit` reports Markdown age, dead code anchors, and inbound
+links. New Markdown placement reminders always exit successfully and never move,
+merge, or delete files.
+`superflow map-audit` compares full, task Top-K, and directory/symbol skeleton
+contexts from the existing Understand Anything graph without creating another
+persistent map.
+`superflow cleanup-audit` reports duplicate names, complexity clues, and TODO
+hotspots with evidence and a route, without modifying source files.
+`superflow hook-migrate --path <project> --json` audits project Hooks read-only;
+`--apply` backs up the config and removes only known legacy ake Hooks with
+provenance or managed Superflow/SDD entries. Custom Hooks remain. Project init
+and update use the same migration; the global prompt Hook also attempts one
+safe migration per project session and asks for a restart if definitions changed.
+
 ## Highlights
 
 0.5.10 strengthens document delivery: requirement × real-entry coverage (including
@@ -330,6 +355,7 @@ best-effort and does not block initialization.
 | `superflow --language en --help`                             | Show English CLI help                                                    |
 | `superflow scan --language en`                               | Regenerate project context templates in English                          |
 | `superflow pipeline`                                         | Check pipeline skill deployment                                          |
+| `superflow quick "<task>" --path <file> --seam <existing-file>` | Gate a small code task before Quick Spec approval and quick managed execution |
 | `superflow pipeline "<task>" --managed --project <path>`     | Run short-session execution with direct review by the current host agent |
 | `--acceptance-contract <file>`                                | Required frozen acceptance JSON for prompt/SDD starts                    |
 | `superflow docs [change]`                                    | Run the docs gate and check the phase skill                              |

package/README.zh-CN.md

@@ -34,6 +34,13 @@ Superpowers 编排成一个有状态的研发流程：前者负责需求、合
 后者负责源码级设计、TDD 顺序、实现分工、review 和真实验证。
 
 CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 npm 包，
+启用 OpenSpec/SDD 的 Java 仓库还会在写码时拦截危险 Mapper `${}` 插值、Git Hook 绕过和暂存密钥；Java/构建文件编辑只记录路径，在 Stop 时按受影响 Maven/Gradle 模块批量编译一次。缺少构建工具或编译失败会明确报告，不能当作验证通过。
+原生会话的观察 Hook 会在同文件十分钟内第六次编辑、同工具五分钟内第三次连续失败时各提醒一次；成功调用重置该工具失败计数，SessionEnd 清理观察状态，提醒不阻断工具或改变托管预算。
+`superflow context-audit` 可只读检查 `CONTEXT.md` 术语和 ADR 必备字段：术语只写业务语言，ADR 只用于难逆转且有备选方案的决定；缺少 ADR 仅提醒，不增加审批门禁。
+`superflow docs-audit` 可只读盘点 Markdown 的年龄、失效代码锚点和入链数；新建 Markdown 的落位提醒恒退 0，不自动移动、合并或删除。
+`superflow map-audit` 只读比较 Understand Anything 的完整图谱、任务 Top-K 和目录/符号骨架，不创建第二套持久地图。
+`superflow cleanup-audit` 只读输出重复文件名、复杂度线索和 TODO 热点，带证据与执行路由，不修改源码。
+项目旧 Hook 可用 `superflow hook-migrate --path <项目> --json` 只读审计，追加 `--apply` 后只迁移有 ake 来源标记的已知旧 Hook 或 Superflow/SDD 管理项；先备份，保留自定义 Hook。项目级 init/update 自动执行同一迁移；全局会话 Hook 首次使用项目时也会尝试一次安全迁移，若配置已改变须重启当前会话。
 自动部署到：
 
 - Claude Code：`~/.claude/skills/`、`~/.claude/scripts/`，并注册 `~/.claude/settings.json` hook
@@ -271,6 +278,7 @@ MCP 是主 Agent 与本地托管状态机的通信通道，不会把 Superflow
 | `superflow design [change]`                                  | 校验 SuperBridge Flow design 阶段技能部署                   |
 | `superflow implement [change]`                               | 生成当前 Coding Ready 凭证后进入实现阶段                    |
 | `superflow pipeline`                                         | 校验 SuperBridge Flow pipeline 阶段技能部署                 |
+| `superflow quick "<任务>" --path <文件> --seam <既有文件>`    | 对小型代码任务做窄门判断；批准 Quick Spec 后复用 quick 托管档位 |
 | `superflow pipeline "<任务>" --managed --project <目录>`     | 执行 Agent 短会话开发，当前 Host Agent 直接评审             |
 | `--acceptance-contract <文件>`                                | Prompt/SDD 启动必填的冻结验收合同 JSON                      |
 | `superflow check <change> --level files\|docs\|coding-ready` | 分级检查文件、文档交付或可直接编码就绪度                    |

package/assets/manifest.json

@@ -1,6 +1,9 @@
 {
   "version": "0.1.2",
-  "agents": ["claude", "codex"],
+  "agents": [
+    "claude",
+    "codex"
+  ],
   "skills": [
     "openspec-apply-change",
     "openspec-archive-change",
@@ -16,13 +19,22 @@
     "superflow-requirement-review",
     "superflow-table-impact-analysis",
     "superflow-tweak",
-    "superflow-verify"
+    "superflow-verify",
+    "superflow-quick-dev"
+  ],
+  "rules": [
+    "superflow-phase-guard.md"
   ],
-  "rules": ["superflow-phase-guard.md"],
   "scripts": [
     "superflow-verify-integration.sh",
     "superflow-delivery-check.sh",
     "superflow-sql-sync-hook.py",
+    "superflow-java-build-hook.py",
+    "superflow-java-stop-hook.sh",
+    "superflow-loop-observer.py",
+    "superflow-loop-failure-hook.sh",
+    "superflow-loop-end-hook.sh",
+    "superflow-doc-placement-hook.py",
     "superflow-contract-hooks.sh",
     "superflow-enforce-hook.sh",
     "superflow-hook-guard.sh",
@@ -43,8 +55,12 @@
     "sync-settings-json.py"
   ],
   "agentScripts": {
-    "claude": ["claude-auto-backup-hook.sh"],
-    "codex": ["codex-auto-backup-hook.sh"]
+    "claude": [
+      "claude-auto-backup-hook.sh"
+    ],
+    "codex": [
+      "codex-auto-backup-hook.sh"
+    ]
   },
   "hooks": [
     "superflow-enforce-hook.sh",
@@ -52,13 +68,23 @@
     "superflow-contract-hooks.sh",
     "superflow-dependency-update-hook.sh",
     "superflow-sql-sync-hook.py",
+    "superflow-java-build-hook.py",
+    "superflow-java-stop-hook.sh",
+    "superflow-loop-observer.py",
+    "superflow-loop-failure-hook.sh",
+    "superflow-loop-end-hook.sh",
+    "superflow-doc-placement-hook.py",
     "superflow-delivery-check.sh",
     "superflow-integration-evidence-hook.sh",
     "superflow-archive-command-hook.sh",
     "superflow-managed-work-guard.sh"
   ],
   "agentHooks": {
-    "claude": ["claude-auto-backup-hook.sh"],
-    "codex": ["codex-auto-backup-hook.sh"]
+    "claude": [
+      "claude-auto-backup-hook.sh"
+    ],
+    "codex": [
+      "codex-auto-backup-hook.sh"
+    ]
   }
 }

package/assets/review-rules.json

@@ -0,0 +1,24 @@
+{
+  "rules": [
+    {
+      "path": "**/*Mapper.xml",
+      "rule": "Verify parameterized MyBatis bindings and dynamic identifier allowlists",
+      "source": "system"
+    },
+    {
+      "path": "**/*Controller.java",
+      "rule": "Review authentication, validation, and controller-to-service boundaries",
+      "source": "system"
+    },
+    {
+      "path": "**/*Service*.java",
+      "rule": "Review transactions, batch access, N+1 queries, and external-call boundaries",
+      "source": "system"
+    },
+    {
+      "path": "**/*.java",
+      "rule": "Review correctness, exceptions, sensitive logging, and concurrency",
+      "source": "system"
+    }
+  ]
+}

package/assets/scripts/superflow-archive-command-hook.sh

@@ -1,6 +1,10 @@
 #!/bin/bash
 # Blocks direct OpenSpec/Superflow archive commands that bypass lifecycle gates.
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 set -u
 
 INPUT=$(cat)

package/assets/scripts/superflow-contract-hooks.sh

@@ -9,6 +9,10 @@
 # 环境变量：
 #   SDD_CONTRACT_HOOK_DEBUG=1  开启调试输出
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 INPUT=$(cat)
 
 # 提取 file_path

package/assets/scripts/superflow-delivery-check.sh

@@ -3,6 +3,10 @@
 # Blocks implementation commits that forget to update the matching PXX
 # delivery documents and test evidence.
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 set -u
 
 MODE="${1:-}"

package/assets/scripts/superflow-dependency-update-hook.sh

@@ -68,6 +68,35 @@ GLOBAL_STAMP="$STATE_DIR/dependency-update-last.stamp"
 LOG_FILE="$STATE_DIR/dependency-update.log"
 LOCK_DIR="$STATE_DIR/dependency-update.lock"
 
+# One safe project migration per session. The CLI only removes known managed
+# legacy entries after a provenance check, backs up the project config, and
+# preserves custom hooks. A running Host may need a restart to reload hooks.
+PROJECT_STAMP="$STATE_DIR/project-hooks-$SESSION_HASH.stamp"
+if [ ! -f "$PROJECT_STAMP" ] && command -v superflow >/dev/null 2>&1; then
+  HOST_AGENT=""
+  case "$0" in
+    */.codex/*) HOST_AGENT="codex" ;;
+    */.claude/*) HOST_AGENT="claude" ;;
+  esac
+  if [ -n "$HOST_AGENT" ]; then
+    MIGRATION_JSON="$(superflow hook-migrate --path "$PWD" --agent "$HOST_AGENT" --apply --json 2>/dev/null || true)"
+    if [ -n "$MIGRATION_JSON" ]; then
+      MIGRATED="$(printf '%s' "$MIGRATION_JSON" | python3 -c '
+import json, sys
+try:
+    report = json.load(sys.stdin)
+    print("1" if any(item.get("changed") for item in report.get("hosts", [])) else "0")
+except Exception:
+    print("0")
+' 2>/dev/null)"
+      if [ "$MIGRATED" = "1" ]; then
+        printf '[Superflow] 已备份并迁移当前项目旧 Hook；请重启本会话以加载新配置。\n' >&2
+      fi
+      printf '%s\n' "$(date +%s)" > "$PROJECT_STAMP" 2>/dev/null || true
+    fi
+  fi
+fi
+
 now_epoch() {
   date +%s
 }

package/assets/scripts/superflow-doc-placement-hook.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Advisory Markdown placement reminder; always exits successfully."""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = {"README.md", "AGENTS.md", "CLAUDE.md", "CONTEXT.md", "CHANGELOG.md"}
+
+def main():
+    try:
+        data = json.loads(sys.stdin.read() or "{}")
+        tool = data.get("tool_input") or {}
+        raw = tool.get("file_path") or ""
+        if not raw.lower().endswith(".md"):
+            return 0
+        cwd = Path(data.get("cwd") or os.getcwd()).resolve()
+        path = Path(raw).expanduser()
+        path = (path if path.is_absolute() else cwd / path).resolve()
+        if path.exists():
+            return 0
+        try:
+            relative = path.relative_to(cwd).as_posix()
+        except ValueError:
+            return 0
+        parts = relative.split("/")
+        if len(parts) == 1 and relative not in ROOT:
+            print(f"[Superflow 文档落位] 新建 {relative} 不在仓根白名单；"
+                  "任务产物建议放入 .ake/tasks/<日期>-<slug>/。", file=sys.stderr)
+        elif len(parts) == 2 and parts[0].lower() == "docs":
+            print(f"[Superflow 文档落位] 新建 {relative} 位于 docs/ 顶层；"
+                  "请放入 docs/adr/、docs/howto/ 等主题子目录。", file=sys.stderr)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        pass
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/scripts/superflow-enforce-hook.sh

@@ -11,6 +11,10 @@
 #
 # 退出码：0=允许  2=拦截
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 INPUT=$(cat)
 
 FILE_PATH=$(echo "$INPUT" | python3 -c "

package/assets/scripts/superflow-hook-guard.sh

@@ -2,6 +2,10 @@
 # SDD phase-aware hook guard.
 # Blocks writes that conflict with .sdd/state.yaml when .sdd-enforced is active.
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 set -u
 
 INPUT=""

package/assets/scripts/superflow-integration-evidence-hook.sh

@@ -3,6 +3,10 @@
 # When .sdd-enforced is active, block git commit for runtime code changes unless
 # staged test-report evidence passes superflow-verify-integration.sh.
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 INPUT=$(cat)
 
 COMMAND=$(echo "$INPUT" | python3 -c "

package/assets/scripts/superflow-java-build-hook.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Record Java edits and compile affected Maven/Gradle modules once at Stop."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+BUILD_FILES = {"pom.xml", "build.gradle", "build.gradle.kts",
+               "settings.gradle", "settings.gradle.kts", "gradle.properties"}
+
+
+def project_root():
+    result = subprocess.run(["git", "rev-parse", "--show-toplevel"],
+                            capture_output=True, text=True, check=False)
+    return Path(result.stdout.strip()).resolve() if result.returncode == 0 else None
+
+
+def state_file(root, payload):
+    session = str(payload.get("session_id") or os.environ.get("CODEX_SESSION_ID")
+                  or os.environ.get("CLAUDE_CODE_SESSION_ID") or "default")
+    safe = "".join(char if char.isalnum() or char in "-_" else "_" for char in session)
+    import hashlib
+    digest = hashlib.sha256(str(root).encode()).hexdigest()[:12]
+    return Path(tempfile.gettempdir()) / f"superflow-java-edits-{digest}-{safe}.txt"
+
+
+def in_root(root, file_path):
+    try:
+        path = Path(file_path).expanduser()
+        path = (path if path.is_absolute() else root / path).resolve()
+        path.relative_to(root)
+        return path
+    except (ValueError, OSError):
+        return None
+
+
+def record(root, payload):
+    tool_input = payload.get("tool_input") or {}
+    targets = [tool_input.get("file_path")]
+    patch = tool_input.get("patch") or ""
+    targets += re.findall(r"^\*\*\* (?:Add|Update|Delete) File: (.+)$",
+                          patch, re.M)
+    paths = [in_root(root, target) for target in targets if target]
+    relevant = {path for path in paths if path and
+                (path.suffix == ".java" or path.name in BUILD_FILES)}
+    if relevant:
+        with state_file(root, payload).open("a", encoding="utf-8") as state:
+            state.write("\n".join(str(path) for path in sorted(relevant)) + "\n")
+    return 0
+
+
+def build_root(root, file_path):
+    directory = file_path.parent
+    while directory == root or root in directory.parents:
+        if any((directory / name).is_file()
+               for name in ("pom.xml", "build.gradle", "build.gradle.kts")):
+            return directory
+        if directory == root:
+            break
+        directory = directory.parent
+    return None
+
+
+def maven_reactor(root, module):
+    current = module.parent
+    while current == root or root in current.parents:
+        pom = current / "pom.xml"
+        if pom.is_file():
+            relative = module.relative_to(current).as_posix()
+            pattern = r"<module>\s*" + re.escape(relative) + r"\s*</module>"
+            if re.search(pattern, pom.read_text(encoding="utf-8")):
+                return current, relative
+        if current == root:
+            break
+        current = current.parent
+    return module, None
+
+
+def gradle_reactor(root, module):
+    current = module.parent
+    while current == root or root in current.parents:
+        settings = current / "settings.gradle"
+        kotlin = current / "settings.gradle.kts"
+        config = settings if settings.is_file() else kotlin
+        if config.is_file():
+            relative = module.relative_to(current).as_posix().replace("/", ":")
+            if f":{relative}" in config.read_text(encoding="utf-8"):
+                return current, f":{relative}:compileJava"
+        if current == root:
+            break
+        current = current.parent
+    return module, "compileJava"
+
+
+def compile_command(root, modules):
+    module = modules[0]
+    if (module / "pom.xml").is_file():
+        reactor, _ = maven_reactor(root, module)
+        executable = reactor / "mvnw"
+        command = str(executable) if executable.is_file() else shutil.which("mvn")
+        if not command:
+            return None, "未找到 mvn/mvnw，无法确认编译结果"
+        args = [command, "-q", "-f", str(reactor / "pom.xml")]
+        relatives = [maven_reactor(root, item)[1] for item in modules]
+        if all(relatives):
+            args += ["-pl", ",".join(sorted(relatives)), "-am"]
+        return args + ["compile"], None
+    reactor, _ = gradle_reactor(root, module)
+    executable = reactor / "gradlew"
+    command = str(executable) if executable.is_file() else shutil.which("gradle")
+    if not command:
+        return None, "未找到 gradle/gradlew，无法确认编译结果"
+    tasks = sorted({gradle_reactor(root, item)[1] for item in modules})
+    return [command, "-q", "-p", str(reactor), *tasks], None
+
+
+def stop(root, payload):
+    state = state_file(root, payload)
+    if not state.is_file():
+        return 0
+    files = {in_root(root, line.strip()) for line in state.read_text().splitlines()}
+    modules = {build_root(root, file) for file in files if file}
+    modules.discard(None)
+    if not modules:
+        state.unlink(missing_ok=True)
+        return 0
+    groups = {}
+    for module in modules:
+        if (module / "pom.xml").is_file():
+            reactor, _ = maven_reactor(root, module)
+        else:
+            reactor, _ = gradle_reactor(root, module)
+        groups.setdefault(reactor, []).append(module)
+    for reactor, members in sorted(groups.items()):
+        command, error = compile_command(root, sorted(members))
+        if error:
+            print(f"[Superflow Java 编译] {reactor}: {error}", file=sys.stderr)
+            return 2
+        try:
+            result = subprocess.run(command, cwd=root, capture_output=True,
+                                    text=True, timeout=120, check=False)
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            print(f"[Superflow Java 编译] {reactor}: {exc}", file=sys.stderr)
+            return 2
+        if result.returncode:
+            detail = (result.stdout + result.stderr).strip()[-3000:]
+            print(f"[Superflow Java 编译] {reactor} 编译失败：\n{detail}",
+                  file=sys.stderr)
+            return 2
+    state.unlink(missing_ok=True)
+    return 0
+
+
+def main():
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        return 0
+    root = project_root()
+    if not root or not ((root / "openspec").exists() or
+                        (root / ".sdd").exists() or
+                        (root / ".sdd-enforced").exists()):
+        return 0
+    try:
+        return stop(root, payload) if "--stop" in sys.argv else record(root, payload)
+    except OSError as exc:
+        print(f"[Superflow Java 编译] Hook 内部错误：{exc}", file=sys.stderr)
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/scripts/superflow-java-stop-hook.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/superflow-java-build-hook.py" --stop

package/assets/scripts/superflow-loop-end-hook.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/superflow-loop-observer.py" --end

package/assets/scripts/superflow-loop-failure-hook.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/superflow-loop-observer.py" --failure

package/assets/scripts/superflow-loop-observer.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Fail-open session observation for repeated edits and tool failures."""
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+EDIT_WINDOW = 600
+FAILURE_WINDOW = 300
+EDIT_LIMIT = 5
+FAILURE_LIMIT = 3
+
+
+def project_root():
+    result = subprocess.run(["git", "rev-parse", "--show-toplevel"],
+                            capture_output=True, text=True, check=False)
+    return Path(result.stdout.strip()).resolve() if result.returncode == 0 else None
+
+
+def state_path(root, payload):
+    session = (payload.get("session_id") or
+               os.environ.get("CODEX_SESSION_ID") or
+               os.environ.get("CLAUDE_CODE_SESSION_ID"))
+    if not session:
+        return None
+    identity = f"{root}:{session}"
+    digest = hashlib.sha256(identity.encode()).hexdigest()[:24]
+    return Path(tempfile.gettempdir()) / f"superflow-loop-{digest}.json"
+
+
+def load_state(file):
+    if not file.is_file():
+        return {"edits": {}, "failures": {}}
+    try:
+        data = json.loads(file.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            return {"edits": data.get("edits", {}),
+                    "failures": data.get("failures", {})}
+    except (OSError, ValueError):
+        pass
+    return {"edits": {}, "failures": {}}
+
+
+def save_state(file, state):
+    temporary = file.with_suffix(".tmp")
+    temporary.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+    temporary.replace(file)
+
+
+def recent(values, now, window):
+    return [stamp for stamp in values if isinstance(stamp, (int, float))
+            and 0 <= now - stamp < window]
+
+
+def edited_paths(root, payload):
+    tool_input = payload.get("tool_input") or {}
+    paths = [tool_input.get("file_path")]
+    patch = tool_input.get("patch") or ""
+    paths += re.findall(r"^\*\*\* (?:Add|Update|Delete) File: (.+)$", patch, re.M)
+    result = set()
+    for raw in paths:
+        if not isinstance(raw, str) or not raw:
+            continue
+        candidate = Path(raw).expanduser()
+        candidate = (candidate if candidate.is_absolute() else root / candidate).resolve()
+        try:
+            result.add(candidate.relative_to(root).as_posix())
+        except ValueError:
+            continue
+    return result
+
+
+def observe_success(root, payload, state, now):
+    tool = str(payload.get("tool_name") or "unknown")
+    state["failures"].pop(tool, None)
+    if not re.search(r"(?:^|[._])(Edit|Write|MultiEdit|apply_patch)$", tool, re.I):
+        return
+    for path in edited_paths(root, payload):
+        entry = state["edits"].get(path, {})
+        stamps = recent(entry.get("times", []), now, EDIT_WINDOW)
+        was_warned = bool(entry.get("warned")) and bool(stamps)
+        stamps.append(now)
+        state["edits"][path] = {"times": stamps, "warned": was_warned}
+        if len(stamps) > EDIT_LIMIT and not was_warned:
+            print(f"[Superflow 循环提醒] {path} 在 10 分钟内修改 {len(stamps)} 次；"
+                  "请核对失败原因和实现方案。", file=sys.stderr)
+            state["edits"][path]["warned"] = True
+
+
+def observe_failure(payload, state, now):
+    tool = str(payload.get("tool_name") or "unknown")
+    entry = state["failures"].get(tool, {})
+    stamps = recent(entry.get("times", []), now, FAILURE_WINDOW)
+    was_warned = bool(entry.get("warned")) and bool(stamps)
+    stamps.append(now)
+    state["failures"][tool] = {"times": stamps, "warned": was_warned}
+    if len(stamps) >= FAILURE_LIMIT and not was_warned:
+        print(f"[Superflow 失败提醒] {tool} 在 5 分钟内连续失败 "
+              f"{len(stamps)} 次；先分析原因，再决定是否重试。", file=sys.stderr)
+        state["failures"][tool]["warned"] = True
+
+
+def prune_state(state, now):
+    for bucket, window in (("edits", EDIT_WINDOW), ("failures", FAILURE_WINDOW)):
+        for key, entry in list(state[bucket].items()):
+            if not isinstance(entry, dict):
+                del state[bucket][key]
+                continue
+            entry["times"] = recent(entry.get("times", []), now, window)
+            if not entry["times"]:
+                del state[bucket][key]
+
+
+def main():
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        root = project_root()
+        if not root or not ((root / "openspec").exists() or
+                            (root / ".sdd").exists() or
+                            (root / ".sdd-enforced").exists()):
+            return 0
+        file = state_path(root, payload)
+        if file is None:
+            return 0
+        if "--end" in sys.argv:
+            file.unlink(missing_ok=True)
+            return 0
+        state = load_state(file)
+        now = time.time()
+        prune_state(state, now)
+        if "--failure" in sys.argv:
+            observe_failure(payload, state, now)
+        else:
+            observe_success(root, payload, state, now)
+        save_state(file, state)
+    except (OSError, ValueError, TypeError, AttributeError):
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/scripts/superflow-managed-work-guard.sh

@@ -1,6 +1,10 @@
 #!/bin/bash
 # Managed-work role guard. Active only inside a Superflow managed Agent process.
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+[ -d openspec ] || [ -d .sdd ] || [ -f .sdd-enforced ] || exit 0
+
 set -u
 
 ROLE="${SUPERFLOW_MANAGED_ROLE:-}"