Compare commits
11
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 weichen
|
7a6cfeefeb | ||
|
weichen
|
dec963c16f | ||
|
weichen
|
15881cd0e6 | ||
|
weichen
|
d73d2e8633 | ||
|
weichen
|
111f25c9a8 | ||
|
weichen
|
e5e09560c7 | ||
|
weichen
|
b67816a898 | ||
|
weichen
|
56eb0ed4fe | ||
|
weichen
|
8c9a12d996 | ||
|
weichen
|
dd30e061d8 | ||
|
weichen
|
2e826e7f58 |
@@ -1,49 +0,0 @@
|
||||
{
|
||||
"version": 1,
|
||||
"hooks": {
|
||||
"beforeShellExecution": [
|
||||
{
|
||||
"command": ".cursor/hooks/guard-git.sh",
|
||||
"matcher": "^git ",
|
||||
"timeout": 10,
|
||||
"failClosed": true
|
||||
},
|
||||
{
|
||||
"command": ".cursor/hooks/guard-pi-shell.sh",
|
||||
"matcher": "pi_subagents\\.py|pkill",
|
||||
"timeout": 10,
|
||||
"failClosed": true
|
||||
}
|
||||
],
|
||||
"beforeMCPExecution": [
|
||||
{
|
||||
"command": ".cursor/hooks/guard-pi-dispatch.sh",
|
||||
"matcher": "pi-subagents|pi_subagent_",
|
||||
"timeout": 10,
|
||||
"failClosed": true
|
||||
}
|
||||
],
|
||||
"postToolUse": [
|
||||
{
|
||||
"command": ".cursor/hooks/pi-receipt-context.sh",
|
||||
"matcher": "MCP: pi-subagents|pi_subagent_",
|
||||
"timeout": 10,
|
||||
"failClosed": false
|
||||
}
|
||||
],
|
||||
"sessionStart": [
|
||||
{
|
||||
"command": ".cursor/hooks/audit-session.sh",
|
||||
"timeout": 20,
|
||||
"failClosed": false
|
||||
}
|
||||
],
|
||||
"stop": [
|
||||
{
|
||||
"command": ".cursor/hooks/audit-session.sh",
|
||||
"timeout": 10,
|
||||
"failClosed": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,166 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Shared helpers for project Cursor hooks (advisory gates + audit/probe)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
KNOWN_ROLES = frozenset(
|
||||
{
|
||||
"research",
|
||||
"planning",
|
||||
"requirements_review",
|
||||
"plan_review",
|
||||
"code_review",
|
||||
"diagnosis",
|
||||
"test_run",
|
||||
"acceptance_check",
|
||||
"stage_notes",
|
||||
"report",
|
||||
"auxiliary",
|
||||
}
|
||||
)
|
||||
TEST_ROLES = frozenset({"test_run", "acceptance_check"})
|
||||
FULL_SHA = re.compile(r"^[0-9a-fA-F]{40}$")
|
||||
REQUEST_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
|
||||
|
||||
|
||||
def repo_root() -> Path:
|
||||
env = os.environ.get("CURSOR_PROJECT_DIR") or os.environ.get("CURSOR_WORKSPACE_ROOT")
|
||||
if env:
|
||||
return Path(env).resolve()
|
||||
# hooks run with cwd = project root
|
||||
return Path.cwd().resolve()
|
||||
|
||||
|
||||
def audit_path() -> Path:
|
||||
return repo_root() / ".cursor" / "hook-audit.jsonl"
|
||||
|
||||
|
||||
def probe_path() -> Path:
|
||||
return repo_root() / ".cursor" / "hook-probe.jsonl"
|
||||
|
||||
|
||||
def inventory_dir() -> Path:
|
||||
return repo_root() / ".cursor" / "hook-audit"
|
||||
|
||||
|
||||
def append_jsonl(path: Path, record: dict[str, Any]) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
record = dict(record)
|
||||
record.setdefault("ts", datetime.now(timezone.utc).isoformat())
|
||||
with path.open("a", encoding="utf-8") as fh:
|
||||
fh.write(json.dumps(record, ensure_ascii=False) + "\n")
|
||||
|
||||
|
||||
def read_stdin() -> str:
|
||||
return sys.stdin.read()
|
||||
|
||||
|
||||
def maybe_probe(raw: str, hook: str) -> None:
|
||||
if os.environ.get("CURSOR_HOOKS_PROBE", "").strip() not in ("1", "true", "TRUE", "yes"):
|
||||
return
|
||||
append_jsonl(
|
||||
probe_path(),
|
||||
{"hook": hook, "raw": raw[:65536], "raw_len": len(raw)},
|
||||
)
|
||||
|
||||
|
||||
def parse_json_loose(raw: str) -> dict[str, Any] | None:
|
||||
raw = (raw or "").strip()
|
||||
if not raw:
|
||||
return None
|
||||
try:
|
||||
data = json.loads(raw)
|
||||
except json.JSONDecodeError:
|
||||
return None
|
||||
return data if isinstance(data, dict) else None
|
||||
|
||||
|
||||
def first_key(data: dict[str, Any], *names: str) -> Any:
|
||||
for name in names:
|
||||
if name in data and data[name] is not None:
|
||||
return data[name]
|
||||
return None
|
||||
|
||||
|
||||
def normalize_tool_name(name: str | None) -> str | None:
|
||||
"""Strip Cursor MCP prefixes such as 'MCP:' / 'MCP: pi-subagents/'."""
|
||||
if name is None:
|
||||
return None
|
||||
n = str(name).strip()
|
||||
# Observed IDE postToolUse: tool_name == "MCP:pi_subagent_roles"
|
||||
if n.upper().startswith("MCP:"):
|
||||
n = n[4:].lstrip()
|
||||
# Rare: "MCP: pi-subagents/pi_subagent_run"
|
||||
if "/" in n and n.rsplit("/", 1)[-1].startswith("pi_subagent_"):
|
||||
n = n.rsplit("/", 1)[-1]
|
||||
return n or None
|
||||
|
||||
|
||||
def tool_name(data: dict[str, Any]) -> str | None:
|
||||
v = first_key(data, "tool_name", "mcp_tool_name", "name", "toolName")
|
||||
return normalize_tool_name(str(v) if v is not None else None)
|
||||
|
||||
|
||||
def mcp_server(data: dict[str, Any]) -> str | None:
|
||||
v = first_key(data, "mcp_server_name", "server", "mcpServer", "server_name")
|
||||
return str(v) if v is not None else None
|
||||
|
||||
|
||||
def tool_input(data: dict[str, Any]) -> dict[str, Any] | None:
|
||||
v = first_key(data, "tool_input", "arguments", "input", "toolInput", "params")
|
||||
if isinstance(v, dict):
|
||||
return v
|
||||
if isinstance(v, str):
|
||||
try:
|
||||
parsed = json.loads(v)
|
||||
return parsed if isinstance(parsed, dict) else None
|
||||
except json.JSONDecodeError:
|
||||
return None
|
||||
return None
|
||||
|
||||
|
||||
def shell_command(data: dict[str, Any]) -> str:
|
||||
v = first_key(data, "command", "shell_command", "cmd")
|
||||
return str(v) if v is not None else ""
|
||||
|
||||
|
||||
def emit(obj: dict[str, Any]) -> None:
|
||||
sys.stdout.write(json.dumps(obj, ensure_ascii=False))
|
||||
sys.stdout.flush()
|
||||
|
||||
|
||||
def allow() -> None:
|
||||
emit({"permission": "allow"})
|
||||
raise SystemExit(0)
|
||||
|
||||
|
||||
def ask(user_message: str, agent_message: str) -> None:
|
||||
emit(
|
||||
{
|
||||
"permission": "ask",
|
||||
"user_message": user_message,
|
||||
"agent_message": agent_message,
|
||||
}
|
||||
)
|
||||
raise SystemExit(0)
|
||||
|
||||
|
||||
def additional_context(text: str) -> None:
|
||||
emit({"additional_context": text})
|
||||
raise SystemExit(0)
|
||||
|
||||
|
||||
def audit(hook: str, code: str, **extra: Any) -> None:
|
||||
rec = {"hook": hook, "code": code}
|
||||
rec.update(extra)
|
||||
try:
|
||||
append_jsonl(audit_path(), rec)
|
||||
except OSError:
|
||||
pass
|
||||
@@ -1,4 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
exec python3 -B "$DIR/audit_session.py"
|
||||
@@ -1,101 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""sessionStart / stop: audit + optional fail-open inventory (no context injection)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
import _lib as lib # noqa: E402
|
||||
|
||||
HOOK = "audit-session"
|
||||
INVENTORY_TIMEOUT = 15
|
||||
|
||||
|
||||
def _run_inventory(root: Path) -> dict:
|
||||
out: dict = {"cleanup_report": None, "docs_drift": None, "errors": []}
|
||||
if os.environ.get("CURSOR_HOOKS_NO_INVENTORY", "").strip() in ("1", "true", "TRUE", "yes"):
|
||||
out["skipped"] = "CURSOR_HOOKS_NO_INVENTORY"
|
||||
return out
|
||||
agentctl = root / "scripts" / "agentctl.py"
|
||||
if not agentctl.is_file():
|
||||
out["errors"].append("agentctl.py missing")
|
||||
return out
|
||||
for label, args in (
|
||||
("cleanup_report", ["cleanup", "report"]),
|
||||
("docs_drift", ["docs", "drift"]),
|
||||
):
|
||||
try:
|
||||
r = subprocess.run(
|
||||
["python3", "-B", str(agentctl), *args],
|
||||
cwd=str(root),
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=INVENTORY_TIMEOUT,
|
||||
check=False,
|
||||
)
|
||||
payload = None
|
||||
for stream in (r.stdout, r.stderr):
|
||||
for line in (stream or "").splitlines():
|
||||
line = line.strip()
|
||||
if line.startswith("{"):
|
||||
try:
|
||||
payload = json.loads(line)
|
||||
break
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
if payload is not None:
|
||||
break
|
||||
out[label] = {
|
||||
"exit_code": r.returncode,
|
||||
"payload": payload,
|
||||
"stdout_tail": (r.stdout or "")[-2000:],
|
||||
"stderr_tail": (r.stderr or "")[-1000:],
|
||||
}
|
||||
except subprocess.TimeoutExpired:
|
||||
out["errors"].append(f"{label}: timeout>{INVENTORY_TIMEOUT}s")
|
||||
except OSError as exc:
|
||||
out["errors"].append(f"{label}: {exc}")
|
||||
return out
|
||||
|
||||
|
||||
def main() -> None:
|
||||
raw = lib.read_stdin()
|
||||
lib.maybe_probe(raw, HOOK)
|
||||
data = lib.parse_json_loose(raw) or {}
|
||||
event = str(
|
||||
lib.first_key(data, "hook_event_name", "event", "event_name", "type") or "unknown"
|
||||
)
|
||||
root = lib.repo_root()
|
||||
if "start" in event.lower() or event == "unknown":
|
||||
inv = _run_inventory(root)
|
||||
inv_path = None
|
||||
try:
|
||||
inv_dir = lib.inventory_dir()
|
||||
inv_dir.mkdir(parents=True, exist_ok=True)
|
||||
ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
|
||||
path = inv_dir / f"inventory-{ts}.json"
|
||||
path.write_text(json.dumps(inv, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
|
||||
inv_path = str(path)
|
||||
except OSError:
|
||||
pass
|
||||
lib.audit(
|
||||
HOOK,
|
||||
"SESSION_AUDIT",
|
||||
event=event,
|
||||
inventory_path=inv_path,
|
||||
inventory_errors=inv.get("errors"),
|
||||
)
|
||||
else:
|
||||
lib.audit(HOOK, "SESSION_AUDIT", event=event)
|
||||
|
||||
lib.emit({})
|
||||
raise SystemExit(0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,60 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Fail-closed red-line gate for destructive / unauthorized git. Does not replace agentctl leases.
|
||||
set -euo pipefail
|
||||
input=$(cat)
|
||||
command=$(printf '%s' "$input" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("command") or "")')
|
||||
|
||||
ask() {
|
||||
local user_msg="$1"
|
||||
local agent_msg="$2"
|
||||
python3 -c 'import json,sys; print(json.dumps({"permission":"ask","user_message":sys.argv[1],"agent_message":sys.argv[2]}))' "$user_msg" "$agent_msg"
|
||||
exit 0
|
||||
}
|
||||
|
||||
allow() {
|
||||
echo '{"permission":"allow"}'
|
||||
exit 0
|
||||
}
|
||||
|
||||
# Normalize whitespace for matching
|
||||
cmd=$(printf '%s' "$command" | tr '\n' ' ')
|
||||
|
||||
# Unauthorized push (user must confirm)
|
||||
if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])git([[:space:]]+-[^[:space:]]+)*[[:space:]]+push([[:space:]]|$)'; then
|
||||
ask "git push 需要显式用户授权（AGENTS remote_sync）。请确认后再继续。" \
|
||||
"Hook blocked git push pending user authorization."
|
||||
fi
|
||||
|
||||
# Destructive / force operations
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+.*(--force|-f)([[:space:]]|$)' \
|
||||
|| printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push[[:space:]].*\+'; then
|
||||
ask "检测到 git --force / 强推。破坏性操作须用户明确授权。" \
|
||||
"Hook requires confirmation for force git operation."
|
||||
fi
|
||||
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+reset[[:space:]]+.*--hard'; then
|
||||
ask "git reset --hard 会丢弃工作区。须用户明确授权。" \
|
||||
"Hook requires confirmation for git reset --hard."
|
||||
fi
|
||||
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+clean[[:space:]]+.*-[a-zA-Z]*f'; then
|
||||
ask "git clean -f 会删除未跟踪文件。须用户明确授权。" \
|
||||
"Hook requires confirmation for git clean -f."
|
||||
fi
|
||||
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+branch[[:space:]]+(-D|--delete[[:space:]]+--force)'; then
|
||||
ask "强制删分支 (-D) 须用户明确授权；优先 git branch -d。" \
|
||||
"Hook requires confirmation for git branch -D."
|
||||
fi
|
||||
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+worktree[[:space:]]+remove[[:space:]]+.*--force'; then
|
||||
ask "git worktree remove --force 被 AGENTS 禁止升级。须用户明确授权。" \
|
||||
"Hook requires confirmation for forced worktree remove."
|
||||
fi
|
||||
|
||||
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+checkout[[:space:]]+--\.($|[[:space:]])'; then
|
||||
ask "git checkout -- . 会丢弃全部本地修改。须用户明确授权。" \
|
||||
"Hook requires confirmation for discarding all local changes."
|
||||
fi
|
||||
|
||||
allow
|
||||
@@ -1,5 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Thin wrapper: preserve stdin for Cursor hook JSON (do not use heredoc).
|
||||
set -euo pipefail
|
||||
DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
exec python3 -B "$DIR/guard_pi_dispatch.py"
|
||||
@@ -1,4 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
exec python3 -B "$DIR/guard_pi_shell.py"
|
||||
@@ -1,113 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Advisory beforeMCPExecution gate for pi-subagents MCP tools."""
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
import _lib as lib # noqa: E402
|
||||
|
||||
HOOK = "guard-pi-dispatch"
|
||||
|
||||
|
||||
def main() -> None:
|
||||
raw = lib.read_stdin()
|
||||
lib.maybe_probe(raw, HOOK)
|
||||
data = lib.parse_json_loose(raw)
|
||||
if data is None:
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="non_json_or_empty")
|
||||
lib.allow()
|
||||
|
||||
name = lib.tool_name(data)
|
||||
server = lib.mcp_server(data)
|
||||
if not name:
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="missing_tool_name", keys=sorted(data.keys())[:40])
|
||||
lib.allow()
|
||||
|
||||
if server and "pi-subagents" not in server and not name.startswith("pi_subagent_"):
|
||||
if not name.startswith("pi_subagent_"):
|
||||
lib.allow()
|
||||
|
||||
if name in ("pi_subagent_roles", "pi_subagent_result"):
|
||||
lib.allow()
|
||||
|
||||
if name != "pi_subagent_run":
|
||||
if name.startswith("pi_subagent_"):
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="unknown_pi_tool", tool=name)
|
||||
lib.allow()
|
||||
|
||||
args = lib.tool_input(data) or {}
|
||||
req = args.get("request") if isinstance(args.get("request"), dict) else args
|
||||
if not isinstance(req, dict):
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="missing_request")
|
||||
lib.ask(
|
||||
"pi_subagent_run 缺少可识别的 request 对象。请核对 MCP 参数后再继续。",
|
||||
"Hook: unrecognized request shape for pi_subagent_run.",
|
||||
)
|
||||
|
||||
role = req.get("role_id")
|
||||
request_id = req.get("request_id")
|
||||
goal = req.get("goal")
|
||||
auth = req.get("authorization_ref")
|
||||
source_sha = req.get("source_sha")
|
||||
input_files = req.get("input_files")
|
||||
timeout = req.get("timeout_seconds")
|
||||
|
||||
problems: list[str] = []
|
||||
|
||||
if not role or not isinstance(role, str):
|
||||
problems.append("role_id 缺失")
|
||||
elif role not in lib.KNOWN_ROLES:
|
||||
problems.append(f"role_id={role!r} 不在已知角色表")
|
||||
|
||||
if not request_id or not isinstance(request_id, str) or not lib.REQUEST_ID.match(request_id):
|
||||
problems.append("request_id 非法（需字母数字开头，长度≤128）")
|
||||
|
||||
if not goal or not isinstance(goal, str) or not goal.strip():
|
||||
problems.append("goal 为空")
|
||||
|
||||
if not auth or not isinstance(auth, str) or not auth.strip():
|
||||
problems.append("authorization_ref 为空")
|
||||
|
||||
if not isinstance(source_sha, str) or not lib.FULL_SHA.match(source_sha):
|
||||
problems.append("source_sha 必须是完整 40-hex 提交（禁止 HEAD/分支名/短 hash）")
|
||||
|
||||
if not isinstance(input_files, list):
|
||||
problems.append("input_files 必须是数组")
|
||||
|
||||
if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout <= 0:
|
||||
if isinstance(timeout, float) and timeout.is_integer() and timeout > 0:
|
||||
pass
|
||||
else:
|
||||
problems.append("timeout_seconds 必须是正整数")
|
||||
|
||||
if isinstance(role, str) and role in lib.TEST_ROLES:
|
||||
cmds = req.get("approved_commands")
|
||||
digest = req.get("plan_digest")
|
||||
if not isinstance(cmds, list) or not cmds:
|
||||
problems.append("test 角色需要 approved_commands（argv 数组的数组）")
|
||||
elif any(not isinstance(c, list) or not all(isinstance(x, str) for x in c) for c in cmds):
|
||||
problems.append("approved_commands 形状错误（应为字符串数组的数组）")
|
||||
if not isinstance(digest, str) or len(digest) != 64 or any(
|
||||
c not in "0123456789abcdefABCDEF" for c in digest
|
||||
):
|
||||
problems.append("plan_digest 必须是 64-hex SHA-256")
|
||||
|
||||
if "model_override" in req and req.get("model_override") is not None:
|
||||
problems.append("出现 model_override（禁止静默换模型；请用任务 override）")
|
||||
|
||||
if problems:
|
||||
detail = "；".join(problems)
|
||||
lib.audit(HOOK, "SHAPE_ASK", tool=name, problems=problems, role=role, request_id=request_id)
|
||||
lib.ask(
|
||||
f"pi_subagent_run 形状检查未通过：{detail}。执行器仍会硬校验；确认后继续或修正参数。",
|
||||
f"Hook advisory: {detail}",
|
||||
)
|
||||
|
||||
lib.audit(HOOK, "ALLOW", tool=name, role=role, request_id=request_id)
|
||||
lib.allow()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,56 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Advisory beforeShellExecution: bare pi_subagents.py run / broad pkill."""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
import _lib as lib # noqa: E402
|
||||
|
||||
HOOK = "guard-pi-shell"
|
||||
|
||||
|
||||
def main() -> None:
|
||||
raw = lib.read_stdin()
|
||||
lib.maybe_probe(raw, HOOK)
|
||||
data = lib.parse_json_loose(raw)
|
||||
if data is None:
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="non_json_or_empty")
|
||||
lib.allow()
|
||||
|
||||
cmd = lib.shell_command(data)
|
||||
if not cmd:
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="missing_command", keys=sorted(data.keys())[:40])
|
||||
lib.allow()
|
||||
|
||||
compact = re.sub(r"\s+", " ", cmd).strip()
|
||||
|
||||
if re.search(r"(^|[;&|]\s*)pkill(\s|$)", compact) and re.search(r"\s-f(\s|$)", compact):
|
||||
lib.audit(HOOK, "PKILL_ASK", command=compact[:500])
|
||||
lib.ask(
|
||||
"检测到 pkill -f（广谱杀进程）。AGENTS/PI 规则禁止广谱杀；请确认范围后再继续。",
|
||||
"Hook requires confirmation for pkill -f.",
|
||||
)
|
||||
|
||||
if re.search(r"pi_subagents\.py(\s|$)", compact) and re.search(r"(^|\s)run(\s|$)", compact):
|
||||
has_lease = (
|
||||
re.search(r"agentctl(\.py)?\s+with\b", compact) is not None
|
||||
and re.search(r"--resource\s+path:", compact) is not None
|
||||
)
|
||||
if re.search(r"pi_subagents\.py\s+(roles|result|status|config)\b", compact):
|
||||
lib.allow()
|
||||
if not has_lease:
|
||||
lib.audit(HOOK, "BARE_RUN_ASK", command=compact[:500])
|
||||
lib.ask(
|
||||
"裸调 pi_subagents.py run 缺少 agentctl with --resource path:… 租约。"
|
||||
"报告路径须在 path:.doc/test-reports/assets/pi-subagents/<task>/<request> 租约内。",
|
||||
"Hook: bare PI run without lease resource.",
|
||||
)
|
||||
|
||||
lib.allow()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,4 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
exec python3 -B "$DIR/pi_receipt_context.py"
|
||||
@@ -1,48 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""postToolUse: inject receipt-check reminders after pi-subagents tools."""
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
import _lib as lib # noqa: E402
|
||||
|
||||
HOOK = "pi-receipt-context"
|
||||
|
||||
REMINDER = """[PI subagent receipt checklist]
|
||||
- 核对 report/receipt 路径：.doc/test-reports/assets/pi-subagents/<task_id>/<request_id>/
|
||||
- 记录 config_revision / config_sha256 / configured vs actual_model（不可观察填 unknown）
|
||||
- run_status=succeeded 不等于阶段 PASS；review_state 仍可为 pending
|
||||
- 测试 pass 只来自批准命令证据（approved_commands），不能用模型叙事冒充
|
||||
- 推进门禁前用 subagent-stage-record skill 写回传与阶段收据
|
||||
"""
|
||||
|
||||
|
||||
def main() -> None:
|
||||
raw = lib.read_stdin()
|
||||
lib.maybe_probe(raw, HOOK)
|
||||
data = lib.parse_json_loose(raw)
|
||||
if data is None:
|
||||
lib.audit(HOOK, "UNRECOGNIZED_INPUT", reason="non_json_or_empty")
|
||||
lib.emit({})
|
||||
raise SystemExit(0)
|
||||
|
||||
name = lib.tool_name(data) or ""
|
||||
server = lib.mcp_server(data) or ""
|
||||
blob = raw
|
||||
is_pi = (
|
||||
name.startswith("pi_subagent_")
|
||||
or "pi-subagents" in server
|
||||
or "pi_subagent_" in blob
|
||||
)
|
||||
if not is_pi:
|
||||
lib.emit({})
|
||||
raise SystemExit(0)
|
||||
|
||||
lib.audit(HOOK, "CONTEXT_INJECT", tool=name or "unknown")
|
||||
lib.additional_context(REMINDER)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,24 +0,0 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"agentctl": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["scripts/mcp/agentctl-mcp.mjs"]
|
||||
},
|
||||
"jev": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["scripts/mcp/jev-mcp.mjs"]
|
||||
},
|
||||
"codegraph": {
|
||||
"type": "stdio",
|
||||
"command": "codegraph",
|
||||
"args": ["serve", "--mcp", "--path", "${workspaceFolder}"]
|
||||
},
|
||||
"pi-subagents": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["scripts/mcp/pi-subagents-mcp.mjs"]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,25 @@
|
||||
---
|
||||
description: 任务分级、授权、文档与收口入口
|
||||
description: 强制 Agent 文档同步与 ops 协作纪律；详情见 AGENTS.md
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
遵循 [AGENTS](../../AGENTS.md) 的启动、任务分级与收口规则。写入文档前读 [文档地图](../../.doc/README.md)；创建、集成、环境操作、清理前读 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md)。
|
||||
# Agent 文档同步（强制）
|
||||
|
||||
完整规范见 [AGENTS.md](../../AGENTS.md) 与 [PROJECT.md](../../PROJECT.md)。
|
||||
|
||||
## 开场必读
|
||||
|
||||
1. `AGENTS.md` → `PROJECT.md` → `.doc/README.md` → `.doc/ops/CURRENT.md` → `FEATURE-MATRIX` → short-term / handoff
|
||||
|
||||
## 红线
|
||||
|
||||
- 任务开始前：short-term/long-term + CURRENT 并行认领（mutex）
|
||||
- 合 dev + 容器测：占用 CURRENT 集成槽位；他人 queue 等待
|
||||
- 多 Agent 并行：worktree（`.worktrees/`）；禁止 worktree 内 env-service start
|
||||
- 禁止只改代码；done 任务 → `archive/ops/`
|
||||
- 验收报告 → `.doc/test-reports/`；运行产物 → `test-reports/assets/`
|
||||
- 禁止在 `.doc/` 根或 `docs/` 随意新建文档
|
||||
|
||||
## 状态
|
||||
|
||||
`planned | in_progress | blocked | done | cancelled`
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
description: Agent-System 写操作必须经 agentctl（租约、docs apply、候选合入）；禁止绕过治理直接改共享文档或 push。
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# agentctl 强制治理
|
||||
|
||||
本仓库由 agentctl 管理面协调（SQLite + launchd daemon）。细则见 [AGENTS.md](../../AGENTS.md) 与 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md)；流程技能见 `.cursor/skills/agentctl-*`。
|
||||
|
||||
## 硬边界
|
||||
|
||||
1. **写仓库**：必须 `agentctl with` / MCP `lease_run`。裸 `git commit` 会被 agentctl pre-commit hook 拒绝。
|
||||
2. **共享文档**：`.doc/ops/CURRENT.md`、`.doc/status/FEATURE-MATRIX.md` 只能 `docs apply`（行级 CAS；MATRIX 键为 `record_id`）。
|
||||
3. **合入 local dev**：`validate` 后 `queue enqueue`（daemon `--ff-only`）或受控 `integrate`；禁止直接改主目录 `dev` tip。
|
||||
4. **禁止默认**：未授权 `git push`、晋升 test/main、`--force` 清理、卸载 launchd coordinator、改 gap-matrix / 升 MATRIX 状态值冒充发布。
|
||||
5. **需求重叠**：跨对话新设计须 `catalog overlap`；硬重叠拒绝；软重叠须 `catalog ack` 留痕后方可编码（见 `.doc/ops/2026-09-24-governance-catalog-plan.md`）。
|
||||
|
||||
## 会话路径
|
||||
|
||||
- 启动 → skill `agentctl-session-start`
|
||||
- 建场 → `agentctl-worktree-setup`
|
||||
- 写回 → `agentctl-lease-write`
|
||||
- 合入/收口 → `agentctl-integrate-closeout`
|
||||
- PI 派发 → skill `pi-subagent-dispatch`（MCP `pi-subagents`）
|
||||
- 阶段落盘 → skill `subagent-stage-record`
|
||||
- MCP 工具定义见 `.cursor/mcp.json` → `scripts/mcp/agentctl-mcp.mjs` / `pi-subagents-mcp.mjs`
|
||||
- 客户端 hook 边界见规则 `cursor-hooks`
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
description: Cursor 对话自动生成的会话名称使用简体中文
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# 会话名称（中文）
|
||||
|
||||
Cursor 为本对话自动生成或建议的**会话名称 / 聊天标题**必须使用**简体中文**。
|
||||
|
||||
## 要求
|
||||
|
||||
- 用简短中文概括当前任务主题（约 6–16 字）
|
||||
- 优先动词/对象：如「创建会话中文命名规则」「修复登录超时」
|
||||
- 禁止默认英文标题（专有名词、命令、路径可保留原文，整体仍以中文为主）
|
||||
|
||||
## 示例
|
||||
|
||||
| 场景 | 可用标题 |
|
||||
|---|---|
|
||||
| 新建 Cursor 规则 | 创建会话中文命名规则 |
|
||||
| 排查 hook | 排查 pi-dispatch hook |
|
||||
| 合入 feature | 合入治理目录库变更 |
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
description: Project Cursor hooks are advisory gates layered on agentctl/PI executor hard checks; scripts exist does not mean Cursor loaded them.
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Cursor hooks（客户端门禁）
|
||||
|
||||
配置：`.cursor/hooks.json`；脚本：`.cursor/hooks/`。规范登记修订 `cursor-governance-2026-09-24-r1`。
|
||||
|
||||
## 分层
|
||||
|
||||
| 层 | 能力 | 说明 |
|
||||
|---|---|---|
|
||||
| 执行器 / agentctl | **enforced** | `scripts/pi_subagents.py`、租约、pre-commit 等硬拒绝 |
|
||||
| hook 脚本行为 | **enforced**（有单元回归） | stdin→stdout 契约可测 |
|
||||
| hook ↔ Cursor 接线 | **advisory / manual** | 官方事件字段未完全文档化；待 probe 采样后收紧 |
|
||||
|
||||
命中策略：与 `guard-git.sh` 一致，一律 `permission: ask`（不静默 deny）。
|
||||
|
||||
## 事件与脚本
|
||||
|
||||
- `beforeShellExecution`：`guard-git.sh`（破坏性 git）；`guard-pi-shell.sh`（裸调 `pi_subagents.py run`、`pkill -f`）
|
||||
- `beforeMCPExecution`：`guard-pi-dispatch.sh`（`pi_subagent_run` 形状）
|
||||
- `postToolUse`：`pi-receipt-context.sh`（注入收据核对提醒）
|
||||
- `sessionStart` / `stop`：`audit-session.sh`（审计 + 可选只读盘点；**不注入上下文**）
|
||||
|
||||
IDE 实测（2026-09-24）：`postToolUse` 的 `tool_name` 形如 `MCP:pi_subagent_roles`；hooks 须剥 `MCP:` 前缀后再匹配角色工具名。
|
||||
|
||||
## 审计与 probe
|
||||
|
||||
- 审计：`.cursor/hook-audit.jsonl`（gitignore；勿提交）
|
||||
- 盘点：`.cursor/hook-audit/inventory-*.json`
|
||||
- 采样：`CURSOR_HOOKS_PROBE=1` → `.cursor/hook-probe.jsonl`
|
||||
- 关闭盘点：`CURSOR_HOOKS_NO_INVENTORY=1`
|
||||
|
||||
异形/未知字段：**fail-open + 审计 `UNRECOGNIZED_INPUT`**，不因契约未知卡死会话。
|
||||
|
||||
## 红线
|
||||
|
||||
- 不把 hook 复刻成第二套执行器门禁
|
||||
- 脚本存在 ≠ Cursor 已加载；改 hooks 后检查 Hooks 设置页或通道
|
||||
- 审计日志不得放进被 git 跟踪的 `.cursor/hooks/` 目录
|
||||
@@ -1,6 +1,24 @@
|
||||
---
|
||||
description: 凭证与推送授权入口
|
||||
description: Git push 凭证自主读取；禁止向用户索要 token；详情见 AGENTS.md §8
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
遵循 [AGENTS 安全与证据](../../AGENTS.md#5-安全与证据)；授权推送的凭证和脚本入口见 [PROJECT](../../PROJECT.md#凭证与推送)。
|
||||
# Git Secrets 自主（禁止索要）
|
||||
|
||||
完整规范见 [AGENTS.md](../../AGENTS.md) §8 与 [PROJECT.md](../../PROJECT.md) §7。
|
||||
|
||||
## 本仓约定
|
||||
|
||||
- 凭证：`${HOME}/.secrets/gitea`
|
||||
- 字段：`- ACCESS_TOKEN=`、`- URL_PREFIX=`
|
||||
- 推送：优先 `./scripts/git-push-dev.sh <branch>`
|
||||
|
||||
## 禁止
|
||||
|
||||
- 向用户索要或要求粘贴 token
|
||||
- 在聊天/文档/commit 中展示 secret
|
||||
- 写入 git config 或提交到仓库
|
||||
|
||||
## 缺失时
|
||||
|
||||
在 `.doc/ops` 记 blocker（路径 + 缺字段），提示用户本机补齐后重试；**仍不索要内容**。
|
||||
|
||||
@@ -1,6 +1,60 @@
|
||||
---
|
||||
description: 分支、原子提交与环境操作入口
|
||||
description: 项目固定3分支模型(dev/test/main)、逐步渐进式提交规范与三套独立服务（知识库共享+对话与DB隔离）准则
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
分支/原子提交边界见 [AGENTS](../../AGENTS.md)，环境拓扑见 [PROJECT](../../PROJECT.md)。创建、集成、环境写操作及清理按 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md) 执行。
|
||||
# Git 三分支流转与三套服务环境架构准则
|
||||
|
||||
本仓库严格遵循以下固定分支体系、提交拆分规范与多套独立服务运行准则：
|
||||
|
||||
## 一、 Git 固定三分支体系
|
||||
|
||||
1. **开发分支 (`dev`)**:
|
||||
- **合入基线**，不是日常 commit 目标。
|
||||
- **禁止**在 `dev` 上直接开发提交（含 docs/chore）。
|
||||
- 一律从最新 `dev` 检出 `feature/<name>` 或 `fix/<name>`，在 feature 分支上渐进式提交；自测后占集成槽位，`--no-ff` 合回 `dev`，并删除临时子分支（见 [AGENTS.md](../../AGENTS.md) §6.2）。
|
||||
|
||||
2. **测试分支 (`test`)**:
|
||||
- 当 `dev` 积累了一定的功能阶段后，合并至 `test` 分支，创建阶段候选节点 Tag（如 `rc-vX.Y.Z-beta.1`）。
|
||||
- 用于较长时间的真实环境部署、全链路集成测试、运维稳定性检验。
|
||||
- **严禁**在 `test` 分支进行开发或直接 commit。
|
||||
|
||||
3. **主分支 (`main`)**:
|
||||
- 生产发布分支（Release）。
|
||||
- **严禁**直接在 `main` 上开发或 commit！
|
||||
- 只有 `test` 分支的代码经过实际运维和测试充分验证达到发布标准后，方可将对应验证节点合并回 `main` 分支，并打正式发布 Tag（如 `v1.0.0`）。
|
||||
|
||||
---
|
||||
|
||||
## 二、 任务拆分与渐进式提交规范 (Progressive Commits)
|
||||
|
||||
- **原子性拆分**：严禁把整个任务的大量改动揉合成一次庞大的提交。
|
||||
- **阶段逐步提交**：一个任务必须按功能逻辑分层逐步提交：
|
||||
1. `feat(db)` / `refactor(db)`: 数据表、模型、迁移脚本
|
||||
2. `feat(agent)` / `feat(service)`: 业务逻辑、智能体执行流程
|
||||
3. `feat(api)`: 接口路由与交互
|
||||
4. `test(...)`: 单元测试与集成测试用例
|
||||
5. `docs(...)` / `chore(...)`: 配置、运维脚本与文档同步
|
||||
- **提交规范**：遵循 Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`)。
|
||||
|
||||
---
|
||||
|
||||
## 三、 三套环境独立运行准则 (知识库共享 + 对话与DB隔离)
|
||||
|
||||
三套独立服务对应三个分支的运行态：
|
||||
|
||||
| 环境 | 分支 | Compose 项目 | HTTP 端口 | DB 端口 | 数据/对话路径 |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| **共享知识库** | 跨环境 | `agent-infra` | - | `5432` | `data/shared/kb` |
|
||||
| **开发环境** | `dev` | `agent-dev` | `8080` | `5433` | `data/dev` |
|
||||
| **测试环境** | `test` | `agent-test` | `8081` | `5434` | `data/test` |
|
||||
| **生产环境** | `main` | `agent-main` | `8000` | `5435` | `data/main` |
|
||||
|
||||
### 核心约束：
|
||||
1. **知识库共享**：
|
||||
- 三套环境服务均通过共享网络或内网连接同一个知识库数据库（`shuimu-kb-shared:5432`）。
|
||||
- 知识库法规、向量索引保持全局一致。
|
||||
2. **对话数据与数据库隔离（红线）**：
|
||||
- 各环境对话记录（Chat History）、Agent 思考工作区、审计事件及 SQLite/Postgres 业务库必须严格隔离！
|
||||
- 严禁任何环境读取或写入其他环境的对话数据与业务库。
|
||||
- 宿主机挂载目录严格区分：`data/dev/`、`data/test/`、`data/main/`。
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
description: Route PI analysis/review/test subagent work through scripts/pi_subagents.py (not Cursor native agents).
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# PI subagents（工程工具）
|
||||
|
||||
本机 PI 子任务走 `scripts/pi_subagents.py` + 模型配置 `.doc/ops/2026-09-24-subagent-model-config.md`。可执行步骤见 skill `pi-subagent-dispatch`；阶段记录见 `subagent-stage-record`。
|
||||
|
||||
## 自动派发（主 Agent）
|
||||
|
||||
1. **预览配置**：`pi_subagent_roles` / CLI `roles`（不调模型）。
|
||||
2. **按阶段选角色**：research → planning → reviews → diagnosis → test_run / acceptance_check → report；实施/修复仍由 Cursor Auto。
|
||||
3. **派发 `run`**：携带 task_id、role_id、唯一 request_id、goal、authorization_ref、冻结 source_sha、input_files、timeout；test 角色另附 approved_commands + plan_digest。
|
||||
4. **租约**：报告路径 `path:.doc/test-reports/assets/pi-subagents/<task>/<request>`；裸调拒绝。
|
||||
5. **取回**：`pi_subagent_result` / CLI `result`；`run_status` 与 `verdict`/`review_state` 分离——模型成功仅 `pending`，测试 pass 仅来自批准命令证据。
|
||||
6. **门禁**：审查/测试结论须带回报告路径与 receipt 字段；不得用模型叙事冒充 PASS。
|
||||
|
||||
## 边界
|
||||
|
||||
- **Cursor Auto**：唯一代码实施车道；本规则不把 implementation 派给 PI。
|
||||
- **禁止**：自动换模型、M3 关键角色、伪造 lease、递归把本修复任务再派给 PI worker、`pkill -f` 广谱杀进程。
|
||||
- **MCP**：`.cursor/mcp.json` → `pi-subagents`（roles/run/result）；executor 来自 MCP 安装根。
|
||||
- **Hook（advisory）**：`.cursor/hooks/guard-pi-dispatch.sh` / `guard-pi-shell.sh` 可在形状错误时 `ask`；**硬拒绝以执行器为准**，见规则 `cursor-hooks`。
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
description: Cursor-side test report path/naming conventions; validation scope comes from the validation contract.
|
||||
description: 规定项目中所有自动化测试、功能测试、集成测试报告的存放路径与结构标准规范
|
||||
globs: ["**/*test*.go", ".doc/test-reports/**/*.md"]
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# 测试报告规范准则 (Test Reports Standard)
|
||||
|
||||
本仓库严格遵循标准化、可追溯的质量测试管理体系。**验证范围、套件选择与模型证据的唯一来源**为 [验证契约](../../.doc/ops/2026-09-21-validation-contract.md)；本规则只约定 Cursor 侧的报告路径、命名与结构提醒，不另设第二套测试门禁。
|
||||
|
||||
**范围判定**：纯工程规范/文档变更按 [PROJECT.md 验证入口](../../PROJECT.md#验证入口) 与 [worktree 工作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md) 检查链接、规则一致性及 Git 差异；不适用产品 PI 全链路。报告注明 NOT REQUIRED 及依据，不能记成产品测试 PASS。运行模板、提示词和业务变更不属于此例外——按验证契约选层级。
|
||||
本仓库严格遵循标准化、可追溯的质量测试管理体系。所有测试报告必须归档于指定的文档目录下，并遵循固定结构。
|
||||
|
||||
## 一、 测试报告归档路径规范
|
||||
|
||||
@@ -16,9 +15,11 @@ alwaysApply: true
|
||||
- 例如：`.doc/test-reports/2026-09-07-three-branch-intent-framework-test-report.md`
|
||||
- **证据附件**：运行产物（json/jsonl、workspace 快照、截图）放 `.doc/test-reports/assets/<report-slug>/`，**不得**与 `*-test-report.md` 混放在同一层级目录。
|
||||
|
||||
---
|
||||
|
||||
## 二、 测试报告固定结构模板
|
||||
|
||||
每份独立测试报告应包含以下核心板块（小型文档/脚本任务可在任务主文档设验证节，无需机械拆报告）：
|
||||
每份测试报告必须包含以下核心板块：
|
||||
|
||||
```markdown
|
||||
# [功能/模块名称] 测试报告
|
||||
@@ -27,37 +28,38 @@ alwaysApply: true
|
||||
- 简述被测功能/特性的产生背景、业务痛点或上一轮测试中发现的缺陷与瓶颈。
|
||||
|
||||
## 二、 测试目标 (Test Objectives)
|
||||
- 列举本次测试需要验证的核心功能点、质量指标。
|
||||
- 列举本次测试需要验证的核心功能点、质量指标（如通过率 100%、无流程卡点、非阻塞人机协同等）。
|
||||
|
||||
## 三、 测试方案与环境 (Test Plan & Environment)
|
||||
- 测试环境（OS、工具版本、目标环境批准配置）；
|
||||
- 测试层级分层（按验证契约矩阵选行）；
|
||||
- 测试环境（OS、Go 版本、后端 Stub/Real 模型）；
|
||||
- 测试层级分层（单元测试、协同集成测试、CLI 真实交互测试）；
|
||||
- 核心测试用例矩阵设计。
|
||||
|
||||
## 四、 预期结果 (Expected Results)
|
||||
- 明确给出各用例输入下的理论判定。
|
||||
- 明确给出各用例输入下的理论判定分支、目标意图、提取槽位、参谋回复风格与状态机流转。
|
||||
|
||||
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
|
||||
- 必须包含针对每一个典型测试用例的真实记录：
|
||||
- **测试输入 (Input)**
|
||||
- **实际输出 (Actual Output)**：贴出真实的终端/日志输出文本（可脱敏）
|
||||
- **评价判定 (Evaluation / Verdict)**：PASS / FAIL / SKIP / 未运行
|
||||
- **实际输出 (Actual Output)**：贴出真实的终端/日志输出文本
|
||||
- **评价判定 (Evaluation / Verdict)**：PASS / FAIL 标志及判定依据
|
||||
- **性能与耗时 (Duration & Latency)**
|
||||
|
||||
## 六、 自动化测试套件汇总 (Test Suite Execution)
|
||||
- 只列本次适用并**实际运行**的检查与通过率；不无条件要求全量 `go test`。
|
||||
- 工程工具改动优先 `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`（见验证契约「工程工具验收补充」）。
|
||||
- 附带 `go test -v ./...` 全量回归测试输出与通过率统计。
|
||||
|
||||
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
|
||||
- 总结测试是否达到授权交付终点，提出后续演进或强化点。
|
||||
- 总结测试是否达到上线/合并标准，提出后续演进或强化点。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、 执行要求与真实 Agent 交付铁律
|
||||
|
||||
1. **真实 Agent 交付铁律（红线）**：
|
||||
- **开发实现阶段**：可以快速使用 stub 验证状态机、协议分流、数据落盘与逻辑契约，加速反馈；
|
||||
- **交付前验收与测试报告生成**：涉及产品 Agent/工作流时，必须按验证契约「产品 PI 基线」在获授权环境用真实产品 PI Agent Runner 全链路实测；模型以目标环境批准配置为准，不得在本规则中硬编码模型名；
|
||||
- **严禁**使用 stub、SKIP、未运行输出作为最终交付报告的验收数据。
|
||||
2. **严禁散落存放**：测试报告统一归档至 `.doc/test-reports/`，禁止散落在根目录或临时沙箱中。
|
||||
- **开发实现阶段**：可以快速使用 `stub` 验证状态机、协议分流、数据落盘与逻辑契约，加速反馈；
|
||||
- **交付前验收与测试报告生成**：**必须切回真实环境与真实 Agent（`pi-agent` + 实际运行的 `MiniMax-M2.7-highspeed` 容器）进行全链路端到端实测**；
|
||||
- **严禁**使用 stub 的测试输出作为最终交付报告的验收数据。
|
||||
2. **严禁散落存放**：测试报告统一归档至 `.doc/test-reports/` 目录下，禁止散落在根目录或临时沙箱中。
|
||||
3. **真实控制台取样**：测试报告中的输入、输出、耗时与判定必须取自实际环境运行的真实控制台输出与日志。
|
||||
4. **Git 规范管理**：测试报告伴随对应阶段的 `docs(test)` 或 `test(...)` 规范提交入库。
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
name: agentctl-integrate-closeout
|
||||
description: Validate a merge candidate, enqueue for daemon ff-only integrate, and close out five-state. Use when ready to land a task on local dev.
|
||||
---
|
||||
|
||||
# agentctl 集成与收口
|
||||
|
||||
权威：[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)、[验证契约](../../../.doc/ops/2026-09-21-validation-contract.md)。常驻 daemon 已装载时走 **enqueue**，勿手动 `integrate`（除非 daemon 停）。
|
||||
|
||||
## 候选
|
||||
|
||||
优先一层封装（创建 integrate worktree、`task register`、`--no-ff` merge；**不** validate/enqueue）：
|
||||
|
||||
```bash
|
||||
D=$(git -C /path/to/Agent-System rev-parse HEAD) # 冻结 expected-dev
|
||||
python3 scripts/agentctl.py integrate prepare \
|
||||
--task <feature-task-id> --expected-dev "$D" \
|
||||
[--integrate-id integrate-<task>-YYYY-MM-DD]
|
||||
# 进入返回的 worktree 继续 validate → enqueue
|
||||
cd .worktrees/integrate-<task>-YYYY-MM-DD # 或 emit 中的 worktree
|
||||
```
|
||||
|
||||
第一父必须等于 `$D`。手工 `worktree add` + `with` + `merge --no-ff` 仍可用。
|
||||
|
||||
## validate → enqueue（daemon ff）
|
||||
|
||||
```bash
|
||||
python3 ../../scripts/agentctl.py validate --task "$ID" -- <验收命令>
|
||||
python3 ../../scripts/agentctl.py queue enqueue \
|
||||
--task "$ID" --expected-dev "$D" --head "$(git rev-parse HEAD)"
|
||||
# 在任务 worktree 内 enqueue；数秒内 daemon 合入
|
||||
python3 ../../scripts/agentctl.py queue list
|
||||
python3 ../../scripts/agentctl.py daemon status
|
||||
```
|
||||
|
||||
验收按验证契约选行；治理脚本用 `unittest discover`。
|
||||
|
||||
## 五态收口
|
||||
|
||||
| 字段 | 典型值 |
|
||||
|---|---|
|
||||
| review_state | accepted |
|
||||
| integration_state | merged_local_dev |
|
||||
| deployment | not_required 或 loaded_local_launchd |
|
||||
| cleanup | pending（独立维护者；禁止 `--force`） |
|
||||
| remote_sync | not_requested |
|
||||
|
||||
CURRENT 行 → `done`（`docs apply`）；`task close --status done`。
|
||||
|
||||
## 清理前
|
||||
|
||||
确认 tip 为 local_dev 祖先、证据已持久化、无 tracked/untracked 遗留、无进程占用。唯一日志/对话归档进 `.doc/ops/evidence/` 后再 `worktree remove`。
|
||||
|
||||
只读盘点（不自动删除、不自动写 MATRIX）：
|
||||
|
||||
```bash
|
||||
python3 ../../scripts/agentctl.py cleanup report # 主目录或任意同仓 cwd
|
||||
python3 ../../scripts/agentctl.py docs drift
|
||||
```
|
||||
|
||||
对 `verdict=ready` 的 worktree 由独立维护者执行 `agent-worktree.sh remove … --delete-branch`；拒绝则保留 cleanup_pending。daemon 未装载时用 `queue schedule --drain`（主目录 + 分支 dev）。
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
name: agentctl-lease-write
|
||||
description: Write under agentctl leases and docs apply CAS. Use before any git write, shared-doc edit, or when hitting UNMANAGED_DOCUMENT_CHANGE / EVIDENCE_REQUIRED.
|
||||
---
|
||||
|
||||
# agentctl 租约写回
|
||||
|
||||
权威：[AGENTS §3–5](../../../AGENTS.md)、[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)。
|
||||
|
||||
## 原则
|
||||
|
||||
- **任何仓库写**（含 `git add/commit`）必须在 `agentctl with` / MCP `lease_run` 租约内
|
||||
- CURRENT / FEATURE-MATRIX **只能** `docs apply`（行级 CAS；MATRIX 键为 `record_id`）
|
||||
- 直接 `git commit` 会被 agentctl-managed pre-commit hook 拒绝
|
||||
|
||||
## lease_run（CLI）
|
||||
|
||||
```bash
|
||||
python3 scripts/agentctl.py with \
|
||||
--task "$ID" \
|
||||
--resource path:scripts --resource path:.doc --resource git:index \
|
||||
-- bash -lc 'git add … && git commit -m "…"'
|
||||
```
|
||||
|
||||
MCP：`lease_run` 的 `command` 为 **argv 数组**（无额外 shell）。
|
||||
|
||||
## docs apply（行级）
|
||||
|
||||
```bash
|
||||
python3 scripts/agentctl.py docs snapshot --file .doc/ops/CURRENT.md --record "$RID"
|
||||
# expected_sha256 = snapshot.sha256；改 replacement 后：
|
||||
python3 scripts/agentctl.py docs apply --task "$ID" --request /tmp/req.json
|
||||
```
|
||||
|
||||
FEATURE-MATRIX 升 `done` 需要 `docs:approve` + 可核验 evidence（`git cat-file -e`），否则 `EVIDENCE_REQUIRED`。
|
||||
收口或合入含 MATRIX 的变更后跑 `python3 scripts/agentctl.py docs drift`：硬告警仅 `done→非 done`；不因任务结束自动升 done。
|
||||
|
||||
## 常见拒绝
|
||||
|
||||
| 码 | 处置 |
|
||||
|---|---|
|
||||
| `UNMANAGED_DOCUMENT_CHANGE` | 保留现场，先 snapshot/reconcile，勿覆盖 |
|
||||
| `BASE_CHANGED` | 重新 snapshot，基于新 sha 再 apply |
|
||||
| `AMBIGUOUS_RECORD` | 修重复 record_id / 模块名 |
|
||||
| `CAPABILITY_REQUIRED` | 任务缺 docs:admin / docs:approve |
|
||||
| `DOCUMENT_RECEIPT_REQUIRED` | 共享文档须经 apply 收据后再 commit |
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
name: agentctl-session-start
|
||||
description: Start an Agent-System session under agentctl governance. Use at session start, when opening a worktree, or before any write to this repo.
|
||||
---
|
||||
|
||||
# agentctl 会话启动
|
||||
|
||||
权威规范：[AGENTS.md](../../../AGENTS.md)、[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)、[CURRENT](../../../.doc/ops/CURRENT.md)。
|
||||
|
||||
## 步骤
|
||||
|
||||
1. 读 `AGENTS.md`、`PROJECT.md`、`.doc/ops/CURRENT.md` 活跃摘要（勿跳过）。
|
||||
2. 核对管理面：
|
||||
|
||||
```bash
|
||||
python3 scripts/agentctl.py daemon status
|
||||
# 期望：status=ok；launchd 已装载时 manager.lock.held=true
|
||||
```
|
||||
|
||||
或 MCP 工具 `status`。
|
||||
|
||||
3. 刷新 CodeGraph 索引（fail-open；CLI 缺失可跳过）：
|
||||
|
||||
```bash
|
||||
codegraph sync -q
|
||||
# 或：python3 scripts/agentctl.py hooks codegraph-sync
|
||||
```
|
||||
|
||||
跨文件定位优先用 CodeGraph MCP/`explore`；**grep 仍是完整性唯一权威**（假阴性时以 grep 为准）。
|
||||
|
||||
4. 若任务已存在：在注册 worktree 内工作，确认 `tasks.state=active`。
|
||||
5. **开工前需求重叠探测**（治理目录库）：新设计或可能与其他对话重叠时：
|
||||
|
||||
```bash
|
||||
python3 scripts/agentctl.py catalog search --query '<关键词>'
|
||||
python3 scripts/agentctl.py catalog overlap --task "$ID" --statement '<设计原文>' [--requirement R-xxx] [--feature <record_id>] [--mutex <key>]
|
||||
# soft 命中须显式裁决后才可编码：
|
||||
python3 scripts/agentctl.py catalog overlap ack --task "$ID" --overlap <oid> --decision proceed|merge_into|supersede|defer --reason '...'
|
||||
```
|
||||
|
||||
硬重叠（同 mutex/feature/scope/R-ID）直接拒绝；向量层失败自动降级到 FTS5，不阻断。
|
||||
|
||||
6. 若新任务：跟 [agentctl-worktree-setup](../agentctl-worktree-setup/SKILL.md)。
|
||||
7. 任何仓库写 → [agentctl-lease-write](../agentctl-lease-write/SKILL.md)；合入 → [agentctl-integrate-closeout](../agentctl-integrate-closeout/SKILL.md)。
|
||||
|
||||
## 禁止
|
||||
|
||||
- 主目录直接开发提交；未授权 `git push` / 晋升 test/main
|
||||
- 绕过 `docs apply` 改 CURRENT / FEATURE-MATRIX
|
||||
- 卸载或重启 launchd coordinator（除非用户明示）
|
||||
- 未执行 `catalog overlap` / 未裁决 soft 命中即编码（有 `--requirement`/`--intent`/`--feature`/`--mutex` 绑定时机器强制）
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
name: agentctl-worktree-setup
|
||||
description: Create an agentctl task worktree, register scopes/capabilities, and claim CURRENT. Use when starting a new feature/fix task in Agent-System.
|
||||
---
|
||||
|
||||
# agentctl 建场
|
||||
|
||||
权威：[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)。
|
||||
|
||||
## 命令序列
|
||||
|
||||
```bash
|
||||
cd /path/to/Agent-System # 主目录（dev）
|
||||
D=$(git rev-parse HEAD)
|
||||
ID=<task-id-YYYY-MM-DD>
|
||||
WT=.worktrees/$ID
|
||||
# 推荐入口：自动 best-effort codegraph init（后台；CLI 缺失不阻断）
|
||||
./scripts/agent-worktree.sh create feature/$ID
|
||||
# 等价：git worktree add -b feature/$ID "$WT" "$D"
|
||||
cd "$WT"
|
||||
python3 ../../scripts/agentctl.py task register \
|
||||
--id "$ID" --owner <Owner> \
|
||||
--scope scripts --scope .doc \
|
||||
--capability docs:publish
|
||||
# 需要整文/行级 admin 时再加 --capability docs:admin；证据升 done 加 docs:approve
|
||||
# 若已知需求/功能绑定，追加：
|
||||
# --requirement R-<slug> --intent '<设计原文>' --feature <record_id> --mutex <key>
|
||||
# 有 soft 重叠时 register 会 OVERLAP_ACK_REQUIRED：先 catalog overlap + ack 再重试 register
|
||||
codegraph sync -q # 若建场已 init，此处只需 sync；缺失 CLI 可跳过
|
||||
```
|
||||
|
||||
## 开工前重叠裁决（catalog）
|
||||
|
||||
```bash
|
||||
python3 ../../scripts/agentctl.py catalog overlap \
|
||||
--task "$ID" --statement '<新设计原文>' \
|
||||
[--requirement R-xxx] [--feature <record_id>] [--mutex <key>]
|
||||
# hard → 换 mutex/合并到持有者任务；soft → ack 留痕
|
||||
python3 ../../scripts/agentctl.py catalog ack \
|
||||
--task "$ID" --overlap <oid> \
|
||||
--decision proceed|merge_into|supersede|defer \
|
||||
--reason '<理由>'
|
||||
```
|
||||
|
||||
## CURRENT 认领
|
||||
|
||||
优先用一层封装（内部仍走 `docs apply` CAS）：
|
||||
|
||||
```bash
|
||||
python3 ../../scripts/agentctl.py claim new \
|
||||
--task "$ID" --owner <Owner> --mutex <mutex> \
|
||||
[--branch feature/$ID] [--worktree "$WT"] [--replace]
|
||||
```
|
||||
|
||||
手工 `docs snapshot` + `docs apply` 仍可用；行已存在且内容不同时需 `--replace`。
|
||||
|
||||
## short-term 模板字段
|
||||
|
||||
`status`、`write_scope`、`mutex`、`base_dev_sha`、`review_state`/`integration_state`/`deployment`/`cleanup`/`remote_sync`。命名 `.doc/ops/short-term/YYYY-MM-DD-<slug>.md`。
|
||||
|
||||
## 注意
|
||||
|
||||
- 从确切 `dev` SHA 创建，不从他人 feature 分支启动
|
||||
- 重叠 path/mutex 只允许一个写者
|
||||
- CodeGraph 索引是加速器：有假阴性；穷举调用方仍用 grep
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
name: jev-decide
|
||||
description: Use jev-service typed decisions (choice/noul/numeric with probabilities) for Agent-System governance classification. Use when choosing task tier, validation level, reject-code routing, or other closed-enum judgments.
|
||||
---
|
||||
|
||||
# jev-decide（治理决策）
|
||||
|
||||
依赖 MCP 服务器 `jev`（[`scripts/mcp/jev-mcp.mjs`](../../../scripts/mcp/jev-mcp.mjs)）。凭证在本机 `~/.secrets/jev/`（`api.key`、`base-url`），**禁止**写入仓库、commit 或聊天。
|
||||
|
||||
## 何时用
|
||||
|
||||
输入是情境文本、输出是**封闭枚举 / yes-no / 分桶数值**时调用 `jev_decide`，例如：
|
||||
|
||||
| 决策点 | 建议 questions |
|
||||
|---|---|
|
||||
| 任务分级（是否开 worktree） | `choice`：`info_reply` / `single_task` / `cross_module` |
|
||||
| 验证层级（验证契约） | `choice`（可多题）：`doc` / `script` / `go` / `frontend` / `migration` / `product_pi` |
|
||||
| 拒绝码处置 | `choice`：`reconcile` / `re_snapshot` / `fix_record_id` / `request_capability` / `abort` |
|
||||
| 是否 blocker / 是否触碰重验面 | `noul` |
|
||||
|
||||
不适合：需要解释链、多步规划、自由文本生成——那些走大模型或 agentctl 确定性门禁。
|
||||
|
||||
## 调用约定
|
||||
|
||||
1. 可选先 `jev_health`；失败则本机判断，勿阻塞写路径。
|
||||
2. `jev_decide`：同一情境的多问合成一次请求。
|
||||
3. 问句**正向措辞**，避免双重否定。
|
||||
4. 置信度路由：
|
||||
- `confidence >= 0.9` 且 top1−top2 ≥ 0.15 → 可采用
|
||||
- 否则 → agent 自行按规范裁定，把 jev 结果当参考
|
||||
5. 401/超时/`answers.*.error` → 降级到本机判断；勿把决策失败变成业务失败。
|
||||
|
||||
## 示例（任务分级）
|
||||
|
||||
```json
|
||||
{
|
||||
"context": "用户请求：给 CURRENT 加一行认领说明，不改代码",
|
||||
"questions": {
|
||||
"tier": {
|
||||
"type": "choice",
|
||||
"question": "This request matches which AGENTS task tier?",
|
||||
"options": ["info_reply", "single_task", "cross_module"]
|
||||
},
|
||||
"needs_worktree": {
|
||||
"type": "noul",
|
||||
"question": "Does this require a new feature/fix worktree?"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
权威矩阵仍以 [AGENTS.md](../../../AGENTS.md)、[验证契约](../../../.doc/ops/2026-09-21-validation-contract.md) 为准；jev 只加速封闭枚举分类，不替代机器门禁（admit/hooks/docs apply）。
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
name: pi-subagent-dispatch
|
||||
description: Dispatch gmktec PI analysis/review/test subagents via project MCP pi-subagents (roles/run/result). Use when delegating research, planning, reviews, diagnosis, test_run, acceptance_check, or report work—not for code implementation.
|
||||
---
|
||||
|
||||
# PI Subagent 派发
|
||||
|
||||
权威：[模型配置](../../../.doc/ops/2026-09-24-subagent-model-config.md)、[执行器说明](../../../.doc/ops/2026-09-24-pi-subagent-executor.md)、[流程规范](../../../.doc/ops/2026-09-24-subagent-workflow-standard.md)。客户端规则：[pi-subagents](../../rules/pi-subagents.mdc)。阶段落盘：[subagent-stage-record](../subagent-stage-record/SKILL.md)。
|
||||
|
||||
**Cursor Auto 独占代码实施与修复**；本 skill 只走本机 PI 子任务。
|
||||
|
||||
## 调用序列
|
||||
|
||||
1. `pi_subagent_roles` — 只读预览角色/模型（不调 PI）。
|
||||
2. 选 `role_id`（research → planning → reviews → diagnosis → test_run / acceptance_check → report）。
|
||||
3. （推荐）`agentctl pi packet` 生成派发包；**不**触发 run：
|
||||
```bash
|
||||
python3 -B scripts/agentctl.py pi packet \
|
||||
--task "$ID" --role research \
|
||||
--goal '…' --authorization-ref 'user:…' \
|
||||
--source-sha "$(git rev-parse HEAD)" \
|
||||
[--input-file …] [--approved-command '…']… \
|
||||
--request-id "$RID" --write
|
||||
# → .doc/test-reports/assets/pi-subagents/<task>/<request>/packet.json
|
||||
```
|
||||
4. `pi_subagent_run` — 按 packet 字段在 agentctl 租约下异步启动。
|
||||
5. `pi_subagent_result` — 取回收据；轮询至终态。
|
||||
|
||||
CLI 等价：`python3 -B scripts/pi_subagents.py roles|run|result`；`run` 必须包在 `agentctl with --resource path:.doc/test-reports/assets/pi-subagents/<task>/<request>` 内。
|
||||
|
||||
## 请求字段（MCP `pi_subagent_run`）
|
||||
|
||||
外层：`worktree`（已登记任务工作区绝对路径）、`task_id`、`request` 对象。
|
||||
|
||||
`request` 必填：
|
||||
|
||||
| 字段 | 约束 |
|
||||
|---|---|
|
||||
| `role_id` | 配置 §3 中 enabled 角色 |
|
||||
| `request_id` | 任务内稳定唯一；同参重放不重复调模型 |
|
||||
| `goal` | 具体目标；子任务不依赖主会话未传入历史 |
|
||||
| `authorization_ref` | 可回链真实用户授权，禁止日志自授 |
|
||||
| `source_sha` | **完整** 40-hex 提交；禁止 `HEAD`/分支名/短 hash |
|
||||
| `input_files` | 已跟踪 UTF-8 普通文件相对路径数组 |
|
||||
| `timeout_seconds` | 正整数 |
|
||||
|
||||
测试角色（`test_run` / `acceptance_check`）另需：
|
||||
|
||||
- `approved_commands`：argv 数组的数组（如 `[["go","test","-short","./"]]`）
|
||||
- `plan_digest`：外部已批准计划的 SHA-256 hex
|
||||
|
||||
禁止静默 `model_override`；临时改模型写任务 override 并说明用户来源。
|
||||
|
||||
## 租约与输出
|
||||
|
||||
- 资源：`path:.doc/test-reports/assets/pi-subagents/<task_id>/<request_id>`
|
||||
- 产物：`receipt.json`、`report.md`、命令日志（同目录）
|
||||
- 裸调 `run`（无租约）被拒绝
|
||||
|
||||
## 状态分离（红线）
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| `run_status` | running / succeeded / failed / cancelled / unknown |
|
||||
| `verdict` | pass / changes_required / blocked / not_applicable |
|
||||
| `review_state` | 阶段门禁；模型 succeeded **仅** pending |
|
||||
|
||||
测试 `commands_passed`/`pass` 只针对批准命令证据，不能直接赋给任务 `acceptance`。
|
||||
|
||||
## 常见拒绝码（执行器权威）
|
||||
|
||||
| 码 | 处置 |
|
||||
|---|---|
|
||||
| `INVALID_SOURCE_SHA` | 换完整提交 hash |
|
||||
| `APPROVED_COMMANDS_REQUIRED` | 补 approved_commands + plan_digest |
|
||||
| `MINIMAX_ROLE_FORBIDDEN` | 不把 M3 用于关键角色 |
|
||||
| `INPUT_NOT_TRACKED` / `PATH_OUT_OF_SCOPE` | 收窄 input_files |
|
||||
| `CONCURRENCY_LIMIT` | 串行或等空闲槽 |
|
||||
| `ORPHAN_RUNNING` | 先核进程/副作用，勿盲目重派 |
|
||||
|
||||
Cursor hooks 对形状错误可能 `permission=ask`（advisory）；**硬拒绝以执行器为准**。
|
||||
|
||||
## 禁止
|
||||
|
||||
- 把 implementation 派给 PI
|
||||
- 自动换模型 / 伪造 lease / 递归把本修复再派给 PI worker
|
||||
- 用模型叙事冒充 PASS；审查结论须带回报告路径与 receipt 字段
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: subagent-stage-record
|
||||
description: Record PI/Cursor stage handoffs using the subagent stage template (dispatch packet, return, S0–S9 receipt, R-AC-T mapping). Use after PI results, before gate advances, or when closing a multi-stage task.
|
||||
---
|
||||
|
||||
# Subagent 阶段记录
|
||||
|
||||
权威模板：[subagent-stage-record.md](../../../.doc/ops/templates/subagent-stage-record.md)；流程：[协作规范](../../../.doc/ops/2026-09-24-subagent-workflow-standard.md)。派发入口：[pi-subagent-dispatch](../pi-subagent-dispatch/SKILL.md)。
|
||||
|
||||
原则：**一步一记录，不必一步一文件**。小任务可把适用段落并入任务主文档；跨模块才拆独立审查/测试/验收证据。
|
||||
|
||||
## 何时写
|
||||
|
||||
- 每次 `pi_subagent_run` 前后：派发包 + 回传
|
||||
- 阶段门禁推进前：S0–S9 收据行
|
||||
- 收口前：R→AC→改动→审查→T→运行验收映射
|
||||
|
||||
## 派发包（最小字段）
|
||||
|
||||
复制到任务文档并填实值：
|
||||
|
||||
- `parent_task_id` / `subtask_id` / `stage_id` / `role_id`
|
||||
- 配置路径 / `config_revision` / `config_sha256`（来自 roles 或 receipt）
|
||||
- 解析后的 provider/model；任务 override 与用户来源
|
||||
- 目标、非目标、授权来源、交付终点
|
||||
- 输入版本：R-ID / AC-ID / 方案版本 / `base_sha` / `head_sha` 或 `source_sha`
|
||||
- cwd / branch / allowed_paths / 只读或写入 / mutex
|
||||
- 完成条件、输出路径、预算与异常处理
|
||||
|
||||
## 子任务回传
|
||||
|
||||
- PI `run_id` / producer / 起止时间
|
||||
- `configured_model` / `actual_model`（不可观察填 `unknown`）
|
||||
- `run_status` 与 `verdict` **分列**（不得把退出成功当质量通过）
|
||||
- 结论与依据、证据链接、脱敏范围
|
||||
- 未覆盖项、风险、遗留进程/产物、接管建议
|
||||
|
||||
只读子 Agent 结论由主 Agent 转存时：保留 `agent_id` 与原结论，注明「由主 Agent 转存」。
|
||||
|
||||
## 阶段收据表
|
||||
|
||||
| 阶段 | 输入版本 | 产物/证据 | producer | reviewer/独立性 | 决定 | 下一步 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| S0–S9 适用项 | | | | independent / self_review / not_required | pass / changes_required / blocked / not_applicable | |
|
||||
|
||||
未执行阶段写 `not_applicable` + 原因。报告存在不自动满足门禁。
|
||||
|
||||
## 需求追踪
|
||||
|
||||
| R-ID | AC-ID | 改动/版本 | 审查 | T-ID / 结果 | 运行验收 | acceptance_owner |
|
||||
|---|---|---|---|---|---|---|
|
||||
| | | | | | | |
|
||||
|
||||
## 与任务五态
|
||||
|
||||
继续用任务模板的 `status`、`review_state`、`integration_state`、`deployment`、`cleanup`、`remote_sync`；额外记 `phase`、`acceptance`、待回收 `subtask_id`。`done` 取决于授权交付终点，不因会话结束自动完成。
|
||||
+3
-14
@@ -11,10 +11,10 @@
|
||||
.doc/
|
||||
README.md ← 本文件（总地图）
|
||||
status/ ← 模块/功能完成度 SSOT
|
||||
audit/ ← 问题发现与分析、ISSUES.md 问题/修复台账
|
||||
audit/ ← 问题发现与分析
|
||||
remediation/ ← 整改方案与发布缺口
|
||||
archive/ ← 历史（只增不删）
|
||||
ops/ ← 活协作（任务、交接、调研；lessons/ 开发经验）
|
||||
ops/ ← 活协作（任务、交接、调研）
|
||||
system-design/ ← 模块架构深读
|
||||
adr/ ← 架构决策
|
||||
backlog/ ← 产品 backlog（非阻塞）
|
||||
@@ -33,16 +33,9 @@
|
||||
|
||||
| 我要… | 读这里 |
|
||||
|--------|--------|
|
||||
| Subagent 模型配置 / 流程 | [可调整模型配置](ops/2026-09-24-subagent-model-config.md) · [PI 执行器](ops/2026-09-24-pi-subagent-executor.md) · [流程草案](ops/2026-09-24-subagent-workflow-standard.md) · [研究依据](audit/2026-09-24-subagent-workflow-research.md) |
|
||||
| 规则来源/生效版本 | [规范登记](ops/2026-09-21-policy-registry.md) |
|
||||
| 选择测试/报告范围 | [验证契约](ops/2026-09-21-validation-contract.md) |
|
||||
| 任务模板与会话收口 | [任务模板](ops/templates/short-term-task.md) · [收口清单](ops/templates/session-close-checklist.md) |
|
||||
| 创建任务、集成、部署、清理 | [worktree 工作规范](ops/2026-09-21-agent-worktree-workflow.md) |
|
||||
| 当前在做什么 | [ops/CURRENT.md](ops/CURRENT.md) |
|
||||
| 模块完成度 | [status/FEATURE-MATRIX.md](status/FEATURE-MATRIX.md) |
|
||||
| 发布 blocker | [remediation/gap-matrix.md](remediation/gap-matrix.md) |
|
||||
| 问题历史、修复经过 | [问题台账](audit/ISSUES.md) · [闭环规范](ops/2026-09-23-issue-learning-workflow.md) |
|
||||
| 开发注意事项与经验检索 | [经验索引](ops/lessons/INDEX.md) |
|
||||
| 审计/问题分析 | [audit/INDEX.md](audit/INDEX.md) |
|
||||
| 整改方案 | [remediation/INDEX.md](remediation/INDEX.md) |
|
||||
| 历史归档 | [archive/README.md](archive/README.md) |
|
||||
@@ -64,13 +57,9 @@
|
||||
|
||||
## 文档生命周期
|
||||
|
||||
按 [AGENTS 任务分级](../AGENTS.md#2-任务分级与授权) 选择最小产物。下图是可选信息流，不要求每任务创建所有文件；小任务/有价值的只读审查可由一个主文档承载范围、结论、验证与交接。主文档先明确 task_id、owner、授权来源、状态和证据；跨阶段信息确需独立时才拆分并回链。
|
||||
|
||||
```text
|
||||
audit（问题）→ remediation（方案）→ ops/short-term（任务）
|
||||
→ test-reports（验收）→ archive（关闭证据）
|
||||
```
|
||||
|
||||
任务状态字段：`planned | in_progress | blocked | done | cancelled`。问题以 issue_state、经验以 lesson_state 独立记录，取值与转换见 [闭环规范](ops/2026-09-23-issue-learning-workflow.md)；研究任务完成不关闭待修问题。
|
||||
|
||||
会话结束不等于任务完成；只有 done/cancelled 任务归档。CURRENT 保留最多 3 项焦点及活跃/阻塞/待集成/待清理事项，完成认领和长证据迁入 [历史快照](archive/ops/2026-09-21-current-history.md)。移动文档同步修复相对链接，保留证据与来源。规范生命周期另用 proposed/approved/active/deprecated；工具能力另用 manual/enforced。
|
||||
状态字段：`planned | in_progress | blocked | done | cancelled`
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
# ADR：最终成果保险库（FAV）
|
||||
|
||||
## 状态
|
||||
|
||||
已接受（2026-09-14，落地计划 V0–V6）
|
||||
|
||||
## 背景
|
||||
|
||||
运行库 PostgreSQL 与 workspace 投影会一起丢失或错挂。需要独立保存**已确认终态**的精确字节，但不能成为第三套完整业务真相源，也不能用目录扫描猜测“最终文件”。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **三层权威**：PostgreSQL 管项目/权限/工作流/版本关系；workspace 是可清理投影；FAV 只对已归档 payload、manifest、来源证据和删除状态权威。
|
||||
2. **无 tenant_id**：安全边界沿用 `environment + project_members + role-admin`。未来组织层另立 ADR。
|
||||
3. **事件准入**：只接受方案准入表中的数据库事实。显式 publish/pin 不能绕过终态 allowlist。禁止扫描 workspace。
|
||||
4. **同事务冻结**：终态事务把精确 payload/SHA 写入 staging 并写 unpublished outbox；publisher 不得重读可变消息行。
|
||||
5. **union-deny 删除**：运行库删除账本或 vault tombstone 任一侧删除即拒绝读取/恢复。
|
||||
6. **恢复**：只进 scratch 库，默认 `recover-as-collection`。禁止 GET 自动写回或覆盖现有 head。
|
||||
7. **互补**：FAV、migration corpus、完整 DB backup/PITR 互相不能替代。不作为 409/split-brain 绕行。
|
||||
|
||||
## 后果
|
||||
|
||||
- 实现从 `feature/final-artifact-vault` 推进；mutex=`artifact-vault`。
|
||||
- Goose 从 **00034** 增加 FAV 表（00033 已被 task-run 治理占用）。
|
||||
- 降级读取默认关闭（`FAV_DEGRADED_READ`），Unit A 纠挂完成前不得对现网开启。
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: "功能启用与文档修改影响分析调研"
|
||||
status: done
|
||||
created: 2026-09-20
|
||||
updated: 2026-09-20
|
||||
owner: Codex
|
||||
branch: feature/capability-enablement-impact-plan
|
||||
worktree: "-"
|
||||
mutex: capability-impact-research
|
||||
---
|
||||
|
||||
# 功能启用与文档修改影响分析调研
|
||||
|
||||
## 目标
|
||||
核实已实现功能的有效启用状态，形成分阶段启用方案及需求追踪、增量影响分析设计。
|
||||
|
||||
## 范围
|
||||
源码、配置、只读运行态、已有证据；研究报告与整改方案落盘。
|
||||
|
||||
## 非目标
|
||||
本轮不修改业务代码、不启用开关、不改变共享容器或真实项目数据。
|
||||
|
||||
## 步骤
|
||||
1. [x] 核实功能状态和接线。
|
||||
2. [x] 调研已有修改报告、依赖与需求追踪模型。
|
||||
3. [x] 编写详细报告和可实施方案，完成文档核查。
|
||||
|
||||
## 验收标准
|
||||
- [x] 当前事实与历史验收分开；每项启用方案有前置条件、验收、回退。
|
||||
- [x] 影响分析有版本、权限、增量更新、一致性和用户交互契约。
|
||||
|
||||
## 证据 / 备注
|
||||
开始时 dev=8fdcd98，工作区干净；git pull --ff-only 返回 Already up to date。无集成槽占用、无 push 授权。
|
||||
|
||||
产物：
|
||||
|
||||
- [调研报告](../../ops/research/2026-09-20-capability-enablement-impact-research.md)
|
||||
- [整改方案](../../remediation/2026-09-20-capability-enablement-impact-plan.md)
|
||||
- [FEATURE-MATRIX 校准](../../status/FEATURE-MATRIX.md)
|
||||
- [方案审阅记录](../../ops/research/2026-09-20-capability-enablement-impact-plan-review.md)
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: "2026-09-20 P0 热修（迁移 / 越权 / 稳定性 / 凭证）"
|
||||
status: done
|
||||
created: 2026-09-20
|
||||
updated: 2026-09-20
|
||||
owner: Cursor-Auto
|
||||
branch: docs/p0-closeout-2026-09-20
|
||||
worktree: "-"
|
||||
mutex: docs
|
||||
---
|
||||
|
||||
# 2026-09-20 P0 热修
|
||||
|
||||
## 目标
|
||||
|
||||
关闭系统体检发现的 P0 critical：迁移断链、三项 IDOR、进程 panic/race、凭证泄漏与生产口令轮换。
|
||||
|
||||
## 范围
|
||||
|
||||
- Wave 0–4（见 [整改方案](../../remediation/2026-09-20-p0-remediation-plan.md)）
|
||||
- 后续实现分支：`fix/capability-merge-00058-2026-09-20`、`fix/authz-idor-hotfixes-2026-09-20`、`fix/runtime-panic-races-2026-09-20`、`fix/credential-hardening-2026-09-20`、`docs/p0-closeout-2026-09-20`
|
||||
|
||||
## 非目标
|
||||
|
||||
- main 分支对齐晋升
|
||||
- FAV / SWBOOT-10 / D7 / MULTI_INTENT full
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] Wave 0：审计与整改文档、CURRENT 认领、long-term 增补
|
||||
2. [x] Wave 1：capability 合入 + 00058 + rebuild
|
||||
3. [x] Wave 2：三项越权
|
||||
4. [x] Wave 2b：panic/race/recover/XSS
|
||||
5. [x] Wave 3：凭证 + 口令轮换
|
||||
6. [x] Wave 4：测试报告与收口
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 见 [测试报告](../../test-reports/2026-09-20-p0-hotfixes-test-report.md)
|
||||
|
||||
## 相关链接
|
||||
|
||||
- Audit: [../../audit/2026-09-20-system-triage-audit.md](../../audit/2026-09-20-system-triage-audit.md)
|
||||
- Remediation: [../../remediation/2026-09-20-p0-remediation-plan.md](../../remediation/2026-09-20-p0-remediation-plan.md)
|
||||
- Test report: [../../test-reports/2026-09-20-p0-hotfixes-test-report.md](../../test-reports/2026-09-20-p0-hotfixes-test-report.md)
|
||||
|
||||
## 证据 / 备注
|
||||
|
||||
（各波次合入 commit 与健康输出）
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: "落实 Agent 规范与 L1 操作门禁"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Codex
|
||||
branch: feature/agent-governance-implementation
|
||||
worktree: .worktrees/agent-governance-implementation
|
||||
base_dev_sha: a241e838150f218f3a09d3523f93291b847d45fd
|
||||
mutex: agent-governance
|
||||
review_state: passed
|
||||
integration_state: integrated
|
||||
deployment: not_required
|
||||
cleanup: pending
|
||||
cleanup_owner: independent-maintainer-after-owner-exit
|
||||
remote_sync: not_requested
|
||||
---
|
||||
|
||||
# 落实 Agent 规范与 L1 操作门禁
|
||||
|
||||
用户已授权“按照方案实现这些规范”。范围：审查 R01–R10、两项安全补充、两个共享文档与 dev 操作的 L1 管理入口。所有修改在本任务 worktree；不改产品业务代码、数据库、模型配置，不升级 test/main，不 push。Python 标准库 sqlite3/fcntl 实现本机协调，不增加产品 Go 依赖。
|
||||
|
||||
## 实施单元与所有权
|
||||
|
||||
- 规范 Agent：AGENTS/PROJECT/客户端薄入口/模板/测试规范/CURRENT 归档，互斥 policy-docs。
|
||||
- 工具 Agent：worktree helper、env-service、candidate-images-build 与对应测试，互斥 ops-scripts。
|
||||
- 根 Agent：agentctl/SQLite/lease/CAS/提交与集成门禁、runbook、报告、FEATURE-MATRIX、ignore，互斥 coordination-core。
|
||||
- 测试 Agent：核心独立行为测试，仅写自己的测试文件，使用临时 Git 仓库。
|
||||
|
||||
## 验收
|
||||
|
||||
- [x] 新规范一致、轻量入口和真实状态可用；历史迁移不丢失。
|
||||
- [x] 主仓唯一 .locks；原子资源集合、父子冲突、活跃/失效身份、幂等及保守恢复。
|
||||
- [x] CURRENT/MATRIX 受控增量/CAS 更新，旧基线不覆盖，记录恢复证据。
|
||||
- [x] 错误工作区/无租约服务写入被拒；候选镜像源码 SHA 不符被拒。
|
||||
- [x] 安全 create/remove、commit/ref 门禁正反例通过。
|
||||
- [x] 独立代码审查及真实临时仓库并发验收；本地 dev 接收验证后的候选；安全清理。
|
||||
|
||||
## 交付边界
|
||||
|
||||
L1 对统一入口与 Git hooks 防误改，不能阻止任意同 UID shell 绕过。OS 沙箱、跨机锁、产品 PI 镜像交付等独立运行架构变更不在本次规范/最小门禁改动内。纯工程代码与文档不触发产品重建；将验证主目录运行挂载和就绪未因本轮改变。
|
||||
|
||||
## 验证与集成结果
|
||||
|
||||
- 76 项 Python 工程测试通过；最终候选复跑同样 76 PASS。20 个真实进程/独立 Git worktree 争同一资源：1 个执行、19 个 LOCK_BUSY。
|
||||
- ce-simplify-code 三视角完成；ce-code-review `20260921-133611-5e4781e6` 的 5 个确认问题全部修复并经独立复核关闭。详见[报告](../../test-reports/2026-09-21-agent-governance-test-report.md)。
|
||||
- 源码实现提交 `fed87ad1`；保留并行 Cursor 材料切块任务后任务 HEAD 为 `578a96440da56717582ec5ab267a094ceea3d941`。dev 从 `a5ea469ca44171a5c3e6419b1757852270fb991d` 接收完整验证候选 `7e9317b849e0696e110bac5b27749861178d7e3d`，这是规则 effective_commit。
|
||||
- 主仓 `.locks` 初始化、旧/新 dev flock 同 inode 和三个 hooks 已启用；doctor 正常，无租约 env guard 返回 LEASE_REQUIRED。收口文档使用已生效入口完成 CAS、提交与后续候选集成。
|
||||
- 真实 dev 合入前后 ready=ok/schema61、容器镜像和主目录 data/dev 挂载一致。本轮 deployment=not_required；未 push、未操作 test/main、无产品数据库或模型配置改动。
|
||||
- cleanup=pending：实际普通 remove 因部分同 UID 进程 cwd 不可读拒绝。保留本任务及 integrate-agent-governance-implementation 两个工作区，不使用 force/-D。独立维护者在 owner 退出并解决/核实进程可见性后重跑全部门禁；仅含可再生 pycache 的文件先明确删除。其他任务现场不在清理范围。
|
||||
- 文档链接检查 356 个目标中，唯一已存在的 `FEATURE-MATRIX` 历史 promotion receipt 断链不由本轮引入；本轮新增/修改链接全部有效。
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: "Agent 规范整体审查"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Codex
|
||||
branch: feature/agent-policy-review
|
||||
worktree: .worktrees/agent-policy-review
|
||||
base_dev_sha: a241e838150f218f3a09d3523f93291b847d45fd
|
||||
write_scope: [.doc/ops/short-term/2026-09-21-agent-policy-review.md, .doc/archive/ops/2026-09-21-agent-policy-review.md, .doc/audit/2026-09-21-agent-policy-review.md, .doc/ops/CURRENT.md]
|
||||
mutex: agent-policy-review
|
||||
deployment: not_required
|
||||
cleanup: retained-with-reason
|
||||
---
|
||||
|
||||
# Agent 规范整体审查
|
||||
|
||||
## 目标与范围
|
||||
|
||||
评估生效规范的可完善之处，形成有依据的新增、删除、修改清单。本轮使用 ce-doc-review 的只读审查流程；不修改 AGENTS/PROJECT/客户端规则，不实现锁管理或改业务代码。
|
||||
|
||||
## 已确定约束
|
||||
|
||||
- 全部新增修改使用 .worktrees；主目录留给 dev 集成与运行。
|
||||
- 锁先统一入口/提交门禁防误改，OS 权限隔离后续实施。
|
||||
- 审查不等于实现或部署授权；已有未合入规范收口和 .locks 方案保留原分支。
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 启动链、当前 Git、规范与模板盘点。
|
||||
2. [x] 一致性、可执行性、范围、安全及故障场景复核。
|
||||
3. [x] 核实保留发现，形成增删改建议与实施优先级。
|
||||
4. [x] 文档校验、归档、本地提交。
|
||||
|
||||
## 验收
|
||||
|
||||
- 每条保留发现有当前源文件或明确缺失证据、实际后果和建议修改。
|
||||
- 区分已生效规则、尚待实现工具和未合入草案；不把建议当现状。
|
||||
- 未修改主目录跟踪文件、运行锁、服务或用户数据。
|
||||
|
||||
## 结果与交接
|
||||
|
||||
- [整体审查](../../audit/2026-09-21-agent-policy-review.md)：10 组增删改建议、2 项安全观察；保留已确定的 worktree 与 L1-first 选择。
|
||||
- 五个独立会话内视角已返回；主审核对引用与实际命令/脚本。文档原规则未改，自动化未实施。
|
||||
- 检查项：新增文档相对链接、git diff --check；未运行产品测试，不作运行验收声明。
|
||||
- 本任务 CURRENT 快照标 done，未占共享集成槽位；本地分支保留供审核，未合入 dev、未 push。
|
||||
- 需要执行修改时先按第一批消除冲突，再处理减负及既有工具实现；不要将本报告直接视为已生效规则。
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
title: "采纳 Agent worktree 工作规范"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Codex
|
||||
branch: feature/agent-workflow-governance-plan
|
||||
worktree: .worktrees/feature-agent-workflow-governance-plan
|
||||
mutex: agent-workflow-governance
|
||||
---
|
||||
|
||||
# 采纳 Agent worktree 工作规范
|
||||
|
||||
## 授权与范围
|
||||
|
||||
用户于 2026-09-21 确认“提交吧，之后按这套执行”。延续原治理任务，在原 dev 派生的独立 worktree 内将方案采纳为生效规则，提交并合入本地 dev。仅修改规范、模板和治理记录。
|
||||
|
||||
本次不将 W1–W4 的自动化开发宣称已完成；它们保留在实施任务中。主目录仍有其他任务未提交改动，使用临时集成 worktree 合入纯文档，不迁移原任务、不改变业务运行态、不 push。
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 核对主目录现场、原方案提交与集成槽位。
|
||||
2. [x] 同步 AGENTS、PROJECT、Cursor 规则、操作规范与模板。
|
||||
3. [x] 文档检查、提交、独立 worktree 合入 dev。
|
||||
4. [x] 更新验收/交接及清理状态。
|
||||
|
||||
## 验收
|
||||
|
||||
- [x] 单 Agent 主目录开发例外已移除，生效规则可从启动链发现。
|
||||
- [x] 创建明确来自 dev；测试提交、共享服务串行、部署及安全清理条件可执行。
|
||||
- [x] 自动化能力保持 planned；主目录其他任务未提交改动不被纳入提交。
|
||||
- [x] 本地 dev 含本次规范提交；未 push，未重建服务。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)
|
||||
|
||||
## 结果
|
||||
|
||||
- 规则提交 `048bbe4a`，验证的合并候选及首次 dev 合入 `83e22a70`。
|
||||
- [文档验收](../../test-reports/2026-09-21-agent-workflow-governance-adoption-test-report.md)。
|
||||
- 主目录旧任务保留；临时 dev 集成工作区保留到原 owner 可安全切回 dev，见 [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)。
|
||||
- 收口提交合入后普通清理本任务和候选工作区，实际结果记录共同 Git 目录的治理操作收据。未 push；deployment=not_required。
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: "Agent 工作规范与 worktree 并行治理方案"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Codex
|
||||
branch: feature/agent-workflow-governance-plan
|
||||
worktree: .worktrees/feature-agent-workflow-governance-plan
|
||||
mutex: agent-workflow-governance-plan
|
||||
---
|
||||
|
||||
# Agent 工作规范与 worktree 并行治理方案
|
||||
|
||||
## 目标
|
||||
|
||||
基于当前仓库规范、脚本和现场，评估主目录保护、强制 worktree、串行集成与清理机制，交付可审核方案。
|
||||
|
||||
## 范围
|
||||
|
||||
- 只读检查 Git、脚本、Compose、测试入口和协作记录。
|
||||
- 形成调研、治理方案及交接文档；仅在本任务 worktree 写文档。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不修改业务代码、Agent 规则或运维脚本；不切换主目录分支、不干预其他任务、不重建服务、不清理既有 worktree、不 push。
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 阅读启动链并盘点现场。
|
||||
2. [x] 显式从本地 dev@15b8a4a8 创建独立 worktree。
|
||||
3. [x] 完成机制核验、方案和边界审查。
|
||||
4. [x] 写交接并核查文档差异。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 有现状证据、方案比较、操作流程、并行边界、恢复与验收标准。
|
||||
- [x] 区分已存在机制与拟实现机制；不将方案宣称为已落地。
|
||||
|
||||
## 证据 / 备注
|
||||
|
||||
初始主目录为 fix/intent-workflow-scoping-2026-09-21，有其他任务未提交变更。为保护现场，未执行 checkout dev / pull；从显式本地 dev 创建 worktree。origin/dev...dev 为 0/309，仅为本地远端跟踪引用快照，本轮未 fetch。认领仅登记本 worktree 的 CURRENT，尚无跨 worktree 实时协调入口；本任务只读代码且使用独立文档路径。
|
||||
|
||||
## 交付
|
||||
|
||||
- [调研](../../ops/research/2026-09-21-agent-workflow-governance-research.md)
|
||||
- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)
|
||||
- [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)
|
||||
- 仅文档核验，未执行产品测试；治理能力在 FEATURE-MATRIX 保持 planned。
|
||||
@@ -1,286 +0,0 @@
|
||||
# CURRENT 历史快照（2026-09-21）
|
||||
|
||||
归档来源：实施基线 `eb4dbdca5baae8dd5f3ddefc0f5510ac2978dcd3` 的 `.doc/ops/CURRENT.md`。以下保留原始认领、环境断言、焦点和证据索引；只调整移动后的 Markdown 相对链接。历史状态不是当前锁、环境或授权依据，活跃协调见 [CURRENT](../../ops/CURRENT.md)。基线内已失效的旧链接另在本次验证记录中说明，不把历史声明改写成新结论。
|
||||
|
||||
---
|
||||
|
||||
# 当前焦点
|
||||
|
||||
**更新**: 2026-09-21
|
||||
**production_ready**: yes（门禁 B1–B4 已签；dev schema **61**，test/main 仍为 **58**。P0 热修 done；rdev 种子热修 done，见 [报告](../../test-reports/2026-09-20-rdev-seed-hotfix-test-report.md)）
|
||||
|
||||
## 焦点
|
||||
|
||||
1. **工作流作用域权重**：`WORKFLOW_SCOPE_MODE` 默认 `strict`；`weighted` 按关系权重打分，只读跨流注明归属，写动作仍拦截。见 [报告](../../test-reports/2026-09-21-workflow-scope-weighting-test-report.md)。test/main 未晋升。
|
||||
2. **意图确认优先与阶段感知**：弱写「整理需求」→ intake 确认卡片。见 [报告](../../test-reports/2026-09-21-intent-confirm-stage-aware-test-report.md)。test/main 未晋升。
|
||||
3. **上传解析提示 / 去重 / CoW 收口**：MinerU 解析状态轮询闭环（pending→running→done）、重复文件「已复用」提示、失败原因+重新解析、CAS 不可变 CoW 契约测试，已合入 `dev`（代码 `99905571`、证据 `74587ccf`、收口 `a0464eb5`）。见 [报告](../../test-reports/2026-09-21-upload-parse-ux-dedup-test-report.md)。test/main 未晋升。前序任务执行状态卡收口见 [报告](../../test-reports/2026-09-21-taskrun-status-card-persistence-test-report.md)（含二轮修复：completed 步骤 label 冻结为"正在…（NN%）"的收口归一化 + dev 历史回填，已合入 `dev@4b303247` 并真实 PI 验收）。
|
||||
4. **MinerU 真实 PDF 二轮验收**：用户反馈「PDF 内容未被理解」由两因叠加——(A) 首轮在 worktree 内跑 `env-service dev rebuild` 令挂载漂到 worktree `data/dev`，真实历史 blob 全部读不到；(B) Agent 轻量 API 硬限 20 页，28 页真实文件失败。首轮结论作废。二轮从**主目录** rebuild 修复挂载，`internal/mineru` 在 `-30003` 时按 20 页窗分块解析并重编全局页锚；`ReadRefBytes` 失败改为 `slog.Warn`。已合入 `dev@362b68a0`。真实 `bd_intake`（项目 6532）`completed`，工作区 `materials_text` 注入 29152 字节中文正文。见 [报告](../../test-reports/2026-09-21-mineru-doc-parsing-test-report.md) 第八节。
|
||||
5. **红线**：禁止整支 merge FAV；不默认升 `MULTI_INTENT_PLAN_TIER=full`；`SEMANTIC_SUMMARY_REPLACE` 不随 W2 开启；FAV live 观察窗证据驱动；`FAV_DEGRADED_READ=false`；项目 143 只读；SWBOOT-10 保持 fail-closed stub；D7 对话 ADR 仍待合规签字（追踪表留存类别已定为 `record`，不授权物理删除）；**不改 `production_ready`**；模块解耦批次 A–G 与回溯实施切片未单独认领前保持 `planned`；**合入 dev 后必须回主目录跑 `env-service.sh dev rebuild`，禁止任何 worktree 内运行 `env-service`**（脚本 ROOT_DIR 取自脚本所在目录树，会带走 bind mount，导致 `/app/data` 漂到 worktree 空目录）。
|
||||
|
||||
## 并行认领
|
||||
|
||||
| owner | task | branch | worktree | mutex | status |
|
||||
|-------|------|--------|----------|-------|--------|
|
||||
| Codex | 2026-09-21-agent-governance-implementation | feature/agent-governance-implementation | .worktrees/agent-governance-implementation | agent-governance | in_progress |
|
||||
| Cursor | 2026-09-21-workflow-scope-weighting | feature/workflow-scope-weighting-2026-09-21 | .worktrees/workflow-scope-weighting-2026-09-21 | intent+web+docgov | done |
|
||||
| Cursor | 2026-09-21-upload-parse-ux-dedup | feature/upload-parse-ux-2026-09-21 | .worktrees/upload-parse-ux-2026-09-21 | server+web+storage | done |
|
||||
| Cursor | 2026-09-21-mineru-doc-parsing | feature/mineru-doc-parsing-2026-09-21 | .worktrees/mineru-doc-parsing-2026-09-21 | storage+bizdev+kb | done |
|
||||
| Cursor | 2026-09-21-intent-confirm-stage-aware | fix/intent-confirm-stage-aware-2026-09-21 | .worktrees/intent-confirm-stage-aware-2026-09-21 | intent+web+docgov | done |
|
||||
| Cursor | 2026-09-21-taskrun-status-card | feature/taskrun-status-card-2026-09-21 | .worktrees/feature-taskrun-status-card-2026-09-21 | chat+web+taskrun | done |
|
||||
| Cursor | 2026-09-21-intent-workflow-scoping | fix/intent-workflow-scoping-2026-09-21 | - | intent+web+docgov | done |
|
||||
| Codex | 2026-09-21-agent-workflow-governance-adoption | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance | in_progress |
|
||||
| Codex | 2026-09-21-agent-workflow-governance-plan | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance-plan | done |
|
||||
| Cursor | 2026-09-21-workflow-doc-key-unification | fix/workflow-doc-key-unification-2026-09-21 | .worktrees/fix-workflow-doc-key-unification-2026-09-21 | docgov+web | done |
|
||||
| Cursor | 2026-09-21-dev-deep-test-four-issues | fix/dev-deep-test-four-issues-2026-09-21 | - | web+intent+taskrun | done |
|
||||
| Cursor | 2026-09-21-trace-panel-to-chat | feature/trace-panel-to-chat-2026-09-21 | - | trace-impact+web | done |
|
||||
| Cursor | 2026-09-21-taskrun-scope-persist | fix/taskrun-scope-persist-2026-09-21 | - | projectinstance+taskrun | done |
|
||||
| Cursor | 2026-09-21-dev-multiuser-four-issues | fix/dev-multiuser-four-issues-2026-09-21 | .worktrees/fix-dev-multiuser-four-issues | projectinstance+docgov | done |
|
||||
| Cursor | 2026-09-21-taskrun-error-transparency | fix/taskrun-error-transparency-2026-09-21 | - | chat+web | done |
|
||||
| Cursor | 2026-09-21-trace-panel-null-crash | fix/trace-panel-null-crash-2026-09-21 | - | trace-index+web | done |
|
||||
| Cursor-Auto | 2026-09-20-stage-backtrack-design | feature/stage-backtrack-design | - | trace-impact-design | done |
|
||||
| Cursor-Auto | 2026-09-20-impact-loop-t1 至 T3/B1–B3 | feature/stage-backtrack-impl | - | trace-index | done |
|
||||
| Cursor | 2026-09-20-rdev-seed-hotfix | fix/workflow-seed-bootstrap-2026-09-20 | - | workflow-def | done |
|
||||
| Cursor-Auto | 2026-09-20-module-decoupling-spec-audit | docs/module-decoupling-spec-2026-09-20 | - | module-decoupling-spec | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-closeout | docs/p0-closeout-2026-09-20 | - | docs | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-hotfixes（Wave 0 文档） | docs/p0-triage-2026-09-20 | - | docs | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-capability-00058 | fix/capability-merge-00058-2026-09-20 | - | infra+chat | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-idor | fix/authz-idor-hotfixes-2026-09-20 | - | authz | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-runtime-stability | fix/runtime-panic-races-2026-09-20 | - | taskrun+chat+web | done |
|
||||
| Cursor-Auto | 2026-09-20-p0-credentials | fix/credential-hardening-2026-09-20 | - | ops+infra | done |
|
||||
| Cursor-Auto | 2026-09-20-proposed-authoritative-reports | feature/capability-enablement-impact-plan | - | docgov | done |
|
||||
| Cursor-Auto | 2026-09-20-pi-narrative-clipped-diff | feature/capability-enablement-impact-plan | - | docgov | done |
|
||||
| Cursor-Auto | 2026-09-20-pi-reasoning-profile | feature/capability-enablement-impact-plan | - | pi-agent | done |
|
||||
| Cursor-Auto | 2026-09-20-semantic-summary-persistence | feature/capability-enablement-impact-plan | - | chat+lineage-version | done |
|
||||
| Cursor-Auto | 2026-09-20-feature-readiness-and-lineage-authz | feature/capability-enablement-impact-plan | - | sysadmin+lineage | done |
|
||||
| Codex | 2026-09-20-capability-enablement-impact-plan | feature/capability-enablement-impact-plan | - | capability-impact-research | done |
|
||||
| Cursor-Auto | 2026-09-20-post-activation-duty-reassign-member-chat | fix/post-activation-duty-reassign-member-chat | - | projectworkflow+authz+web | done |
|
||||
| Cursor-Auto | 2026-09-20-test-env-triage-fixes | fix/test-env-triage-2026-09-20 | - | projectworkflow+chat+assets | done |
|
||||
| Cursor-Auto | 2026-09-20-test-env-beta6-verification | docs/test-env-beta6-verification | - | infra+docs | done |
|
||||
| Cursor-Auto | 2026-09-20-bug-hunt-permissions-uploads | fix/bug-hunt-2026-09-20-permissions-and-uploads | - | authz+web+projectworkflow | done |
|
||||
| Cursor | audit-b1-data-consistency | fix/audit-b1-data-consistency | - | docgov+workflow+chat | done |
|
||||
| Cursor | audit-b2-authz-hardening | fix/audit-b2-authz-hardening | - | authz | done |
|
||||
| Cursor | audit-b3-sse-events | fix/audit-b3-sse-events | - | chat+events | done |
|
||||
| Cursor | audit-b4-frontend | fix/audit-b4-frontend | - | web | done |
|
||||
| Cursor-Auto | 2026-09-19-audit-remainder-closeout | fix/audit-remainder-closeout | - | audit-remainder | done |
|
||||
| Antigravity | 2026-09-20-dev-deep-test-and-promotion | feature/dev-deep-test-and-promotion | - | integration | done |
|
||||
| Cursor-Auto | 2026-09-19-remove-control-center | fix/remove-control-center | - | controlcenter | done |
|
||||
| Cursor-Auto | 2026-09-17-control-center-server | feature/control-center-server | - | controlcenter | cancelled |
|
||||
| Kimi | 2026-09-18-user-manual | feature/user-manual | .worktrees/feature-user-manual | docs | done |
|
||||
| Cursor-Auto | 2026-09-18-wave7-roadmap-orchestration | docs/wave7-roadmap-orchestration | - | roadmap-orchestration | done |
|
||||
| Cursor-Auto | 2026-09-18-wave6-doc-drift | docs/wave6-doc-drift | - | doc-drift | done |
|
||||
| Cursor-Auto | 2026-09-18-wave5-deadcode-decisions | fix/wave5-deadcode-decisions | - | deadcode-cleanup | done |
|
||||
| Cursor-Auto | 2026-09-18-wave4-hardening-r1-r8 | fix/wave4-hardening-r1-r8 | - | hardening | done |
|
||||
| Cursor-Auto | 2026-09-18-wave3-test-debt-blindspots | fix/wave3-test-debt-blindspots | - | test-debt | done |
|
||||
| Cursor-Auto | 2026-09-18-wave2-config-flag-align | fix/wave2-config-flag-align | - | infra | done |
|
||||
| Cursor | 2026-09-18-wave1-main-env-fix | fix/wave1-main-env-fix | - | infra | done |
|
||||
| Cursor | 2026-09-18-wave0-p0-bug-fixes | fix/wave0-p0-sse-chat-cache-bugs | - | chat + web | done |
|
||||
| Kimi | 2026-09-17-system-health-check（只读审计，未实施） | - | - | audit | done |
|
||||
| Cursor | 2026-09-17-docgov-modification-proposal-http | feature/docgov-modification-proposal-http | - | docgov | done |
|
||||
| Cursor | 2026-09-17-document-author-only-closeout | feature/document-author-only-plan | - | document-duty-policy | done |
|
||||
| Cursor | 2026-09-17-rdev-template-depth-s1-continued | feature/rdev-template-depth-s1-continued | .worktrees/feature-rdev-template-depth-s1-continued | rdev-templates | done |
|
||||
| Cursor | 2026-09-17-rdev-workflow-integration | feature/rdev-core | - | workflow-def | done |
|
||||
| Cursor | 2026-09-17-rdev-template-depth | feature/rdev-template-depth | .worktrees/feature-rdev-template-depth | rdev-templates | done |
|
||||
| Codex | 2026-09-17-document-author-only-plan | feature/document-author-only-plan | - | document-duty-policy-plan | done |
|
||||
| Cursor | 2026-09-17-initial-load-perf-u2 | feature/initial-load-perf-u2 | - | web + static-delivery | done |
|
||||
| Codex | 2026-09-17-initial-load-performance-plan | feature/initial-load-performance-plan | .worktrees/feature-initial-load-performance-plan | loading-performance-audit | done |
|
||||
| Kimi | 2026-09-17-system-admin-console | feature/system-admin-console | - | web + sysadmin | done |
|
||||
| Cursor-Auto | 2026-09-17-engineering-dashboard | feature/engineering-dashboard | .worktrees/feature-engineering-dashboard | engineering-dashboard | done |
|
||||
| Cursor | 2026-09-17-promote-null-fk-to-test | feature/promote-null-fk-to-test | - | infra | done |
|
||||
| Cursor | 2026-09-17-docgov-optional-duty-null-fk | fix/docgov-optional-duty-null-fk | - | docgov | done |
|
||||
| Cursor | 2026-09-17-leftover-hygiene | chore/leftover-hygiene-2026-09-17 | - | ops | done |
|
||||
| Cursor | 2026-09-17-w2-semantic-summary-shadow | feature/w2-semantic-summary-shadow-live | - | chat | done |
|
||||
| Cursor | 2026-09-17-w3-pi-change-report-narrative | feature/w3-pi-change-report-narrative-live | - | docgov | done |
|
||||
| Cursor | 2026-09-17-w4-multi-intent-u9-u12 | feature/w4-u9-segment-live | - | intent-plan | done |
|
||||
| Cursor | 2026-09-17-w5a-software-bootstrap-ui | feature/w5a-software-bootstrap-ui-pi | - | workflow-design | done |
|
||||
| Cursor | 2026-09-17-w6-fav-subscriber-shadow | feature/w6-fav-subscriber-shadow | - | events | done |
|
||||
| Cursor | 2026-09-17-w7-d7-inventory | feature/w7-d7-data-inventory | - | chat | done |
|
||||
| Cursor | 2026-09-17-promote-dev-to-test | feature/promote-dev-to-test-2026-09-17 | - | infra | done |
|
||||
| Cursor | 2026-09-17-kb-host-auth-fix | fix/kb-host-auth-layered-load | - | infra | done |
|
||||
| Cursor | 2026-09-17-w1-ci-e2e-green-nightly | feature/w1-ci-e2e-green-nightly | - | ci | done |
|
||||
| Cline | 2026-09-16-partial-deferred-completion | docs/partial-deferred-completion-plan | - | architecture-docs | in_progress |
|
||||
| Cursor | 2026-09-16-intent-plan-playwright-dual-tab | feature/intent-plan-cards-playwright | .worktrees/feature-intent-plan-cards-playwright | web | done |
|
||||
| Cursor | 2026-09-16-full-backlog-override | docs/override-nogo-full-backlog | - | architecture-docs | done |
|
||||
| Cursor | 2026-09-16-gitea-nightly-docker-datadir | fix/gitea-nightly-docker-datadir | - | ci | done |
|
||||
| Cursor | 2026-09-16-gitea-nightly-host-tools | fix/gitea-nightly-host-tools | - | ci | done |
|
||||
| Cursor | 2026-09-21-test-env-lazy-doc-verification | docs/lazy-doc-verification-2026-09-21 | - | infra+docs | done |
|
||||
| Cursor | 2026-09-16-wave-leftovers | fix/wave-leftovers-n7-playwright-dod | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave3-pu6-pu8-go-no-go | feature/wave3-pu6-pu8-go-no-go | - | architecture-docs | done |
|
||||
| Cursor | 2026-09-16-wave2c-same-image-digest | feature/wave2c-same-image-digest | - | infra | done |
|
||||
| Cursor | 2026-09-16-wave2b-nightly-promotion-receipt | feature/wave2b-nightly-promotion-receipt | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave2-real-pi-evidence | feature/wave2-real-pi-evidence | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-wave1-race-tempdir-cleanup | fix/race-tempdir-cleanup | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave1-iam-fail-closed | fix/iam-store-fail-closed | - | authz | done |
|
||||
| Cursor | 2026-09-16-feature-matrix-wave0-calibration | feature/feature-matrix-production-readiness-plan | .worktrees/feature-matrix-production-readiness-plan | architecture-docs | done |
|
||||
| Codex | 2026-09-16-feature-matrix-production-readiness-plan | feature/feature-matrix-production-readiness-plan | .worktrees/feature-matrix-production-readiness-plan | architecture-docs | done |
|
||||
| Cursor-Auto | 2026-09-16-matrix-deep-test-promote-test | feature/matrix-deep-test-promote-test | - | infra | done |
|
||||
| Cursor-Auto | 2026-09-16-production-ready-gates | docs/production-ready-flip | - | ci | done |
|
||||
| Cursor-Auto | 2026-09-16-demo-seed-pollution | fix/demo-data-pollution-web | - | web | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u8-task-generate | feature/multi-intent-u8-task-generate | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u7-auto-read | feature/multi-intent-u7-auto-read | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u6-web-cards | feature/multi-intent-u6-web-cards | - | web | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u5-decision-api | feature/multi-intent-u5-decision-api | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u4-outbox-projection | feature/multi-intent-u4-outbox-projection | - | events | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u3-intentflow-pg | feature/multi-intent-u3-intentflow-pg | - | intent-plan | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u2-segmenter | feature/multi-intent-u2-segmenter | - | intent | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u1-contracts | feature/multi-intent-u1-contracts | - | architecture-docs | done |
|
||||
| Cursor | app-composition-u11-u12 | feature/app-composition-u11-u12 | - | app | done |
|
||||
| Cursor | chatlog-contextasm-u10 | feature/chatlog-contextasm-u10 | - | chat | done |
|
||||
| Cursor | chat-history-refresh-remediation | fix/chat-history-refresh | - | chat | done |
|
||||
| Cursor | dataset-lifecycle-u9 | feature/dataset-lifecycle-u9 | - | dataset | done |
|
||||
| Cursor | taskrun-runmanifest-u8 | feature/taskrun-runmanifest | - | taskrun | done |
|
||||
| Cursor | document-reliability-m1-live-and-m2 | refactor/document-reliability-pilot | - | workspace | done |
|
||||
| Codex | module-decoupling-remediation-plan | feature/module-decoupling-remediation | - | architecture-docs | done |
|
||||
| Codex | module-decoupling-phase2-plan-review | docs/module-decoupling-ipc-assessment | - | architecture-docs | done |
|
||||
| Cursor | module-decoupling-phase2-docs | feature/module-decoupling-phase2-docs | - | architecture-docs | done |
|
||||
| verifier_antigravity | controlled-content-ui-acceptance | fix/controlled-content-ui-acceptance | - | document-content-ui-acceptance | done |
|
||||
| implementer_cursor | controlled-content-canonical-hash | fix/controlled-content-canonical-hash | - | docgov | done |
|
||||
| Codex | project143-controlled-content-404-diagnosis | fix/project143-controlled-content-404-diagnosis | - | docgov-content-diagnosis | done |
|
||||
| Codex | software-project-bootstrap-plan | feature/software-project-bootstrap-plan | - | workflow-design | done |
|
||||
| Codex | conversation-intent-runtime-state | fix/conversation-intent-state | - | intent | done |
|
||||
| Cursor | conversation-intent-runtime-state | docs/conversation-intent-dual-tab | - | intent | done |
|
||||
| Cursor | document-revision-wave1-6-implementation | feature/document-revision-management | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-runtime-ui03 | fix/document-revision-runtime-ui03 | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-sse-idempotency | fix/document-revision-sse-idempotency | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-active-doc-routing | fix/document-revision-active-doc-routing | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-quality-context | fix/document-revision-quality-context | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-e2e-pending-flow | fix/document-revision-e2e-pending-flow | - | pending-report-ui | done |
|
||||
| Cursor-Auto | document-revision-e2e-reject-routing | fix/document-revision-e2e-reject-routing | - | document-revision-runtime-ui | done |
|
||||
| Cursor-Auto | document-revision-e2e-block-selector | fix/document-revision-e2e-block-selector | - | document-revision-block-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-save-selector | fix/document-revision-e2e-save-selector | - | document-revision-save-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-overlay-selector | fix/document-revision-e2e-overlay-selector | - | document-revision-overlay-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-overlay-transition | fix/document-revision-e2e-overlay-transition | - | document-revision-overlay-transition | done |
|
||||
| Cursor-Auto | document-revision-second-doc-routing-lease | fix/document-revision-second-doc-routing-lease | - | document-revision-second-doc-routing-lease | done |
|
||||
| Cursor-Auto | document-revision-prelim-output | fix/document-revision-pi-runner-module | - | document-revision-prelim-output | done |
|
||||
| Cursor-Auto | document-revision-editor-hydration-race | fix/document-revision-editor-hydration-race | - | document-revision-editor-hydration-race | done |
|
||||
| Cursor-Auto | document-revision-quality-repair-workspace-contract | fix/document-revision-quality-repair-workspace-contract | - | document-revision-quality-repair-workspace-contract | done |
|
||||
| Cursor-Auto | document-revision-fast-completion-observation | fix/document-revision-fast-completion-observation | - | document-revision-fast-completion-observation | done |
|
||||
| Cursor-Auto | document-revision-workflow-category-navigation | fix/document-revision-workflow-category-navigation | - | document-revision-workflow-category-navigation | done |
|
||||
| Cursor-Auto | document-revision-duty-cell-assertion | fix/document-revision-duty-cell-assertion | - | document-revision-duty-cell-assertion | done |
|
||||
| Cursor-Auto | document-revision-reviewer-duty-sync | fix/document-revision-reviewer-duty-sync | - | document-revision-reviewer-duty-sync | done |
|
||||
| Cursor-Auto | document-revision-post-restart-selector | fix/document-revision-post-restart-selector | - | document-revision-post-restart-selector | done |
|
||||
| Cursor-Auto | document-revision-post-restart-final-snippet | fix/document-revision-post-restart-final-snippet | - | document-revision-post-restart-final-snippet | done |
|
||||
| Cursor-Auto | document-revision-pg-id-remap | fix/document-revision-pg-id-remap | - | document-revision | done |
|
||||
| Cursor-Auto | document-revision-runtime | fix/document-revision-runtime-ui03 | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-runtime-ui-final-report | feature/document-revision-runtime-ui-final-report | - | document-revision-runtime-ui | done |
|
||||
| Cursor-Auto | document-revision-evidence-count | fix/document-revision-evidence-count | - | document-revision-evidence-count | done |
|
||||
| Cursor-Auto | document-revision-session-close | feature/document-revision-session-close | - | document-revision-session-close | done |
|
||||
| Cursor-Auto | vite-frp-allowed-hosts | fix/vite-frp-allowed-hosts | - | web-devserver | done |
|
||||
| implementer_cursor | workflow-plan-409-frozen-and-optional-duties | fix/workflow-plan-409-frozen-and-optional-duties | - | workflow | done |
|
||||
| implementer_cursor | governance-action-level-authz | fix/governance-action-level-authz | - | workflow | done |
|
||||
| Cursor | leftover-branch-cleanup | chore/leftover-branch-cleanup | - | ops | done |
|
||||
| Cursor | event-e0a-production-scope-contract | fix/event-production-scope-contract | - | events | done |
|
||||
| Cursor | event-e0b-dispatcher-pg | feature/events-dispatcher-pg | - | events | done |
|
||||
| Cursor | event-e1a-notify-cutover | fix/event-notify-cutover | - | events | done |
|
||||
| Cursor | event-e1b-workflow-advance | fix/event-workflow-advance | - | events | done |
|
||||
| Cursor | event-e1c-projection-cutover | fix/event-projection-cutover | - | events | done |
|
||||
| Cursor | event-e2-hook-guard | fix/event-e2-hook-guard | - | events | done |
|
||||
| Cursor | doccontent-canonical-boundary | fix/doccontent-canonical-boundary | - | docgov | done |
|
||||
| Cursor | intent-bizdev-boundary | fix/intent-bizdev-boundary | - | intent | done |
|
||||
| Cursor | stageflow-type-ownership | fix/stageflow-type-ownership | - | stageflow | done |
|
||||
| Cursor | bizdev-locator-removal | fix/bizdev-locator-removal | - | bizdev | done |
|
||||
| Cursor | chatflow-orchestration-boundary | fix/chatflow-orchestration-boundary | - | chat | done |
|
||||
| Cursor | phase2-closeout-inventories | feature/phase2-closeout-inventories | - | architecture-docs | done |
|
||||
| Cursor | event-shared-live-cutover | feature/event-shared-live-cutover | - | events | done |
|
||||
| Cursor | pi-typed-result | feature/pi-typed-result | - | pi-agent | done |
|
||||
| Cursor | promote-dev-to-test-2026-09-15 | feature/promote-dev-to-test-2026-09-15 | - | infra | done |
|
||||
|
||||
> 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。
|
||||
|
||||
> workflow-plan 409 与治理鉴权 G1–G5 已收口（见 [test-report](../../test-reports/2026-09-14-governance-action-level-authz-test-report.md)）。禁止终止或改写项目 143。
|
||||
> `document-reliability-pilot` U11–U12 已合入 `dev@bf59cce` 并 rebuild。`CHAT-INTENT-STATE` 双标签 busy 已 PASS（项目 6275）。禁止 worktree 内 `env-service`。项目 143 只读，禁止终止。
|
||||
> 2026-09-17 leftover 二次收口：[报告](../../test-reports/2026-09-17-leftover-hygiene-test-report.md)。已合入 leftover worktree/旁支再拆一轮；`feature/software-project-bootstrap` L1 已在 `dev`（残留关闭 commit 已丢弃）。`fix/clean-test-env-baseline` **不 merge**（前端 demo 清理已放弃；仅保留已挑拣的 `SEED_DEMO_USERS=false`）。extra worktree 仅余 `.worktrees/fix-dev-runtime-data-root-guard`（目录名是 guard，检出的是 `feature/final-artifact-vault`）。**故意不合入、不删**：`feature/final-artifact-vault`、`feature/remove-herdr-agent-settings`、`fix/project143-controlled-content-404-diagnosis`、`fix/dev-runtime-data-root-guard`、`dev-old-linear`。不删 `origin/*`。不整支 merge FAV；不启用 `FAV_DEGRADED_READ`。
|
||||
|
||||
## 集成槽位
|
||||
|
||||
| holder | phase | since | scope | queue |
|
||||
|--------|-------|-------|-------|-------|
|
||||
| - | idle | 2026-09-21 | taskrun-status-card label 修复已合入 dev@4b303247 并真实 PI 验收（round2 docs 随后合入）；mineru 二轮文档已合入；schema=61 | - |
|
||||
|
||||
**phase**: `idle` | `merging` | `smoke` | `e2e`
|
||||
|
||||
> 合入 `dev` + 共享容器验证必须串行。详见 [AGENTS.md](../../../AGENTS.md) §6.3。
|
||||
|
||||
## 环境快照
|
||||
|
||||
| 环境 | 端口 | schema | 状态 |
|
||||
|------|------|--------|------|
|
||||
| dev | 8080 | **61** | healthy（mineru `00061`；intent-confirm 真实 PI PASS；`/health` schema_version=61；`pi-agent`；events `:8088`） |
|
||||
| test | 8081 | **58** | healthy（`rc-v1.0.0-beta.7`；rdev v1 active；`published_by` 回落到用户 4；events `:8089`） |
|
||||
| main | 8000 | **58** | healthy（P0 Wave3 rebuild 已追平 schema；分支树对齐仍记 backlog；口令已轮换；events `:8090`） |
|
||||
|
||||
## SSOT
|
||||
|
||||
| 类型 | 路径 |
|
||||
|------|------|
|
||||
| 2026-09-21 Agent worktree 工作规范 | [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) · [调研](../../ops/research/2026-09-21-agent-workflow-governance-research.md) · [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)；规范已采纳，自动化另列 planned |
|
||||
| 2026-09-20 rdev 种子 | [short-term](../../ops/short-term/2026-09-20-rdev-seed-hotfix.md) · [报告](../../test-reports/2026-09-20-rdev-seed-hotfix-test-report.md) |
|
||||
| 2026-09-20 模块解耦 | [审计](../../audit/2026-09-20-module-coupling-audit.md) · [规范](../../system-design/2026-09-20-module-development-standards.md) · [批次 A–G](../../remediation/2026-09-20-module-decoupling-batch-plan.md) · [short-term](../../ops/short-term/2026-09-20-module-decoupling-spec-audit.md) |
|
||||
| 文档总地图 | [../README.md](../../README.md) |
|
||||
| 模块完成度 | [FEATURE-MATRIX](../../status/FEATURE-MATRIX.md)（Wave 0 已校准契约与冻结边界） |
|
||||
| 发布缺口 | [gap-matrix](../../remediation/gap-matrix.md)（`production_ready=yes`；Wave 0 IAM 只读未发现旁路） |
|
||||
| 2026-09-20 系统体检 | [audit](../../audit/2026-09-20-system-triage-audit.md) · [P0 整改](../../remediation/2026-09-20-p0-remediation-plan.md) · [short-term](../../ops/short-term/2026-09-20-p0-hotfixes.md) |
|
||||
| 连续性审计/计划 | [audit](../../audit/2026-09-16-feature-matrix-production-readiness-audit.md) · [remediation](../../remediation/2026-09-16-feature-matrix-production-readiness-plan.md) · [Wave 0 任务](../../ops/short-term/2026-09-16-feature-matrix-wave0-calibration.md) |
|
||||
| 测试报告 | [test-reports/](../../test-reports) |
|
||||
| dev→test 晋升前复核 | [research](../../ops/research/2026-09-19-pre-test-promotion-review.md)（2026-09-19 只读；静态门禁过，容器未 rebuild，暂不合并） |
|
||||
| D7 盘点（W7） | [audit](../../audit/2026-09-17-d7-data-inventory.md) · [报告](../../test-reports/2026-09-17-w7-d7-inventory-test-report.md) · ADR 仍 `pending-compliance-signoff` |
|
||||
| 功能启用与文档影响分析 | [调研](../../ops/research/2026-09-20-capability-enablement-impact-research.md) · [整改方案](../../remediation/2026-09-20-capability-enablement-impact-plan.md) · [方案审阅](../../ops/research/2026-09-20-capability-enablement-impact-plan-review.md)（2026-09-20；未启用开关、未改业务代码） |
|
||||
| 阶段回溯与影响闭环 | [设计](../../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md) · [short-term](../../ops/short-term/2026-09-20-stage-backtrack-design.md)（2026-09-20；仅设计。切片 T1/T2/B1/B2/B3/T3 均为 planned） |
|
||||
| Wave 7 编排确认 | [决策记录](../../ops/short-term/2026-09-18-wave7-roadmap-orchestration.md) |
|
||||
| Agent 手册 | [AGENTS.md](../../../AGENTS.md) |
|
||||
| 意图双标签 busy 交接 | [./handoffs/2026-09-15-conversation-intent-dual-tab.md](../../ops/handoffs/2026-09-15-conversation-intent-dual-tab.md) |
|
||||
| 受控正文 hash 漂移 W1–W6 | [../ops/handoffs/2026-09-14-controlled-content-canonical-hash.md](../../ops/handoffs/2026-09-14-controlled-content-canonical-hash.md) |
|
||||
| DOCREV ADR | [../adr/2026-09-13-document-version-boundary.md](../../adr/2026-09-13-document-version-boundary.md) |
|
||||
| DOCREV 管理测试 | [../test-reports/2026-09-13-document-revision-management-test-report.md](../../test-reports/2026-09-13-document-revision-management-test-report.md) |
|
||||
| DOCREV 运行时 UI Round20 | [../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md](../../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) |
|
||||
| 纯软件项目自举设计 | [../system-design/2026-09-14-software-project-bootstrap-workflow.md](../../system-design/2026-09-14-software-project-bootstrap-workflow.md) |
|
||||
| 模块化单体解耦架构 | [../system-design/2026-09-14-module-decoupling-architecture.md](../../system-design/2026-09-14-module-decoupling-architecture.md) |
|
||||
| 模块解耦整改计划 | [../remediation/2026-09-14-module-decoupling-refactor-plan.md](../../remediation/2026-09-14-module-decoupling-refactor-plan.md) |
|
||||
| Phase 2 方案审阅 | [../audit/2026-09-15-module-decoupling-phase2-plan-review.md](../../audit/2026-09-15-module-decoupling-phase2-plan-review.md) |
|
||||
| Phase 2 修订计划 | [../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md](../../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md) |
|
||||
| 多意图 HITL 复核方案 | [../system-design/2026-09-15-multi-intent-hitl-plan.md](../../system-design/2026-09-15-multi-intent-hitl-plan.md) |
|
||||
| 多意图 HITL U1 契约 | [../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md](../../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md) |
|
||||
| 多意图 HITL U2 分段 | [../test-reports/2026-09-15-multi-intent-u2-segmenter-test-report.md](../../test-reports/2026-09-15-multi-intent-u2-segmenter-test-report.md) |
|
||||
| 多意图 HITL U3 PG | [../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md](../../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) |
|
||||
| 多意图 HITL U4 投影 | [../test-reports/2026-09-16-multi-intent-u4-outbox-projection-test-report.md](../../test-reports/2026-09-16-multi-intent-u4-outbox-projection-test-report.md) |
|
||||
| 多意图 HITL U5 API | [../test-reports/2026-09-16-multi-intent-u5-decision-api-test-report.md](../../test-reports/2026-09-16-multi-intent-u5-decision-api-test-report.md) |
|
||||
| 多意图 HITL U6 Web | [../test-reports/2026-09-16-multi-intent-u6-web-cards-test-report.md](../../test-reports/2026-09-16-multi-intent-u6-web-cards-test-report.md) |
|
||||
| 多意图 HITL U8 generate | [../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md](../../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md) |
|
||||
| 多意图 HITL U7 只读 | [../test-reports/2026-09-16-multi-intent-u7-auto-read-test-report.md](../../test-reports/2026-09-16-multi-intent-u7-auto-read-test-report.md) |
|
||||
| 文档可靠性 M1 报告 | [../test-reports/2026-09-14-document-reliability-pilot-test-report.md](../../test-reports/2026-09-14-document-reliability-pilot-test-report.md) |
|
||||
| 文档可靠性 M1 活验 | [../test-reports/2026-09-14-document-reliability-pilot-live-test-report.md](../../test-reports/2026-09-14-document-reliability-pilot-live-test-report.md) |
|
||||
| 文档可靠性 M2 | [../test-reports/2026-09-14-document-reliability-m2-test-report.md](../../test-reports/2026-09-14-document-reliability-m2-test-report.md) |
|
||||
| 文档可靠性 M3 U8 | [../test-reports/2026-09-15-taskrun-runmanifest-u8-test-report.md](../../test-reports/2026-09-15-taskrun-runmanifest-u8-test-report.md) |
|
||||
| 文档可靠性 M3 U9 | [../test-reports/2026-09-15-dataset-lifecycle-u9-test-report.md](../../test-reports/2026-09-15-dataset-lifecycle-u9-test-report.md) |
|
||||
| 文档可靠性 M4 U10 | [../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md](../../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md) |
|
||||
| 文档可靠性 M5/M6 U11–U12 | [../test-reports/2026-09-15-app-composition-u11-u12-test-report.md](../../test-reports/2026-09-15-app-composition-u11-u12-test-report.md) |
|
||||
| Track E E2 闭包守卫 | [../test-reports/2026-09-15-event-e2-hook-guard-test-report.md](../../test-reports/2026-09-15-event-e2-hook-guard-test-report.md) |
|
||||
| Track E 复盘 | [./research/2026-09-15-track-e-retrospective.md](../../ops/research/2026-09-15-track-e-retrospective.md) |
|
||||
| 旁支清点收口 | [../test-reports/2026-09-15-leftover-branch-cleanup-test-report.md](../../test-reports/2026-09-15-leftover-branch-cleanup-test-report.md) · [二次收口](../../test-reports/2026-09-17-leftover-hygiene-test-report.md) |
|
||||
| SSE/幂等审计 | [../audit/2026-09-13-document-revision-sse-idempotency.md](../../audit/2026-09-13-document-revision-sse-idempotency.md) |
|
||||
| 质量门禁自污染审计 | [../audit/2026-09-13-document-revision-quality-gate-self-pollution.md](../../audit/2026-09-13-document-revision-quality-gate-self-pollution.md) |
|
||||
| 当前文档路由审计 | [../audit/2026-09-13-document-revision-active-doc-routing.md](../../audit/2026-09-13-document-revision-active-doc-routing.md) |
|
||||
| 行动表状态假阳性审计 | [../audit/2026-09-13-document-revision-quality-status-false-positive.md](../../audit/2026-09-13-document-revision-quality-status-false-positive.md) |
|
||||
| 待确认报告选择失败审计 | [../audit/2026-09-13-document-revision-pending-report-selection.md](../../audit/2026-09-13-document-revision-pending-report-selection.md) |
|
||||
| UI-05b 拒绝路由失败审计 | [../audit/2026-09-13-document-revision-e2e-reject-routing.md](../../audit/2026-09-13-document-revision-e2e-reject-routing.md) |
|
||||
| 职责伪造与 ETag 覆盖审计 | [../audit/2026-09-13-document-revision-duty-etag-overwrite.md](../../audit/2026-09-13-document-revision-duty-etag-overwrite.md) |
|
||||
| UI-06 块选择器失败审计 | [../audit/2026-09-13-document-revision-block-selector.md](../../audit/2026-09-13-document-revision-block-selector.md) |
|
||||
| UI-06 保存选择器失败审计 | [../audit/2026-09-13-document-revision-save-selector.md](../../audit/2026-09-13-document-revision-save-selector.md) |
|
||||
| UI-07 纯净阅读取样失败审计 | [../audit/2026-09-13-document-revision-overlay-selector.md](../../audit/2026-09-13-document-revision-overlay-selector.md) |
|
||||
| UI-07 transition 中间帧取样审计 | [../audit/2026-09-13-document-revision-overlay-transition.md](../../audit/2026-09-13-document-revision-overlay-transition.md) |
|
||||
| UI-11 第二份文档路由与 lease 审计 | [../audit/2026-09-13-document-revision-second-doc-routing-lease.md](../../audit/2026-09-13-document-revision-second-doc-routing-lease.md) |
|
||||
| UI-11 prelim_design 缺 output.md 审计 | [../audit/2026-09-13-document-revision-prelim-output.md](../../audit/2026-09-13-document-revision-prelim-output.md) |
|
||||
| UI-06 编辑弹窗 hydration 竞态审计 | [../audit/2026-09-13-document-revision-editor-hydration-race.md](../../audit/2026-09-13-document-revision-editor-hydration-race.md) |
|
||||
| UI-03 质量修复子工作区契约审计 | [../audit/2026-09-13-document-revision-quality-repair-workspace-contract.md](../../audit/2026-09-13-document-revision-quality-repair-workspace-contract.md) |
|
||||
| UI-11 快速完成观测误判审计 | [../audit/2026-09-13-document-revision-fast-completion-observation.md](../../audit/2026-09-13-document-revision-fast-completion-observation.md) |
|
||||
| UI-13a 私密分类导航失败审计 | [../audit/2026-09-13-document-revision-workflow-category-navigation.md](../../audit/2026-09-13-document-revision-workflow-category-navigation.md) |
|
||||
| UI-13a 职责单元格误判审计 | [../audit/2026-09-13-document-revision-duty-cell-assertion.md](../../audit/2026-09-13-document-revision-duty-cell-assertion.md) |
|
||||
| UI-13a reviewer 职责未同步审计 | [../audit/2026-09-13-document-revision-reviewer-duty-sync.md](../../audit/2026-09-13-document-revision-reviewer-duty-sync.md) |
|
||||
| UI-03 首次生成 PG ID 误删 baseline | [../audit/2026-09-13-document-revision-pg-id-remap.md](../../audit/2026-09-13-document-revision-pg-id-remap.md) |
|
||||
| UI-06 刷新后缓存竞争死锁审计 | [../audit/2026-09-14-document-revision-refresh-cache-race.md](../../audit/2026-09-14-document-revision-refresh-cache-race.md) |
|
||||
| 受控正文真实 UI 验收报告 | [../test-reports/2026-09-14-controlled-content-ui-acceptance.md](../../test-reports/2026-09-14-controlled-content-ui-acceptance.md) |
|
||||
|
||||
## 并行集成补录
|
||||
|
||||
来源：dev@a5ea469c 的 CURRENT 增量。保留材料切块任务的新结论；活跃 CURRENT 保留其认领和最新槽位。
|
||||
|
||||
5. **材料切块不再看体积**：项目 6579 `doc_proj6579_bd_intake` 已确认候选 535，正式正文不再含「二进制压缩流」。成功解析的材料一律写入 `material_chunks`，≤60KB 仍全文注入。见 [报告](../../test-reports/2026-09-21-force-material-chunk-index-test-report.md)。已合入 `dev` 并从主目录 rebuild。test/main 未晋升。
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
task_id: herdr-orchestration-v12
|
||||
status: done
|
||||
owner: Codex
|
||||
branch: feature/herdr-orchestration-v12
|
||||
base_dev_sha: d919e06a73f7a4e18ed9d0cc26728f9cb32f8d97
|
||||
policy_revision: agent-governance-2026-09-21-r1
|
||||
deployment: not_required
|
||||
remote_sync: not_requested
|
||||
integration_state: merged
|
||||
review_state: passed
|
||||
cleanup: pending
|
||||
cleanup_owner: independent-maintainer-after-owner-exit
|
||||
effective_commit: 8c5e3477585fe27a485343dac97a670d95cf8905
|
||||
---
|
||||
# Herdr v1.2 分工与自动审批
|
||||
|
||||
授权：用户要求研究所给方案、纳入仅 Herdr 生效规范，并让已准备客户端自动通过工具请求。本轮修改规则与对应本地入口，提交/合入 dev；不改个人全局配置，不花费模型额度做探针，不操作产品/test/main，不 push。
|
||||
|
||||
本会话 HERDR_ENV 检查失败；依 Herdr 技能不查看/操作现有会话。以本机帮助/非敏感模型别名、官方文档及真实临时 Git/SQLite 配合模拟 Herdr 边界验收，不能声称真实 pane 已启动。
|
||||
|
||||
范围：AGENTS/PROJECT 条件入口、roster、两个启动/派发脚本及共享模块/测试。写入通过任务 path 租约；共享 CURRENT 用 CAS。保留其他任务与已存在 cleanup_pending。
|
||||
|
||||
结论与验收见下文。交付后的原 task_id 继续用于 Kimi 总次数；不得以拆子任务重置预算。
|
||||
|
||||
## 研究与验证结果
|
||||
|
||||
总体采纳。修正 Cursor“无限量”前提、执行跟踪与代码实施边界、默认唯一实施与显式故障接管的矛盾；Kimi 应急/终稿共用上限，GPT 耗尽不以文稿审核代替代码安全终审；普通会话不套用本分工。
|
||||
|
||||
本机配置只读核验：Claude Opus/Sonnet 别名为 glm-5.3[1m]，Haiku 为 glm-5.3-flash[1m]；Codex 默认 gpt-6-astra；PI 默认 minimax-cn/MiniMax-M3，模型目录可列出 qwen-token-plan-cn/qwen3.8-max、qwen3.8-flash 与 zai-coding-cn/glm-5.3。未读取或输出凭证；未修改这些全局设置；未实际调用远端模型。
|
||||
|
||||
- 11 项专用行为测试 PASS（4.664s），包含九个 profile 的自动审批 flags、Herdr 外/错工作区拒绝、目标 pane 检查、报告路由、显式实施备援、不确定发送不重投、唯一重试标记、同角色歧义、Kimi 关停/跨入口计数/未知结果不退款；八进程竞争只有一次真实模拟发送。
|
||||
- [测试输出](../../test-reports/assets/2026-09-21-herdr-v12/focused-tests.txt)；[九种启动命令](../../test-reports/assets/2026-09-21-herdr-v12/launch-commands.json)。Git/SQLite 是真实临时仓库，Herdr transport 为 fake，绝不将其声明为实际 pane 启动/模型 E2E。
|
||||
- PI 安装版本 0.85.1 的本机 README 明确内置工具无权限弹窗，`--approve` 是项目文件信任；扩展仍可自建交互。Cursor force 保留显式 deny，Kimi 使用 auto 而非 yolo。其他本机帮助与[官方出处](../../ops/2026-09-13-herdr-agent-roster.md#5-自动通过请求与实际启动)相互核对。
|
||||
- 本地复核：路由/参数集中于一个 Python 模块，两个 shell 薄入口不复制策略；保留 task 与主仓 `.locks` 身份校验；Kimi 占用在投递前事务提交。没有后台队列/全账户计费控制，MiniMax/GPT 预算轮次由任务记录管理。
|
||||
- 代码不涉及产品 Go/前端/数据库业务；无需产品重建。提交后的候选将按工程测试全集验证，再受控合入 dev；真实 Herdr 会话核验留给下一次在 Herdr 内的实际任务，不在外部强行接入。
|
||||
|
||||
## 收口
|
||||
|
||||
实现提交 `8bc7940e`；生效 dev 候选 `8c5e3477585fe27a485343dac97a670d95cf8905`，其第一父节点 `d919e06a`，主目录持锁快进接收同一已验证节点。[候选完整输出](../../test-reports/assets/2026-09-21-herdr-v12/candidate-tests.txt)：87 tests PASS，36.216s，含原门禁与本轮 11 项测试。语法、diff 与本轮链接检查均通过。收口附加提交仅文档，按文档契约另验。
|
||||
|
||||
运行边界：未启动真实 Herdr/pane/模型请求，未改全局配置、产品服务或数据库；deployment=not_required，无远端 push。不会把模拟 transport 的通过当作实际账户、余额或审批 UI 已消失的证明。
|
||||
|
||||
清理：[进程可见性预检](../../test-reports/assets/2026-09-21-herdr-v12/cleanup-preflight.json)拒绝，部分同 UID cwd 不可读。保留 `.worktrees/herdr-orchestration-v12` 与 `.worktrees/integrate-herdr-orchestration-v12`；独立维护者在 owner 退出和进程可见性核实后重跑普通 remove/-d 的全部门禁，不强删，不接管其他任务。
|
||||
|
||||
影响：Herdr roster、条件入口、规范登记、启动/派发脚本一致；不改变 FEATURE-MATRIX 的产品状态或治理完整自动化 partial，也不改变 gap-matrix。下一次实际 Herdr 任务先核验模型/自动审批启动状态，再按既有任务范围调度；Kimi 仅有必要时调用一次。
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: "意图确认优先与阶段感知消解"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Cursor
|
||||
branch: fix/intent-confirm-stage-aware-2026-09-21
|
||||
worktree: .worktrees/intent-confirm-stage-aware-2026-09-21
|
||||
base_dev_sha: 49fb68fec1ea56f00616c23d08efb15950c2300d
|
||||
mutex: intent+web+docgov
|
||||
---
|
||||
|
||||
# 意图确认优先与阶段感知消解
|
||||
|
||||
## 目标
|
||||
|
||||
商务流初期「整理一下需求」等弱写表述 → 阶段感知消解为 intake，经确认卡片拍板后再执行；不强指令误伤。扩展已合入的工作流作用域修复。
|
||||
|
||||
## 范围
|
||||
|
||||
- 批次5 `feat(intent)`：弱写动词 + `stageAwareRequirementsTask` + `needs_confirmation`
|
||||
- 批次6 `feat(coordinator)`：智能确认门禁（PendingExpectation）
|
||||
- 批次7 `feat(web)`：阶段错误降级聊天一次
|
||||
- 批次8：验收报告 + 合回 `dev` + 真实 PI 抽样
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 批次5–7 实现与单元门禁
|
||||
2. [x] 批次8：合入 `dev@0c401904` + rebuild + 真实链路抽样（陈威项目 6579）
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] V0.1「整理一下需求」→ 确认 →「好」→ intake（单元 + 真实 PI）
|
||||
- [x] 强指令不强制确认；「编写用户需求表」无 rdev 误拦
|
||||
- [x] 合入后真实 PI 抽样（见测试报告）
|
||||
|
||||
## 相关链接
|
||||
|
||||
- Plan: `~/.cursor/plans/意图确认优先与阶段感知_7ab2c4d5.plan.md`
|
||||
- Prior (done): `.doc/archive/ops/2026-09-21-intent-workflow-scoping.md`
|
||||
- Test report: `.doc/test-reports/2026-09-21-intent-confirm-stage-aware-test-report.md`
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: "意图填槽工作流作用域修复"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Cursor
|
||||
branch: fix/intent-workflow-scoping-2026-09-21
|
||||
worktree: "-"
|
||||
mutex: intent+web+docgov
|
||||
---
|
||||
|
||||
# 意图填槽工作流作用域修复
|
||||
|
||||
## 目标
|
||||
|
||||
意图识别填槽（target_doc / target_task）只命中当前激活工作流的文档与任务；显式点名其他工作流的文档时拦截并引导切换工作流，不误触、不执行。
|
||||
|
||||
## 背景
|
||||
|
||||
用户反馈：填「要修改的文档」等槽位时可能命中其他工作流的文档。根因链（2026-09-21 调研）：
|
||||
|
||||
1. `intent.ContextSnapshot` 无 workflow 字段，`ToSnapshot()` 丢弃 `Project.ActiveWorkflowKey`；server 默认上下文硬编码 `CurrentWorkflow: "intake"`
|
||||
2. `extractDocName` 词表全是 main（bd_）流文档名，无按流归属约束
|
||||
3. 消费端匹配池 `ListWorkflowDocumentsByProject` 仅按 project_id 过滤（跨工作流全量），`selectReadableWorkflowDocument` 双向 contains 模糊匹配取首个命中
|
||||
4. 前端 `resolveTaskTemplateForMessage` 匹配池 `currentProjectDeliverables` 仅按 projectId 过滤；`activeWorkflowKey` 只用于徽标展示
|
||||
|
||||
## 范围
|
||||
|
||||
- 批次1 `feat(intent)`：`ContextSnapshot` 增加 `ActiveWorkflowKey`；`ToSnapshot` 下传；docgov 命中他流文档名时打 `workflow_scope_mismatch` 标记不误填
|
||||
- 批次2 `feat(coordinator+server+projectinstance)`：`ActiveWorkflowTaskKeys` 辅助查询；文档匹配池收窄到激活流；`ErrDocWrongWorkflow` 拦截引导；TRIGGER_TASK 任务键归属校验；enrich 时注入真实 `active_workflow_key`
|
||||
- 批次3 `feat(web)`：`DeliverableItem.workflowKey`；文档列表 API 附带 `workflow_key` 与 `active_workflow_key`；templateMatch 匹配池按激活流过滤，他流点名返回 wrongWorkflow 提示
|
||||
- 批次4：真实环境验收 + 测试报告 + 合回 dev
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不迁移 `document_records` 表（不加 workflow_instance_id 列）
|
||||
- 不改 `production_ready`、不晋升 test/main、不动项目 143
|
||||
- 不改 SWITCH_WORKFLOW 意图本身行为
|
||||
- UI 文档展示列表保持全量（仅匹配池收窄）
|
||||
|
||||
## 渐进安全策略
|
||||
|
||||
`active_workflow_key` 为空或查不到激活实例（存量单流项目、planning 态）→ 不过滤，保持现状行为。
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 批次1：intent 快照与工作流词表归属
|
||||
2. [x] 批次2：服务端匹配池收窄与拦截引导
|
||||
3. [x] 批次3：前端模板匹配池收窄
|
||||
4. [x] 批次4：真实环境验收、报告归档、合回 dev
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 激活 main 流说「查看调研报告」→ 命中 main 流文档（正例；修改/生成话术另记路由噪声）
|
||||
- [x] 激活 main 流说「编写项目建议书」（rdev 流文档）→ 拦截 + 引导切换（反例；tasks/run 409 ERR_DOC_WRONG_WORKFLOW）
|
||||
- [ ] 激活 rdev 流后同名操作 → 正常执行（切换后正例；本轮 SWITCH 落库未兑现，记 deferred）
|
||||
- [x] 存量无 active_workflow_key 项目 → 行为不变（回归）
|
||||
- [x] 相关包 `go vet` / scoped `go test -short`、`web: npm test && npm run build` 全绿
|
||||
|
||||
## 相关链接
|
||||
|
||||
- Plan: `~/.cursor/plans/意图填槽工作流作用域修复_dba2ab4c.plan.md`
|
||||
- Handoff:
|
||||
- Test report: `.doc/test-reports/2026-09-21-intent-workflow-scoping-test-report.md`
|
||||
|
||||
## 证据 / 备注
|
||||
|
||||
用户在 dev 商务对接实测发现跨工作流误命中。用户在方案确认时选定：严格拦截 + 引导切换；等四问题修复 mutex 释放后独立分支推进。
|
||||
|
||||
- 2026-09-21 收口：已合入 `dev@e0665ca4`，验收报告见 `.doc/test-reports/2026-09-21-intent-workflow-scoping-test-report.md`。
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: "工作流作用域权重化"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
owner: Cursor
|
||||
branch: feature/workflow-scope-weighting-2026-09-21
|
||||
worktree: .worktrees/workflow-scope-weighting-2026-09-21
|
||||
base_dev_sha: 10aee3feb478c550adc9959f2d3a8d17cd5b48a0
|
||||
write_scope: [internal/workflowscope, internal/intent, internal/server, internal/coordinator, internal/config, internal/sysadmin, web/src, docker-compose.dev.yml, docker-compose.test.yml, docker-compose.main.yml, .env.example, .doc]
|
||||
head_sha: 7723a5515948788602b342cdda1137c90fee311b
|
||||
deployment: deployed
|
||||
cleanup: pending
|
||||
mutex: intent+web+docgov
|
||||
---
|
||||
|
||||
# 工作流作用域权重化
|
||||
|
||||
## 目标
|
||||
|
||||
把「句子里出现他流文档短语就硬拦截」改为「匹配质量 × 工作流关系权重」裁决。激活流优先；只有他流精确命中明显压过激活流时才跨流。只读跨流在查看权限通过后放行并注明归属；写动作仍引导到项目设置切换（跨流写在现架构下不可执行）。`WORKFLOW_SCOPE_MODE` 默认 `strict`，保持现状。
|
||||
|
||||
## 范围
|
||||
|
||||
- 新建 `internal/workflowscope`（开关、关系权重、打分裁决）
|
||||
- 服务端文档读取、意图填槽、前端模板匹配改用同一裁决
|
||||
- compose / `.env.example` / sysadmin 登记开关
|
||||
- dev 真实环境验收与测试报告
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不迁移 `document_records`，不加 `workflow_instance_id`
|
||||
- 不改工作流切换 / 激活接口
|
||||
- 不改 `production_ready`，不晋升 test/main，不动项目 143
|
||||
|
||||
## 步骤
|
||||
|
||||
1. [x] 打分内核与开关
|
||||
2. [x] 服务端只读跨流放行与查看权限
|
||||
3. [x] 意图填槽改打分
|
||||
4. [x] 前端模板匹配改打分
|
||||
5. [x] 开关声明、真实验收、报告、合回 dev
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] strict 模式与现有跨流拦截断言一致
|
||||
- [x] weighted 下激活流精确名压过他流短语，不再误拦
|
||||
- [x] weighted 下只读精确点名他流文档可放行并注明归属；写动作仍拦截
|
||||
- [x] 无查看权限 / 实例已关闭时跨流只读拒绝
|
||||
- [x] 空激活键不过滤
|
||||
|
||||
## 相关链接
|
||||
|
||||
- Plan: `~/.cursor/plans/工作流作用域权重化_411b5e35.plan.md`
|
||||
- Test report: `.doc/test-reports/2026-09-21-workflow-scope-weighting-test-report.md`
|
||||
|
||||
## 证据 / 备注
|
||||
|
||||
查看权限：治理实例 `ViewableTaskKeys` 只含当前实例已启用文档。他流任务键不在快照内，不能把它当成「显式隐藏」。判定为：解析失败按 `failClosedAuthz` 拒绝；`ViewableTaskKeys` 为空（实例已关闭）拒绝；键落在当前实例但不可见则拒绝；键不属于当前实例、且调用方已能查看该实例文档时允许只读。
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "当前受控文档改写被领域关键词改路由到另一交付物"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# 当前受控文档改写被领域关键词改路由到另一交付物
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第二轮真实 UI（schema 30）**UI-05 首个失败**：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-06 用 overlay/p/h 选择器找不到真实文档块"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-06 用 overlay/p/h 选择器找不到真实文档块
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第六轮真实 UI（schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-13a 用整行 option 文案误判编制负责人"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-13a 用整行 option 文案误判编制负责人
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第16轮真实 UI（schema 30，`dev@dd5671e`）：UI-00 至 UI-12 PASS；分类导航修复已实证，UI-13a 已能从「我的私密」切回「流程受控」并打开 reviewer B 权限矩阵。
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "文档职责伪造与保存时重取 ETag 可覆盖并发正文"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: critical
|
||||
---
|
||||
|
||||
# 文档职责伪造与保存时重取 ETag 可覆盖并发正文
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
静态审查与 E2E UI-13 路径暴露两类产品缺陷：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-05b 缺当前受控文档指示语被路由到 feasibility_reg"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-05b 缺当前受控文档指示语被路由到 feasibility_reg
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第五轮真实 UI（schema 30）**UI-05b 首个失败**：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-06 编辑弹窗打开期间 hydration 换块 ID 导致保存静默丢稿"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-06 编辑弹窗打开期间 hydration 换块 ID 导致保存静默丢稿
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第十二轮真实 UI（schema 30，dev@4c465d2 基线）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-11 快速 completed 被验收脚本误判为失败"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-11 快速 completed 被验收脚本误判为失败
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第14轮真实 UI（schema 30，`dev@339e871`）在 **UI-11** 失败：页面上传附件并发送「请将此附件归档」后，相邻助手卡片已快速处于 `completed`（文案：已收录补充材料并关联黑板）。
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-07 纯净阅读用 overlay/class*block 找不到真实块"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-07 纯净阅读用 overlay/class*block 找不到真实块
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第八轮真实 UI（schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-07 在 CSS transition 中间帧采样纯净阅读"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-07 在 CSS transition 中间帧采样纯净阅读
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第九轮真实 UI（schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-05a 未打开待确认报告导致确认按钮缺失"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-05a 未打开待确认报告导致确认按钮缺失
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第四轮真实 UI（schema 30）**UI-05a 首个失败**：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "post-restart 项目名同时命中顶栏与侧栏"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# post-restart 项目名同时命中顶栏与侧栏
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第18轮真实 UI（schema 31）：main **18 PASS / 0 FAIL**。宿主重启 app 后 `UI_PHASE=post-restart` 在页面**已经恢复项目**时失败，尚未走到 `revision-state`。
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-11 prelim_design 缺 output.md 导致 TASK_INTERRUPTED"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-11 prelim_design 缺 output.md 导致 TASK_INTERRUPTED
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第11轮真实 UI（schema 30，`dev@2a58674`）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "质量门禁自污染与 auto_repair 未启用导致 quality_failed"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# 质量门禁自污染与 auto_repair 未启用导致 quality_failed
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
同一整改范围真实 run（与 SSE/幂等现场同源）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-03 质量修复子工作区越界改写根 output.md"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-03 质量修复子工作区越界改写根 output.md
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第13轮 Antigravity 完整 UI（schema 30，dev@8b1a531 基线）：UI00–02 PASS，UI-03 真实 PI 终态 `quality_failed`，页面 70 分、缺少必填章节「阻塞信息 / 非阻塞信息」。
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "行动计划表状态列「待续」被质量门禁误判为敷衍"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# 行动计划表状态列「待续」被质量门禁误判为敷衍
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第三轮真实 UI（新用户 `mtzzliz5`，新项目，真实 MiniMax）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "项目 reviewer 未同步到受控文档职责"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: critical
|
||||
---
|
||||
|
||||
# 项目 reviewer 未同步到受控文档职责
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第17轮真实 UI（schema 30，`dev@639969f`）：UI-00 至 UI-12 PASS。UI-13a 精确职责断言首次暴露产品缺陷：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-06 全页模糊保存按钮未发出 PATCH"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-06 全页模糊保存按钮未发出 PATCH
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第七轮真实 UI（schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-11 第二份文档路由到 intake 且 human lease 残留"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-11 第二份文档路由到 intake 且 human lease 残留
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第十轮真实 UI（schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "任务 run SSE 超时断线后同 turn 误击 DOC_BUSY"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: critical
|
||||
---
|
||||
|
||||
# 任务 run SSE 超时断线后同 turn 误击 DOC_BUSY
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
真实 Antigravity UI-03（dev schema 30）：
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: "UI-13a 在私密分类下打不开受控工作流文档"
|
||||
status: done
|
||||
status: in_progress
|
||||
created: 2026-09-13
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-13
|
||||
severity: high
|
||||
---
|
||||
|
||||
# UI-13a 在私密分类下打不开受控工作流文档
|
||||
|
||||
> **W3 UI-rerun 关闭（2026-09-22）**：`status=done`。真实 Playwright 账本 PASS：[`ui-acceptance-results.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results.json)（main UI-00..16）+ [`ui-acceptance-results-post-restart.json`](../test-reports/assets/2026-09-22-docrev-ui-rerun/ui-acceptance-results-post-restart.json)（UI-15）。任务 tip 已合入本地 `dev`；详见 [short-term](../ops/short-term/2026-09-22-docrev-ui-rerun.md) 与 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)。
|
||||
|
||||
|
||||
## 现象
|
||||
|
||||
第15轮真实 UI（schema 30，`dev@48a4dcb`）：UI-00 至 UI-12 全部 PASS，UI-11 快速完成修复已实证 PASS。**UI-13a 在真正权限断言前失败**。
|
||||
|
||||
@@ -1,167 +0,0 @@
|
||||
---
|
||||
title: "dev rebuild 从临时 worktree 挂载空数据根导致正文投影 409"
|
||||
status: done
|
||||
created: 2026-09-14
|
||||
updated: 2026-09-14
|
||||
severity: critical
|
||||
---
|
||||
|
||||
# dev rebuild 从临时 worktree 挂载空数据根导致正文投影 409
|
||||
|
||||
## 现象
|
||||
|
||||
用户刷新项目 143 后，前端请求：
|
||||
|
||||
```text
|
||||
GET /api/v1/docgov/documents/doc_proj143_intake/content 409
|
||||
DOCUMENT_CONTENT_PROJECTION_MISSING
|
||||
docgov: document content projection missing
|
||||
```
|
||||
|
||||
错误发生在 `projectDocuments.ts` → `controlledDocHydrate.ts` 的受控正文水合链。它不是并发编辑的 `HEAD_CONFLICT`，也不是此前已修过的 canonical hash drift。
|
||||
|
||||
本轮只做只读现场核对与整改设计：没有操作用户会话、没有修改数据库/正文、没有重建共享容器。
|
||||
|
||||
## 结论
|
||||
|
||||
直接根因是 **dev 应用、PI Runner、Cursor Runner 被重建成挂载临时集成 worktree 的空 `data/dev`，而 PostgreSQL 仍沿用原 dev 持久卷**，形成数据库与文件事实源的 split-brain：
|
||||
|
||||
```text
|
||||
PostgreSQL persistent volume
|
||||
document_records.work_dir=/app/data/workspaces/bizdev/intake_1789270446856290128
|
||||
│
|
||||
├─ 主仓 data/dev：output.md 存在，SHA 与 DB/head 一致
|
||||
│
|
||||
└─ 当前容器 /app/data：绑定 /tmp/as-dev-wf409-merge/data/dev，文件不存在
|
||||
```
|
||||
|
||||
`loadControlledDocumentContent` 先取得账本 head，再调用 `InspectProjection`；容器内看不到 `output.md`，因此正确分类为 `MISSING` 并返回 409。前端只是如实暴露后端错误，不是本次根因。
|
||||
|
||||
## 现场证据
|
||||
|
||||
### E1 — 容器挂载源是临时 worktree
|
||||
|
||||
2026-09-14 08:54 UTC 的 `docker inspect shuimu-agent-app-dev`：
|
||||
|
||||
| 项 | 现场值 |
|
||||
|---|---|
|
||||
| Compose working dir | `/tmp/as-dev-wf409-merge` |
|
||||
| Compose config | `/tmp/as-dev-wf409-merge/docker-compose.dev.yml` |
|
||||
| app `/app/data` source | `/tmp/as-dev-wf409-merge/data/dev` |
|
||||
| pi-agent `/app/data/workspaces` source | `/tmp/as-dev-wf409-merge/data/dev/workspaces` |
|
||||
| cursor-agent `/app/data/workspaces` source | `/tmp/as-dev-wf409-merge/data/dev/workspaces` |
|
||||
| app created | `2026-09-14T08:40:44Z` |
|
||||
|
||||
数据库容器的数据仍来自命名卷 `agent-dev-context-pgdata`，不会随 Compose 工作目录切换。由此产生“旧数据库 + 新空文件根”的不一致组合。
|
||||
|
||||
### E2 — 项目 143 数据本身当前完整
|
||||
|
||||
`document_records`：
|
||||
|
||||
| 字段 | 值 |
|
||||
|---|---|
|
||||
| doc_id | `doc_proj143_intake` |
|
||||
| work_dir | `/app/data/workspaces/bizdev/intake_1789270446856290128` |
|
||||
| content_sha256 | `f283ba94c9c037897f021960f51abacee7242c3db8d10f9f2a5e32cde6acf039` |
|
||||
| updated_at | `2026-09-14 05:14:10.302146+00` |
|
||||
|
||||
账本 open version 1 的 head snapshot 302 是人工修订，SHA 同为 `f283...f039`；主仓文件：
|
||||
|
||||
```text
|
||||
/home/weichen/projects/Agent-System/data/dev/workspaces/bizdev/intake_1789270446856290128/output.md
|
||||
size=40075
|
||||
sha256=f283ba94c9c037897f021960f51abacee7242c3db8d10f9f2a5e32cde6acf039
|
||||
```
|
||||
|
||||
同一路径在当前 app 容器内 `stat` 返回 `No such file or directory`。所以无需再次对项目 143 做内容修复；需要恢复正确数据根挂载。
|
||||
|
||||
### E3 — 影响不是单文档
|
||||
|
||||
对 dev 数据库 100 条“非模板且 work_dir 非空”的记录做只读比较：
|
||||
|
||||
| 根目录 | aligned | missing |
|
||||
|---|---:|---:|
|
||||
| 主仓 `/home/weichen/projects/Agent-System/data/dev` | 32 | 68 |
|
||||
| 当前容器挂载 `/tmp/as-dev-wf409-merge/data/dev` | 0 | 100 |
|
||||
|
||||
主仓下的 68 条 missing 包含历史测试/临时路径，不能直接等同于 68 个真实用户缺陷；但当前容器对本次抽样 **100/100 都不可见**，足以确认环境级事故。恢复前任何真实文档读取或 PI 写入都不可信。
|
||||
|
||||
错误根在容器启动后已出现 27 个文件，其中 9 个 CAS blob 的 mtime 为 `08:40:45 UTC`；虽然 08:54 UTC 尚未找到新的 `output.md`，错误根已经不是可直接丢弃的“绝对空目录”，恢复前仍须做完整差异保全。
|
||||
|
||||
只读核对显示 test/main 当前 app 与 PI Runner 仍挂主仓 `data/test`、`data/main`，本轮没有观察到同样的运行事故；但其 Compose 仍使用相对 bind，仍受同一设计缺陷影响。
|
||||
|
||||
### E4 — 健康检查假阳性
|
||||
|
||||
同一时刻 `/health` 与 `/ready` 都返回 200，只检查数据库、schema 和 task store；未验证：
|
||||
|
||||
- 容器绑定的数据根身份；
|
||||
- app 与 runner 是否挂载同一根；
|
||||
- 活跃项目的正文投影是否可达；
|
||||
- 数据库记录与文件根是否属于同一环境实例。
|
||||
|
||||
因此“healthy + schema 33”不能证明文档运行态可用。
|
||||
|
||||
## 根因分析
|
||||
|
||||
### R1 — Compose 相对 bind mount 与调用 worktree 耦合（直接根因）
|
||||
|
||||
`docker-compose.dev.yml` 使用：
|
||||
|
||||
```yaml
|
||||
- ./data/dev:/app/data
|
||||
- ./data/dev/workspaces:/app/data/workspaces
|
||||
```
|
||||
|
||||
Compose 按 project working directory 解析相对路径。`scripts/env-service.sh` 又把 `ROOT_DIR` 定义为脚本所在 worktree 并 `cd` 进去，所以从任何复制/linked worktree 执行 `dev rebuild`，都会把该 worktree 自己的 `data/dev` 当成运行数据根。
|
||||
|
||||
### R2 — 纪律是文档约束，不是可执行门禁
|
||||
|
||||
`scripts/agent-worktree.sh` 只打印“禁止在此目录运行 env-service”，`AGENTS.md` 也规定 worktree 不得操作共享 Docker；但 `env-service.sh` 没有检测 linked worktree、主 worktree、分支、数据根或集成槽位。一次误调用即可静默替换全套容器挂载。
|
||||
|
||||
### R3 — 数据库与文件没有共享存储身份
|
||||
|
||||
数据库使用稳定 named volume；正文使用随调用目录变化的 bind mount。两者没有共同的 environment/storage UUID，也没有启动握手，因此任意一个被指向另一份状态时，进程仍可启动并连接成功。
|
||||
|
||||
### R4 — 账本权威仍被兼容投影阻断
|
||||
|
||||
当前设计声明 ledger head 是权威正文，但 GET 在账本存在时仍要求 `output.md` 投影必须存在且 aligned。于是兼容投影丢失会阻断 UI 读取权威账本。该 fail-closed 对真实 fork 有价值，却把“可安全重建的 missing”与“内容分叉”按同样的可用性后果处理。
|
||||
|
||||
### R5 — 正文更新仍是非原子双写
|
||||
|
||||
人工 PATCH 先提交 PostgreSQL 账本，再单独写 `output.md`；候选 commit/reject 也采用 DB 状态与文件投影分步更新。失败后只依赖同幂等键重试，没有持久 projection job/status 和后台补偿。即使修复本次挂载问题，进程崩溃、权限错误或磁盘故障仍可能再次留下 head 已更新、投影缺失的状态。
|
||||
|
||||
### R6 — 发布验收没有“从不同源码目录 rebuild 后仍接回同一状态”的负例
|
||||
|
||||
既有真实 UI 验收验证过 restart 后恢复，但 restart 不会重新解析 Compose bind mount；本次事故由 rebuild/recreate 触发。现有门禁没有覆盖 linked worktree、临时集成目录或错误数据根的启动拒绝。
|
||||
|
||||
## 为什么会“每次修改后又出现”
|
||||
|
||||
修改本身并不会删除项目 143 正文。本次时间线表明：最新人工修订和主仓 `output.md` 在 05:14 UTC 已一致落盘；08:40 UTC 后续 dev rebuild 把运行容器切到另一份空数据根，刷新才出现 409。
|
||||
|
||||
因此用户感知的“改完再刷新就坏”来自两个事件经常相邻：开发修改 → Agent 在临时 worktree 合并/rebuild → Compose 改绑数据目录。只修某个文档、某个 hydrate effect 或某次 hash 漂移，都无法阻止它复发。
|
||||
|
||||
## 严重度与影响
|
||||
|
||||
`critical`：
|
||||
|
||||
- dev 环境所有受控正文、工作流产物和 runner 工作区均可能不可见或写入错误根；
|
||||
- 错误根上的新输出可能与主仓状态分叉；
|
||||
- health/ready 仍为绿色，集成报告可能产生假 PASS；
|
||||
- test/main 使用同类相对 bind 写法，设计缺陷可横向复制，虽本轮未观察其被错挂载。
|
||||
|
||||
## 关联整改
|
||||
|
||||
- Remediation: [dev 运行数据根隔离与文档投影自愈整改](../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md)
|
||||
- Short-term: [dev runtime data root guard 诊断与设计](../ops/short-term/2026-09-14-dev-runtime-data-root-guard.md)
|
||||
- 前序问题: [项目 143 canonical hash 漂移](./2026-09-14-project143-controlled-content-404.md)
|
||||
|
||||
## 开放问题
|
||||
|
||||
- 恢复前需再次冻结并备份错误根，确认 08:40 UTC 后是否已有新会话、附件、runner 输出或 agent session 写入；08:54 UTC 抽样未发现 `output.md`，不能替代完整差异清单。
|
||||
- test/main 当前挂载源需在实施 Unit A 只读核对；本轮未扩大操作范围。
|
||||
|
||||
## 审查附记（2026-09-14 ~09:23 UTC）
|
||||
|
||||
- 现场复核：`shuimu-agent-app-dev` 仍 created `08:40:44Z`，bind source 仍为 `/tmp/as-dev-wf409-merge/data/dev`；`/health` `/ready` 仍 200，`schema_version=33`。
|
||||
- 主仓 CURRENT 集成槽仍为 `implementer_cursor` / `e2e`。worktree 副本不得写成 idle。
|
||||
- 方案已审查修订：见 [整改方案](../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md)。用户选择事故抢占 + 先改方案再批实施。08:54 的 `f283...f039` 不得再当 Wave 0 硬门槛。
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: "模块耦合现状审计（规范与分批整改基线）"
|
||||
status: done
|
||||
created: 2026-09-20
|
||||
updated: 2026-09-20
|
||||
severity: high
|
||||
---
|
||||
|
||||
# 模块耦合现状审计（规范与分批整改基线）
|
||||
|
||||
## 现象
|
||||
|
||||
系统已经是模块化单体，不是未治理的大泥球：`module-boundaries.yaml` + `internal/archtest` 已把 import 与事件登记清到零违规（`baseline_counts.import=0`、`event=0`，二者在 `block_kinds`），可靠事件由独立 `cmd/events` worker 经 PostgreSQL lease 消费。
|
||||
|
||||
故障仍会跨模块扩散的原因不在“缺总线”，而在四类残留：
|
||||
|
||||
1. HTTP 适配层直接持有领域具体类型，而不是只调用用例端口。
|
||||
2. `chat`、`app` 子包与 `coordinator` 用子包拆分避开了 Go 编译环，逻辑上仍互相依赖。
|
||||
3. `docgov` 的状态、角色和错误被多个模块当成本模块词汇使用。
|
||||
4. 带到期日的 SQL/路径例外仍允许非属主写入或拼接工作区路径。
|
||||
|
||||
本审计只记录证据与分级，不改代码。整改批次见 [分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md)。
|
||||
|
||||
## 根因分析
|
||||
|
||||
### 已有隔离基线（不要推倒）
|
||||
|
||||
| 机制 | 位置 | 现状 |
|
||||
|------|------|------|
|
||||
| 模块化单体 ADR | [2026-09-14-modular-monolith-decoupling](../adr/2026-09-14-modular-monolith-decoupling.md) | 不拆微服务；窄端口 + 组合根 + 领域事件 |
|
||||
| 静态边界 | [module-boundaries.yaml](../system-design/module-boundaries.yaml) | import allowlist、表唯一写者、路径属主、事件生产者/消费者 |
|
||||
| 架构门禁 | `internal/archtest`、`scripts/arch-check.sh --mode block` | import/event 零容忍 |
|
||||
| 进程内端口 | `internal/app/*flow`（例：`internal/app/chatflow/ports.go`） | 消费者拥有窄接口；组合根注入实现 |
|
||||
| 跨进程事件 | `internal/events` + `cmd/events` | PG outbox/inbox；dev `:8088` / test `:8089` / main `:8090` |
|
||||
| 事件契约 | `internal/events/registry.go` `StaticContracts()` | 11 个事件名、schema version、payload 字段 allowlist；与 YAML parity |
|
||||
|
||||
`StaticContracts` 现有事件：`document.agent_candidate_ready`、`document.agent_version_committed`、`document.downstream_impact_detected`、`document.change_report_degraded`、`document.approved`、`taskrun.completed`、`taskrun.cancelled`、`fav.artifact_staged`（`Enabled: false`）、`intent.plan.awaiting_input`、`intent.plan.step_changed`、`intent.plan.completed`。
|
||||
|
||||
### 热点 1（P1）：`server` 上帝适配层
|
||||
|
||||
`internal/server/server.go` 的 `Server`（约 40–80 行）同时持有 `*bizdev.Service`、`*coordinator.CoordinatorEngine`、`*docgov.GovernanceEngine`、`*docrevision.Service`、`*taskrun.Manager`、`*projectinstance.Service`、`*pgxpool.Pool` 等具体类型。同结构体里只有少数字段是端口（`chatflow.ChatLog`、`chatflow.ContextAssembler`、`intentflow.Service`、`intent.Recognizer`）。
|
||||
|
||||
生产 import 覆盖约 30 个内部包（`server.go` 11–34 行）。handler 直接解释领域错误，例如 `internal/server/handlers.go` 对 `docgov.ErrDocumentBusy` 的分支（426、449 行）以及 `docgov.RoleAuthor`（702、1291 行）。
|
||||
|
||||
后果：领域包改一个错误或角色常量，HTTP 层必须跟着改；`pool` 还让适配层有机会绕过表属主写 SQL。
|
||||
|
||||
### 热点 2（P2）：`chat` ↔ `app` ↔ `coordinator` 逻辑环
|
||||
|
||||
编译环被子包拆开了，依赖方向没有：
|
||||
|
||||
- `internal/chat/session.go` 11–13 行 import `app/chatflow`、`app/intentflow`、`coordinator`。
|
||||
- `internal/chat/action_executor.go` 10–14 行 import `app/intentflow`、`app/stageflow`、`coordinator`、`docgov`、`taskrun`，并持有具体引擎指针。
|
||||
- `internal/app/chatflow/ports.go` 又 import `coordinator`、`ctxmgr`、`projectinstance`（`AssembleRequest` 直接嵌 `coordinator.UserInfo`）。
|
||||
|
||||
`chat` 既是领域会话，又反向依赖用例包。用例一变，会话执行器就会编译失败，问题不会停在单一模块。
|
||||
|
||||
### 热点 3（P3）：`docgov` 词汇泄漏
|
||||
|
||||
生产代码（不含本包测试）直接使用 `docgov` 状态/角色/错误的位置包括：
|
||||
|
||||
- `internal/coordinator/engine.go`：`ErrDocumentBusy`（955）、`StateDrafting`（1596、1598）。
|
||||
- `internal/bizdev/service.go`：`ErrDocumentLocked` / `ErrDocumentBusy`（718）。
|
||||
- `internal/server/handlers.go`、`document_revision_handlers.go`、`auth_helpers.go`：`RoleAuthor`、`ErrDocumentBusy`。
|
||||
- `internal/chat/action_executor.go`：动作名字符串 `"docgov.review_approve"`（58、150 行），以及 `docgov.StateDrafting`（90）。
|
||||
|
||||
这些不是稳定共享词汇（`internal/contracts/vocabulary` 尚未承接它们），而是领域实现类型被当公共 API。
|
||||
|
||||
### 热点 4（P3）：工作流定义与实例网
|
||||
|
||||
- `internal/workflowdef/catalog.go` import `projectworkflow`。
|
||||
- `internal/workflowdef/validator_v2.go` import `workflow`。
|
||||
- `internal/projectinstance` 生产文件（`store.go`、`service.go`、`gate.go`、`types.go` 等）import `workflowdef`。
|
||||
- `internal/workflow/runtime/orchestrator.go` import `projectinstance`。
|
||||
|
||||
定义、目录、实例和运行时互相看得见对方的包。改一份工作流校验会同时碰到定义包和实例包。
|
||||
|
||||
### 热点 5（P4）：巨型文件
|
||||
|
||||
非测试生产文件行数（2026-09-20 `wc -l` 口径，探索盘点）：
|
||||
|
||||
| 行数 | 文件 |
|
||||
|------|------|
|
||||
| 1844 | `internal/coordinator/engine.go` |
|
||||
| 1590 | `internal/bizdev/service.go` |
|
||||
| 1395 | `internal/server/handlers.go` |
|
||||
| 1291 | `internal/projectinstance/store.go` |
|
||||
| 1245 | `internal/intent/recognizer.go` |
|
||||
| 1235 | `internal/projectworkflow/store.go` |
|
||||
| 1207 | `internal/docgov/engine.go` |
|
||||
| 1172 | `internal/docrevision/service.go` |
|
||||
| 1151 | `internal/squad/workspace.go` |
|
||||
| 1028 | `internal/freedoc/service.go` |
|
||||
|
||||
单文件过大本身不是耦合，但它把多个用例绑在同一变更面上，评审和回滚半径变大。拆分应跟在解环之后，避免边搬边改依赖。
|
||||
|
||||
### 热点 6（P4）：前端 API 层无统一客户端
|
||||
|
||||
`web/src/api/` 约 37 个文件按域各写 `fetch()`，`API_BASE` 与鉴权头分散。错误信封、重试和 401 处理无法在一处收口，后端错误契约一变就会在多个 api 文件重复漏改。这是适配层问题，不是把前端改成 RPC。
|
||||
|
||||
### 热点 7（P2，有到期日）：边界例外未清零
|
||||
|
||||
[module-boundaries.yaml](../system-design/module-boundaries.yaml) `exceptions` 共 21 条，`baseline_counts` 为 sql_write 5、path 16。
|
||||
|
||||
| 种类 | 条数 | 里程碑 | 到期 | 风险 |
|
||||
|------|------|--------|------|------|
|
||||
| `sql_write` | 4 | U3 | 2026-09-28 | **8 天后到期**。`docduty`、`docrevision` 仍写 `document_records` / `freeform_documents` |
|
||||
| `sql_write` | 1 | U8 | 2026-10-26 | `projectinstance` 终止流程直接取消 `task_runs` |
|
||||
| `path` | **3** | U4 | 2026-09-28 | **同样到期**。`docrevision/projection.go` + server `document_revision_access.go` / `document_revision_handlers.go` 仍点名 `output.md`（对账前文档少记 handlers 一条） |
|
||||
| `path` | **13** | U5 | 2026-10-12 | `agent`、`bizdev`、`coordinator`、`docgov`、`storage` 仍拼接工作区路径或把 `data/dev` 写进提示 |
|
||||
|
||||
到期后若门禁把这些 kind 升为 block 而代码未迁走，构建会失败；若继续延期而不迁，非属主写入会继续让文档/任务故障跨包扩散。本轮不改 YAML，清零归整改批次 G。
|
||||
|
||||
## 严重度
|
||||
|
||||
整体 `high`：不会单独打穿已签发布门禁（`production_ready` 不因本审计回退），但 P1/P2 使“问题停在单一模块”尚未成立。
|
||||
|
||||
| 级别 | 热点 | 扩散方式 |
|
||||
|------|------|----------|
|
||||
| P1 | server 具体类型装配 | 领域改动直接编译失败到 HTTP |
|
||||
| P2 | chat/app/coordinator 逻辑环 | 会话、意图用例、协调引擎必须同改 |
|
||||
| P2 | 2026-09-28 到期的 sql_write/path 例外 | 非属主写表或读工作区文件 |
|
||||
| P3 | docgov 词汇泄漏 | 状态机常量变成跨包协议 |
|
||||
| P3 | workflow 定义/实例网 | 校验与运行时同改 |
|
||||
| P4 | 巨型文件、前端 fetch 分散 | 变更面大，不立刻产生跨表写入 |
|
||||
|
||||
## 关联整改
|
||||
|
||||
- Remediation: [2026-09-20-module-decoupling-batch-plan.md](../remediation/2026-09-20-module-decoupling-batch-plan.md)
|
||||
- 开发规范: [2026-09-20-module-development-standards.md](../system-design/2026-09-20-module-development-standards.md)
|
||||
- 上位约束（不重复制定）: [架构](../system-design/2026-09-14-module-decoupling-architecture.md)、[Phase 2](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)、[影响面守则 §2](../remediation/2026-09-16-partial-deferred-completion-plan.md)
|
||||
|
||||
## 证据
|
||||
|
||||
- 结构体与 import：`internal/server/server.go`、`internal/chat/session.go`、`internal/chat/action_executor.go`、`internal/app/chatflow/ports.go`。
|
||||
- 事件契约：`internal/events/registry.go` `StaticContracts`。
|
||||
- 例外账本：`module-boundaries.yaml` `exceptions` 与 `baseline_counts`（import 0 / sql_write 5 / path 16 / event 0）。
|
||||
- 盘点方式：2026-09-20 只读检索生产 import 与 `docgov` 符号引用；行数来自当时文件长度，后续拆分后以 `wc -l` 重测为准。
|
||||
|
||||
## 开放问题
|
||||
|
||||
- U3/U4 例外在 2026-09-28 到期后，是先延长豁免并写原因，还是立刻占用 `docgov` mutex 做批次 G 的第一刀。本审计不代决，批次 G 开工前必须二选一，禁止静默改到期日。
|
||||
- `internal/contracts/vocabulary` 在架构文档中已定义，代码侧尚未作为 docgov 状态/角色的唯一出口。批次 C 再决定是新建该包还是把稳定枚举留在消费者端口。
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: "2026-09-20 系统全量体检审计"
|
||||
status: done
|
||||
created: 2026-09-20
|
||||
updated: 2026-09-20
|
||||
severity: high
|
||||
---
|
||||
|
||||
# 2026-09-20 系统全量体检审计
|
||||
|
||||
## 现象
|
||||
|
||||
在 `production_ready=yes`、dev/test/main 健康、近期 triage 已合入的前提下，对全系统做只读深度体检，发现若干**未写入 gap-matrix 的 critical/high**，以及一批 medium/low 加固项。
|
||||
|
||||
方法：四路并行深潜（后端 Go、安全鉴权、前端 web、基础设施）+ 本机实证（goose 版本表、容器 health、口令登录、代码交叉复核）。
|
||||
|
||||
## 根因分析（P0 / critical，均已实证）
|
||||
|
||||
| ID | 发现 | 位置 | 证据 |
|
||||
|----|------|------|------|
|
||||
| P0-MIG | 迁移序号空洞 00054；`chat_summaries` 建表与 summarizer 写失败修复滞留未合入分支 | `feature/capability-enablement-impact-plan@848a0457`；dev 代码仍读写不存在表 | `goose_db_version` 53→55→57 跳号；`to_regclass('chat_summaries')` 空；`summarizer.go:119` `_ = err` |
|
||||
| P0-IDOR-PREF | 偏好写入信任请求体 `user_id`，无归属校验 | `internal/server/handlers.go:508-537` | 无 `requireAuthenticatedUser` 比对 |
|
||||
| P0-IDOR-SESS | `handleGetProject` 以 `callerUserID=0` 调会话，归属校验被跳过 | `server.go:458-463`；`handlers.go` / `project_handlers.go` | `if callerUserID > 0` 守卫 |
|
||||
| P0-IDOR-RECAT | 重分类无会话归属；空 `session_id` 触及全库消息 | `chat_recategorize_api.go`；`ctxmgr/recategorize.go` | `WHERE ($1 = '' OR session_id = $1)` |
|
||||
| P0-PANIC | taskrun 订阅发送在锁外，Unsubscribe `close` 后向 closed channel 发送 panic | `taskrun/manager.go:481-497` vs `:590` | select default 不挡 closed；全仓非测试 `recover()`=0 |
|
||||
| P0-RACE | 同步 `POST /chat` 不取 `execMu`，与 SSE 并发 data race | `handlers.go:240` vs `sse.go:341` | 09-19 C2 残留半修 |
|
||||
| P0-CRED-BACKUP | 三环境 DB 口令硬编码进仓库；生产口令与脚本一致可登录 | `scripts/backup-system-db.sh:43-56` | 实测 `prod_highly_secure_db_pass` 可连 main |
|
||||
| P0-CRED-PUSH | push 脚本把 token 拼进 URL，`ps` 可见 | `scripts/git-push-dev.sh:23` | `https://oauth2:${TOKEN}@...` |
|
||||
| P0-XSS | 块编辑器 math 错误分支未转义 | `BlockEditorModal.tsx:206`；`MathBlockView.tsx:20` | catch 裸拼 + `dangerouslySetInnerHTML` |
|
||||
|
||||
### 环境与分支脱节（本轮不做晋升，记 backlog）
|
||||
|
||||
| ID | 发现 | 证据 |
|
||||
|----|------|------|
|
||||
| ENV-MAIN-DRIFT | main 分支 goose 最高 00025，main 库 schema 52；灾备从分支重建不可复现 | `git ls-tree main`；`goose_db_version` MAX=52 |
|
||||
| ENV-TEST-DRIFT | test 分支最高 00056，test 库已 57 | 实测 |
|
||||
| DOC-SCHEMA | CURRENT 写 dev schema 56，实测 57 | health JSON |
|
||||
| GOOSE-DUP56 | dev 库 version_id=56 记账两行（id 57/58，间隔 2ms） | SQL 取证 |
|
||||
|
||||
## 严重度
|
||||
|
||||
- **critical / P0**：上表 P0-*（本轮整改）
|
||||
- **high / medium / low**：见下方「非 P0 清单」与 [long-term](../ops/long-term/2026-09-19-audit-remainder.md) 2026-09-20 增补区
|
||||
|
||||
## 关联整改
|
||||
|
||||
- Remediation: [../remediation/2026-09-20-p0-remediation-plan.md](../remediation/2026-09-20-p0-remediation-plan.md)
|
||||
- Short-term: [../ops/short-term/2026-09-20-p0-hotfixes.md](../ops/short-term/2026-09-20-p0-hotfixes.md)
|
||||
|
||||
## 证据
|
||||
|
||||
- `go vet ./...` 零告警（2026-09-20）
|
||||
- `go test -short ./...`：仅 `TestPiAgentDockerBuildContext_RunnerModulesPresent` 因外网镜像源 EOF 失败，属测试卫生
|
||||
- 三环境 health：dev/test schema **57**，main **52**；events `:8088`/`:8089`/`:8090` ok
|
||||
- 四路深潜交叉：IDOR×3、XSS、凭证、迁移空洞均被 ≥2 条路径或本机取证命中
|
||||
|
||||
## 非 P0 清单（摘要，详 long-term）
|
||||
|
||||
**后端**：XFF 限流可绕过；events `cancelFns` 只增不减；docrevision/docgov 全局锁内 DB I/O；Shutdown 5s vs 长任务；`idemLocks` 无界；SSE query 传消息；C1 缓存不失效；chat 落库非原子等。
|
||||
|
||||
**前端**：`useChatWindow` 切会话竞态；PLAN_CONFIRM 无 try/catch；turn Map 只增不减；重置密码死功能；ErrorBoundary 仅顶层；SSE `\r\n`；token localStorage + 无全局 401 登出等。
|
||||
|
||||
**基础设施**：容器 root、无资源限制；健康检查路径不一致；main events 挂 shared-net；init 三套；Dockerfile Go 1.23 基镜像；backup 无定时；main 分支对齐晋升专项。
|
||||
|
||||
## 开放问题
|
||||
|
||||
- capability 分支合入后 00054 重编号为 00058 是否与其他未合并旁支再撞号？（当前仅该分支占用 54）
|
||||
- main 分支对齐晋升时 00057 会对存量项目做不可逆改名——晋升前需预演清单
|
||||
@@ -1,234 +0,0 @@
|
||||
---
|
||||
title: "Agent 工作规范增删改审查"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
owner: Codex
|
||||
reviewed_dev_sha: a241e838150f218f3a09d3523f93291b847d45fd
|
||||
implementation_status: not_started
|
||||
---
|
||||
|
||||
# Agent 工作规范增删改审查
|
||||
|
||||
## 结论
|
||||
|
||||
现有方向合理：任务 worktree、主目录保护、串行集成、真实证据和安全清理应继续保留。当前最值得做的是**消除冲突、减少重复维护、让关键门禁可执行**，不是继续扩充一份越来越长的 AGENTS。
|
||||
|
||||
本轮建议集中为 10 组增删改与 2 项安全补充观察。它们不都是缺陷：下文区分已验证问题、流程简化建议与已有方案的实施事项。只形成审查结果，没有修改生效规则、脚本、锁、运行环境或业务代码。
|
||||
|
||||
已确定的用户选择不重新讨论：全部新增写入走 `.worktrees`；锁先交付统一入口与提交门禁防误改，OS 权限隔离后续实施；本轮是规范审查，不是实施授权。
|
||||
|
||||
## 1. 审查范围与现场
|
||||
|
||||
冻结基线为本地 `dev@a241e838`，审查在 `.worktrees/agent-policy-review` 进行。覆盖 AGENTS、PROJECT、worktree 工作规范、Cursor 四条规则、任务/收口/handoff 模板、Herdr roster，并检查相关脚本与测试入口。
|
||||
|
||||
主目录采样为干净 dev；未 fetch 或推送。本轮新分支只写审查记录和自己的 CURRENT 快照，不修改被审查规范。
|
||||
|
||||
实际测量：
|
||||
|
||||
- 基线 CURRENT 并行认领共有 **161 条**：158 条 done、2 条 in_progress、1 条 cancelled。新增本轮认领后为 162 条；不把本轮新增记录算成基线问题。
|
||||
- 基础启动链六份文件合计 **71,205 字符**，这是文件字符数，不是模型 token 数或耗时指标。
|
||||
- CURRENT 焦点有 5 项，而 AGENTS 要求 1–3 项；其中长期红线混在当前焦点中。
|
||||
- 之前的规范收口 `d5302a76` 与 `.locks` 方案 `5987bdcd` 均不是本轮基线 dev 的祖先，不能把它们当作所有 Agent 已能读取的生效规则。
|
||||
- 本轮没有运行 Go、前端、数据库或产品 PI 测试；命令问题来自源码筛选条件核查，不宣称本轮复现了产品运行故障。
|
||||
|
||||
## 2. 优先级总表
|
||||
|
||||
“先修”是工程流程优先级，不改变产品 FEATURE-MATRIX 或 production_ready。
|
||||
|
||||
| ID | 类别 | 建议动作 | 优先级 | 直接收益 |
|
||||
|---|---|---|---|---|
|
||||
| R01 | 已验证冲突 | 修改测试范围与验收模型规则 | 先修 | 消除纯文档也被要求真实 PI 的矛盾 |
|
||||
| R02 | 已验证命令问题 | 修改真实 PI 示例为准确、可核验的入口 | 先修 | 避免漏测而误以为完成全链路 |
|
||||
| R03 | 流程简化建议 | 新增任务分级，允许一个主文档承载小任务 | 第二批 | 少建重复记录，减少共享文件写入 |
|
||||
| R04 | 已验证膨胀/不一致 | 精简 CURRENT 和启动读取范围 | 第二批 | 活跃冲突更易发现，降低每轮上下文成本 |
|
||||
| R05 | 已验证状态矛盾 | 修改会话结束与任务完成定义 | 先修 | 防止为了结束会话把未完成任务写成 done |
|
||||
| R06 | 已验证过强要求 | 删除固定五层提交顺序，保留逻辑原子性 | 第二批 | 代码与测试一起可验证、可回退 |
|
||||
| R07 | 已验证引用问题 + 结构调整 | 确立规范唯一来源与生效版本 | 先修 | 避免客户端副本、草案和历史记录互相覆盖 |
|
||||
| R08 | 规范增强建议 | 新增任务授权记录与例外处理边界 | 第二批 | 授权内持续执行，超范围才停下确认 |
|
||||
| R09 | 已知方案实施事项 | 优先落实最小工具门禁 | 与先修并行规划 | 把已知运维误操作挡在执行前 |
|
||||
| R10 | 收口流程增强 | 明确清理执行者、保留原因和复查触发 | 第二批 | 已完成 worktree 不再长期无主积累 |
|
||||
|
||||
## 3. 具体增删改
|
||||
|
||||
### R01 修改：测试要求必须按变更范围生效
|
||||
|
||||
**依据**：`AGENTS.md:118`、`PROJECT.md:118` 明确纯工程规范/文档不调用产品 PI；`.cursor/rules/test-reports-standard.mdc:49,61` 仍要求报告包含全量 Go 回归，并在报告生成前做真实 PI 全链路。后者是 alwaysApply。旧收口分支虽包含相关澄清，但尚未进入本轮基线 dev。
|
||||
|
||||
**后果**：Agent 依据不同入口可能运行无关长测试、误动共享服务，或把必要测试当作可选。冲突本身应先消除，不能依靠“Agent 应该理解”。
|
||||
|
||||
**建议修改**：测试范围统一在一处定义，PROJECT 和客户端规则引用它：
|
||||
|
||||
| 变更 | 必要验证 |
|
||||
|---|---|
|
||||
| 纯规范/普通文档 | 差异、链接、状态与指令一致性 |
|
||||
| 治理脚本 | 沙盒临时仓库中的真实分支、锁、退出与拒绝路径；不以 shell 语法检查替代行为验证 |
|
||||
| Go/接口 | 对应单测、项目 Go/架构门禁，受影响 PG/鉴权负例 |
|
||||
| 前端 | 对应测试和构建；受影响交互用真实浏览器 |
|
||||
| 迁移/运行配置 | 独立环境升级、兼容性、回退/前滚条件及就绪验证 |
|
||||
| 产品 Agent/工作流 | 受影响真实产品 PI 链路；不得以 stub/SKIP 替代 |
|
||||
|
||||
固定七段报告模板改为“完整报告模板”，小型文档/脚本验证可用精简报告或任务内验证节；必须保留实际命令、结果、提交与适用范围。不要删除真实性要求，也不允许把未运行记作 PASS。
|
||||
|
||||
模型要求按目标环境的已批准配置核验并记录实际值。`PROJECT.md:118` 的固定 M2.7-highspeed 不能不分环境套用：当前 dev Compose 默认 M2.7-highspeed，而 test/main Compose 默认 M3。这里是配置源码差异，未检查运行中的秘密配置；建议保留环境策略，禁止为“满足文档”自行切换模型。
|
||||
|
||||
### R02 修改：真实 PI 命令要准确选择测试并证明没有跳过
|
||||
|
||||
**依据**：`PROJECT.md:91–92` 使用 `RUN_PI_E2E=1 ... go test ./... -run 'PI'`。测试名 `TestPiAgent_FullLifecycle_MultiRole_RealWorld_E2E`（`internal/server/piagent_e2e_test.go:66`）及 `TestWorkflowGovernance_PiAgent_PG_*`（同模块的 `workflow_governance_piagent_pg_test.go:264,278,293`）不匹配大小写敏感的 `PI`。
|
||||
|
||||
**后果**：命令执行范围与“全链路”的名称不一致；配置缺失还可能让数据库用例跳过。退出码 0 不能单独证明验收完成。
|
||||
|
||||
**建议修改**：优先引用已有 `scripts/run-nightly-real-pi.sh` 作为明确基线入口，写清独立 TEST_DATABASE_URL、Runner 认证、KB/运行环境要求。该脚本当前仅选 U8 和 FullNoneMixedChain 两类测试，**不能把它表述为覆盖全部工作流**；任务按变更范围追加精确测试名与浏览器验收。增加 expected-tests 与实际执行/SKIP 对照，保存最终提交、配置与证据。
|
||||
|
||||
不得在文档中填写真实凭证，也不运行测试来试探生产数据。
|
||||
|
||||
### R03 新增：任务分级；删除小任务必须重复建多份记录的要求
|
||||
|
||||
**依据**：`AGENTS.md:12,37,41–44` 要求任何任务落盘、任务文、研究/审计产物、验收及交接；没有最小产物集或合并记录的规则。
|
||||
|
||||
**建议**：保留“需要审计的工作必须有持久证据”，明确三档：
|
||||
|
||||
- **信息答复**：解释已有结果、查询简单状态，且不产生新决策、持久成果、仓库写入或运行副作用，可直接答复；不为一次答复单独开 worktree。若要写入任何成果，仍进入任务 worktree。
|
||||
- **单一小任务/有价值的只读审查**：一个任务文或专用 audit/research 主文档可同时承载范围、结论、验证、状态和交接；不强制再复制同一内容到另外三份文档。
|
||||
- **跨模块、多阶段、数据/部署任务**：完整 task、必要 plan、验证报告、handoff；仅在信息确实独立时拆文件，互相链接而不复制全文。
|
||||
|
||||
本次这样的实质规范审查仍须落盘，不能以“只读”免除证据。将相关追问、修正与收口归入原 task_id；只读子审查使用父任务的范围和记录，不为每个 reviewer 再开业务任务链。无关新增任务才从 dev 建新分支。
|
||||
|
||||
这项改变需要审核采纳；本轮仍遵守现有落盘规则，没有提前使用豁免。
|
||||
|
||||
### R04 修改：CURRENT 只承载活跃协调，历史留索引
|
||||
|
||||
**依据**：CURRENT 161 条认领中 158 条已完成；`AGENTS.md:132` 要求 1–3 焦点，当前正文有 5 项。
|
||||
|
||||
**建议删除/迁移**：从 CURRENT 活跃表移出已完成/取消且没有后续阻塞的行，历史 owner、branch、worktree、证据在归档任务/历史索引保留。将长期红线独立为受控约束区或链接；它不是每天反复排序的焦点。
|
||||
|
||||
**建议保留**：正在进行、阻塞、等待集成及仍需清理的事项。cleanup_pending 是清理/操作阶段，不新增为 task.status 的第六种状态；一行可写任务 done、cleanup pending，并给 owner、原因和下次检查条件。
|
||||
|
||||
**启动读取修改**：每会话先读短核心规则、项目入口、活跃状态摘要；编码前按范围补读相关模块标准、相关 FEATURE-MATRIX 行、任务/方案及操作规程。发布才读完整发布门禁。不要通过摘要跳过硬红线，也不要要求每次解释一个已知结果都重读全部历史。
|
||||
|
||||
模块开发任务应有明确条件指针指向已有 `.doc/system-design/2026-09-20-module-development-standards.md`，复用现有接口/事件/表写者规则，不新造一套编码规范。
|
||||
|
||||
### R05 修改：会话结束、任务完成、合入与清理分别判定
|
||||
|
||||
**依据**：收口模板第 3 行适用于“任务完成或切换 Agent”，第 22 行却无条件要求 `status=done`；AGENTS 同时允许 blocked/cancelled。任务模板已有 deployment/cleanup 字段，但缺少明确的结果判定与集成/同步状态。
|
||||
|
||||
**建议替换收口条件**：
|
||||
|
||||
> 会话结束不等于任务完成。根据实际情况保留 in_progress、blocked、cancelled 或 done；只有任务范围内的验收条件满足才能 done。换 Agent 必须记录剩余工作及接管条件。只有终态任务才归档；不得为了归档改成 done。
|
||||
|
||||
为任务记录补充按需字段：`review_state`、`integration_state`、`deployment`、`cleanup`、`remote_sync`。例如“方案研究 done、review pending、未合入、deployment not_required”是合法状态；“代码已合入、部署 failed”不能报交付完成。字段由工具生成优先，避免人工重复维护多张表。
|
||||
|
||||
研究/审查的验收是有据可审的产物，不要求把未获实施授权的方案部署到 dev。实现任务的 done 则按其获授权交付范围判定。收口报告始终区分本地提交、dev 合入、实际运行版本和远端状态。
|
||||
|
||||
### R06 删除：固定按数据库、服务、API、测试、文档分层提交的硬性顺序
|
||||
|
||||
**依据**：`.cursor/rules/git-workflow-and-environments.mdc:33–38` 规定“一个任务必须”按五类依次提交；AGENTS 的原子提交目标是一个逻辑变更一批。
|
||||
|
||||
**后果**：小修复也被机械拆分，代码与对应测试分离；一些提交无法独立构建/验证，回退时还可能留下半套契约。
|
||||
|
||||
**建议替换**：
|
||||
|
||||
> 每个提交围绕一个可解释、可验证、可回退的逻辑变更；实现与其回归测试可同批。迁移、兼容阶段、配置或文档只有在独立审查/回退有价值时拆分，不要求每项任务凑齐固定提交层次。
|
||||
|
||||
保留 Conventional Commits、明确文件范围、渐进式交付和独立 worktree；不以“原子”为名把无关改动揉成一批。
|
||||
|
||||
### R07 修改：规范来源、生效状态与客户端薄入口
|
||||
|
||||
**已验证的小错误**：`.cursor/rules/git-secrets-autonomy.mdc:2,8` 把 Secrets 指向 AGENTS §8，实际在 §9。AGENTS 开头称可整文件复制到任意项目，但正文包含本仓库日期路径、脚本和 Herdr 约定；应改为“可复用基线，项目路径/流程需调整”。
|
||||
|
||||
**建议新增规范生命周期**：每项规则记录 proposed/approved/active/deprecated 的规则状态、适用范围、生效提交与 owner；工具能力另记 manual/enforced。这里是规则生命周期，不复用任务 status。
|
||||
|
||||
外层系统约束和当前用户授权仍有效；项目内部规则冲突时有明确处理：AGENTS 保存通用硬边界，PROJECT 定义其授权范围内的项目细则，专门 runbook 负责操作流程；客户端入口只引用同一来源，不复制一套近似规则。草案、旧审计和历史报告属于证据，不能自行覆盖生效规则；较新的日期不等于已生效。
|
||||
|
||||
此前收口和锁方案未进入当前 dev，说明“已经写好/提交”与“已被所有新任务读取”必须分开。旧任务启动时记录 policy revision，集成前重读当前 dev 的相关生效规则；期间发生变化时做差异检查，不默默套旧规则，也不突然按未来未实施机制阻塞旧任务。
|
||||
|
||||
删除 PROJECT 中重复的“当前已无 blocker”等长期硬编码断言，改为引用有日期/制品身份的权威门禁结果。模型、schema、角色可用性等动态值记录在环境/执行收据中；不要在多个入口重复写一份可能过期的“当前值”。
|
||||
|
||||
### R08 新增：任务授权记录与例外边界
|
||||
|
||||
这是一项规范增强建议，不是声称现有 Agent 已越权。现有手册限制自动审批扩权、push 和破坏性操作，但任务模板只有范围/非目标，没有统一记录“这次到底获准做到哪一步”。
|
||||
|
||||
建议任务创建时记录：任务类型（研究/实现/运维）、用户目标、允许写路径、可执行环境、交付终点及明确禁止项。已授权范围内自主持续执行，不在每个 Git/测试步骤重复确认；分析和方案请求默认不包含业务实施。
|
||||
|
||||
只有扩大业务范围、增加外部写入、操作未授权环境或破坏性恢复等才重新确认。push 仍遵守明确授权规则；凭证存在不代表允许推送。合理默认写进任务模板，不用每次都问用户一张权限问卷。
|
||||
|
||||
紧急/迁移例外需记录 owner、原因、范围、期限/退出条件和恢复动作；例外仅覆盖明确条款。`AGENTS.md:29` 的紧急热修免启动阅读不能被解释为允许主目录直接开发、删库或取消验收。
|
||||
|
||||
### R09 落实：先做最小执行门禁，不再只增加禁止句
|
||||
|
||||
这是上一治理/锁方案已承认的工程任务，不作为“新发现的缺失要求”重复计数。
|
||||
|
||||
**已有证据**：AGENTS 已禁用旧 helper 的 create/remove；源码仍包含省略 dev 起点和强制删除。env-service 的根目录来自脚本所在树，缺少执行目录/锁守卫。CURRENT 第 11 行及关联 MinerU 报告已记录一次 worktree rebuild 引起数据挂载漂移，说明风险并非仅理论；本轮未重演该事故。
|
||||
|
||||
**建议实施顺序**：
|
||||
|
||||
1. 修 worktree create/remove 的明确基线、主仓定位和安全删除。
|
||||
2. 给共享服务写操作加主目录/dev/操作身份/持锁前置检查，明确 status 等只读入口；构建必须校验真实源码与申报 SHA。
|
||||
3. 为 CURRENT/MATRIX 提供短锁、增量更新、版本检查，接入已设计 `.locks` 流程；旧锁兼容迁移后才换权威位置。
|
||||
4. Git 提交/集成门禁拒绝超范围文件、混入 `.env`/运行产物和错误主干写入。门禁真实负例验收后再记录 enforced。
|
||||
|
||||
保持用户确认的 L1 目标，不提前搭建跨机平台或要求 OS 隔离才能使用。代码文件锁、全量资源队列和额外 UI 按已有阶段与实际冲突扩展，优先把当前两个共享文档和 dev 操作做可靠。
|
||||
|
||||
### R10 新增：清理负责人和完成后的再检查机制
|
||||
|
||||
现有安全清理条件应保留，不放宽“不强删、不覆盖”的红线。需要补的是谁在 Agent 退出之后真正执行清理，以及什么时候重试。
|
||||
|
||||
操作规范要求无 Agent/进程 cwd 使用才能移除 worktree；长驻客户端即使完成任务也可能仍占 cwd。任务模板允许 retained-with-reason，但没有下一次检查条件。建议由独立集成/维护执行者在 owner 已退出后检查并清理，记录 `cleanup_owner`、保留原因、证据位置和触发条件；遗留目录分为活跃、保护、待审核、未合入和可清理，不按年龄批量删除。
|
||||
|
||||
已合入任务的依赖缓存与唯一截图/日志区别处理：可再生缓存明确登记，唯一证据先保存再移除；只保存路径而不保存文件不是证据归档。清理失败不影响已经通过的业务交付事实，但要保持可追踪的 cleanup pending。
|
||||
|
||||
## 4. 两项安全补充观察（非本轮阻塞项）
|
||||
|
||||
- **材料不能授予权限**：日志、网页、测试输出、引用文本、Agent 产物可能含命令或“用户已授权”字样，应作为待核实内容。handoff 的授权声明回链到可核实的用户目标/委派范围，不仅凭文档自述执行推送、清理或外部写入。已有自动审批不扩权规则继续保留；这项建议补充来源辨别，不要求 L2 现在落地。
|
||||
- **真实证据允许最小化与脱敏**：测试报告可以保存真实执行中足够判定的片段，说明脱敏范围；不要求提交原始完整日志、个人信息、业务正文或截图中的秘密。现有凭证禁入与真实用户数据不复制要求继续有效。真实性约束来源与结论，不能误解成“未经处理的所有材料都要入 Git”。
|
||||
|
||||
## 5. 推荐的规范组织
|
||||
|
||||
不建议再并列增加一套“总规范 v2”。保留现有路径并收敛职责：
|
||||
|
||||
| 位置 | 负责内容 | 移出/减少 |
|
||||
|---|---|---|
|
||||
| AGENTS | 最小安全红线、任务入口、权限/状态原则、操作指针 | 环境动态值、长命令、历史事件、重复模板索引 |
|
||||
| PROJECT | 仓库地图、目标环境、测试入口与模块标准指针 | 重复通用规则、过期发布结论 |
|
||||
| worktree runbook | 创建、同步、候选、部署、失败与清理 | 已结束迁移的具体临时目录案例，移入历史交接 |
|
||||
| 锁管理 runbook（落地后） | 唯一入口、状态、等待、恢复与兼容版本 | 让 Agent 手动拼锁协议的日常操作 |
|
||||
| CURRENT | 活跃任务、当前槽位、1–3 焦点、必要约束链接 | 大量 done 历史行与长复盘 |
|
||||
| FEATURE-MATRIX | 能力声明范围、证据、剩余条件 | 逐次操作流水、重复环境快照 |
|
||||
| 客户端入口 | 明确引用上述来源 | 复制并稍微改写的第二套规则 |
|
||||
| 任务/审查主文档 | 单项工作的范围、决定、证据和交接 | 对相同内容的无意义多文件复制 |
|
||||
|
||||
## 6. 改动顺序与验收
|
||||
|
||||
**第一批：消除矛盾。** R01、R02、R05、R07 的明确错误先修。检查从所有客户端入口读取后，纯文档、业务修复、暂停交接、取消任务、真实 PI 验收五种场景都得到一致决策。
|
||||
|
||||
**第二批：减少流程负担。** 采纳 R03/R04/R06/R08/R10 后更新模板与薄入口；历史只迁移、不删除。验证信息问答不触发无意义写入，实质审计有唯一主产物，代码与测试能形成完整逻辑提交，未完成任务不会被强制 done。
|
||||
|
||||
**第三批：工具实现。** R09 与既有 `.locks` 分阶段方案合并为一个实施队列，不重复造项目。用两个并行任务、锁冲突、旧版本共享文档、错误工作区部署、异常退出和清理拒绝的真实证据验收。当前 user-approved 的 L1 防误改边界不变。
|
||||
|
||||
规范检查可以自动化为轻量 `doctor/lint`：本地链接、必需字段/状态、过期 waiver、活跃认领冲突、测试入口存在、脚本能力版本与规范声明对齐。没有明确规则契约的模糊 prose lint 不作硬失败，也不为文案偏好构造复杂测试。
|
||||
|
||||
## 7. 审查覆盖与可信度
|
||||
|
||||
使用 ce-doc-review 非交互只读流程，审查依据为上述实际文件及脚本，而非仅凭历史记忆。
|
||||
|
||||
| 审查视角 | 结果 | 本报告处理 |
|
||||
|---|---|---|
|
||||
| 一致性（独立上下文） | 3 项 | 复用声明/引用合入 R07，焦点上限合入 R04 |
|
||||
| 可执行性（独立上下文） | 1 项 | PI 测试筛选问题合入 R02，主审已核对源码 |
|
||||
| 范围/减负（独立上下文） | 3 项 | 合入 R03/R04；保留实质审计必须落盘，收窄纯只读豁免 |
|
||||
| 安全（独立上下文） | 2 项观察，置信锚 50 | 仅列为 §4 补充观察，不当作已证实漏洞 |
|
||||
| 反例审查（独立上下文） | 0 项新增缺陷 | 候选 SHA、失败恢复、累计部署差异等已有引用约束，未重复提出 |
|
||||
| 主审当前源核查 | 测试范围冲突、状态模板、提交顺序、动态配置与工具事实 | 补充 R01/R05/R06 等；明确区分改进建议与已知实施项 |
|
||||
|
||||
外部第三方 CLI 跨模型复核未执行：本轮未获得向其他外部服务发送仓库文档的显式授权；未以此阻塞会话内独立视角审查。未更改技能或项目配置来伪造关闭该步骤。
|
||||
|
||||
未采纳的建议形态：不把纯只读豁免扩大到有持久价值的审计；不把 cleanup_pending 塞进既有任务 status；不要求当前实现 OS 级权限隔离；不因为当前 helper 明确标为未修复，就重复说规范已承诺了不存在的能力。
|
||||
|
||||
**已应用规范修正：0。** 上述均是待审核建议。本轮只写审查产物与任务记录，未升级 FEATURE-MATRIX、未改 production_ready、未运行产品测试、未合入 dev 或 push。
|
||||
|
||||
## 8. 相关资料
|
||||
|
||||
- [当前工作手册](../../AGENTS.md)
|
||||
- [项目入口](../../PROJECT.md)
|
||||
- [已采纳工作方式](../ops/2026-09-21-agent-worktree-workflow.md)
|
||||
- [既有治理方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)
|
||||
- `.locks` 补充方案：目前在 `feature/agent-lock-coordination-plan@5987bdcd` 的 `.doc/remediation/2026-09-21-agent-lock-coordination-plan.md`，不在本轮 dev 基线；后续合入时再建立普通相对链接。
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
title: "文档存储 CoW（写时复制）现状审计"
|
||||
status: done
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
severity: low
|
||||
---
|
||||
|
||||
# 文档存储 CoW（写时复制）现状审计
|
||||
|
||||
## 背景
|
||||
|
||||
用户诉求：上传文档要「几个人传同一份只存一份」，涉及可编辑文档时「考虑 CoW，写入时复制」。本审计确认系统当前的去重与写时复制实现状态，并明确本次收口补齐了什么。
|
||||
|
||||
## 现状分析
|
||||
|
||||
系统存在两套内容存储，均已采用内容寻址（Content-Addressed Storage, CAS），天然满足去重与 CoW 语义：
|
||||
|
||||
### 1. 二进制资产：`internal/storage/cas.go`
|
||||
|
||||
- 物理对象表 `storage_blobs` 以 `sha256` 为主键，`ref_count` 记录引用数。
|
||||
- 上传命中相同 sha 时（[cas.go](../../internal/storage/cas.go) `storeFileDB`）**不写第二份物理文件**，仅 `ref_count + 1`，并新建一条 `file_references` 逻辑引用。→ 满足「多人传同一文档只存一份」。
|
||||
- 文件路径 `blobs/<xx>/<yy>/<sha>.bin` 由内容 hash 唯一决定；`StoreFile` 对已存在 blob **只读不覆写**（命中去重分支直接返回）。内容变化 → hash 变化 → 新路径新文件。→ 即 CoW：修改等价于写入新对象，旧对象不被就地改写。
|
||||
|
||||
### 2. 可编辑文档正文：`internal/docrevision/pg_store.go`
|
||||
|
||||
- `document_content_blobs` 以 `content_sha256` 为键，`ensureBlobTX` 使用 `INSERT ... ON CONFLICT DO NOTHING`（[pg_store.go:309](../../internal/docrevision/pg_store.go)）。
|
||||
- 每次编辑保存生成新 `document_snapshots`，指向新的 `content_sha256`；未变化的正文块复用同一 blob 行。→ 编辑保存不会复制未改动内容，写入时才产生新 blob。→ 满足「可编辑文档 CoW」。
|
||||
|
||||
## 结论
|
||||
|
||||
- **去重**：物理层早已实现（sha256 + ref_count）；本次补齐的是**逻辑提示**——把 `FileReference.IsDeduplicated` 透出到上传/列表 API 的 `deduplicated` 字段，并在前端附件卡片与文档预览面板展示「重复·已复用」，让"只存一份"对用户可见。跨项目/同项目的逻辑引用记录保留（权限与审计需要），不做合并（已与用户确认方案：物理一份 + 提示）。
|
||||
- **CoW**：语义已是事实实现，但**缺防回归守卫**。本次新增 `TestCAS_ImmutabilityCoWContract`（[cas_test.go](../../internal/storage/cas_test.go)）固化契约：① 相同内容重复写入 → 物理 blob 数不变、字节不变；② 内容变化写入 → 新 blob、旧 blob 不被覆写、历史引用仍读原始字节。未来任何"就地改写 blob"的实现都会在测试期失败。
|
||||
|
||||
## 严重度
|
||||
|
||||
`low` —— 现状正确，本次为可见性增强 + 契约固化，无缺陷修复。
|
||||
|
||||
## 关联整改
|
||||
|
||||
- 任务：[2026-09-21-upload-parse-ux-dedup.md](../ops/short-term/2026-09-21-upload-parse-ux-dedup.md)
|
||||
- 验收报告：[2026-09-21-upload-parse-ux-dedup-test-report.md](../test-reports/2026-09-21-upload-parse-ux-dedup-test-report.md)
|
||||
|
||||
## 开放问题
|
||||
|
||||
- `storage_blobs.ref_count` 目前只增不减；引用删除（若未来支持资产删除）需配套 decrement 与 blob 物理回收，属后续独立任务，不在本次范围。
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: "pi-native 对比未过 P95 门槛"
|
||||
status: planned
|
||||
created: 2026-09-21
|
||||
updated: 2026-09-21
|
||||
severity: medium
|
||||
---
|
||||
|
||||
# pi-native 对比未过 P95 门槛
|
||||
|
||||
## 现象
|
||||
|
||||
真实 MiniMax-M2.7-highspeed 双后端对比中，`pi-native` 六例全部写出目标文件，容器 `pi-agent` 只有两例文档任务成功。按成功样本计算的 P95 仍是 `pi-native` 16.616s、容器 6.926s，比值为 2.40，超过 1.3 倍替换门槛。因此 dev 默认后端保持 `pi-agent`。
|
||||
|
||||
## 根因分析
|
||||
|
||||
- 时延样本只统计成功且无 P0 的用例。容器 `reasoning` 画像使用 `--no-tools`，不会把助手正文落成目标文件，四例返回 `MISSING_TARGET`，不进入 P95。容器 P95 只由两例较快的文档任务构成。
|
||||
- `pi-native` 的 P95 落在 `doc-outline`（16.616s）。同一提示在容器上是 6.926s。文档任务本身慢于 1.3 倍，不是分位数算法造成的。
|
||||
- 第一轮对比把分位索引截断成 0，两例成功时取了更快的那例，已作废。本结论使用 nearest-rank（`ceil`）后的第二轮日志。
|
||||
|
||||
## 严重度
|
||||
|
||||
`medium`。运行时可以继续在分支上迭代，当前默认链路未切换，容器后端仍可回退。
|
||||
|
||||
## 关联整改
|
||||
|
||||
- 任务：`.doc/ops/short-term/2026-09-21-go-agentx-runtime.md`
|
||||
- 报告：`.doc/test-reports/2026-09-21-go-agentx-runtime-test-report.md`
|
||||
- 后续：缩短 `pi-native` 文档轮次时延，或把门槛改成按同一成功用例配对比较后重新实测。未重新通过前不改 `AGENT_BACKEND`。
|
||||
|
||||
## 证据
|
||||
|
||||
- `.doc/test-reports/assets/go-agentx-runtime/ab-live.txt`
|
||||
- `.doc/test-reports/assets/go-agentx-runtime/ab-live-round1.txt`（作废的截断分位）
|
||||
|
||||
## 开放问题
|
||||
|
||||
- 容器结果不回传 token，本轮容器用量为 0，无法比较 token。
|
||||
- `reasoning` 画像的成功定义是否应要求容器也把正文写入目标文件。当前判定仍按两边各自的 `Result.Success` 与目标文件是否出现。
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
title: "当前系统模块解耦现状审查"
|
||||
type: docs
|
||||
date: 2026-09-22
|
||||
source_sha: d034aa00e5785f51234b484f9dca6bf4fb037660
|
||||
task_id: modular-contract-standard-2026-09-22
|
||||
---
|
||||
|
||||
# 当前系统模块解耦现状审查
|
||||
|
||||
## 结论与范围
|
||||
|
||||
当前系统属于**已有实质模块化基础，但契约一致性、数据所有权与运行隔离尚未闭合的模块化单体**。不是只有文件夹拆分：已有应用用例、共享事务、PostgreSQL outbox/delivery/inbox、独立 events 进程、PI Runner HTTP typed-result 边界。
|
||||
|
||||
下一步收益最大的工作是统一业务入口、修正事件顺序契约、补运行时校验和资源预算。把现有相互依赖的实现全部包装为 HTTP 服务，会保留语义耦合并引入跨进程失败窗口。
|
||||
|
||||
本报告针对固定源码 SHA，只读检查 Go/React、架构配置、迁移和部署定义。**未检查当前实际镜像/进程/数据库积压，未运行 Go/PG/PI/浏览器或故障注入测试。** 下文“实现存在”是源码证据；“可能造成”是风险推导；不宣称现网事故已复现，也不改变 FEATURE-MATRIX 或发布门禁。
|
||||
|
||||
关联：[通用规范](../system-design/2026-09-22-generic-module-contract-standard.md)、[采用规划](../remediation/2026-09-22-modular-platform-adoption-plan.md)、[任务与验证](../ops/short-term/2026-09-22-modular-contract-standard.md)。
|
||||
|
||||
## 分维度判断
|
||||
|
||||
| 维度 | 已有基础 | 当前局限 | 判断 |
|
||||
|---|---|---|---|
|
||||
| 模块职责 | domain/app/server 分层，组合根 | server 认识大量实现，跨包类型泄漏 | 部分解耦 |
|
||||
| 业务入口 | docflow/stageflow/chatflow 用例 | 对话和 HTTP 同一动作存在旁路 | 需优先收敛 |
|
||||
| 数据边界 | 表 owner 清单与 UoW | 5 项 SQL 写例外、16 项路径例外 | 明确但未闭合 |
|
||||
| 事件通信 | 可靠 PG 投递与独立进程 | 顺序规则与 ADR 冲突，校验不完整 | 机制具备，语义有缺口 |
|
||||
| 并发与幂等 | claim、lease、token、DB 收据 | 慢消费者共享循环，同 ID 异载荷不校验 | 部分保证 |
|
||||
| 跨进程边界 | Web/server、PI Runner、events | 业务模块大多仍共享 server 进程/资源 | 不能宣称全模块故障隔离 |
|
||||
| 前端功能 | API/hooks 拆分 | 根状态和 setter 跨功能共享 | 文件组织优于状态边界 |
|
||||
| 工程约束 | arch-check 与契约 registry | 静态覆盖有限，不证明运行隔离 | 有工具，须明确盲区 |
|
||||
|
||||
不提供无权重依据的“解耦百分比”。以下发现按对数据与行为的实际影响排序，而非按文件大小排序。
|
||||
|
||||
---
|
||||
|
||||
## A1. 事件领取规则与已接受的顺序契约相冲突
|
||||
|
||||
**高优先级源码问题。** ADR 规定允许首个高领域版本 bootstrap，禁止把 MemoryBus 的连续版本等待搬到 PG dispatcher：`.doc/adr/2026-09-15-event-consumer-checkpoint.md:12-23`。
|
||||
|
||||
当前 `internal/events/dispatcher.go:39-46,75-84` 采用 `version <= checkpoint + 1`；无 checkpoint 时只接纳版本 0/1。生产者 `internal/app/docflow/commands.go:182-185` 使用 document record ID，`:211-214` 使用 candidate ID，`:162-165` 使用文档账本版本。这些不是从 1 开始连续的事件序号。
|
||||
|
||||
因此在“无 checkpoint、第一条版本为 42”这一明确条件下，该事件按 SQL 不能被领取。是否已有这种实际积压未查数据库，不能报成现网观测。
|
||||
|
||||
现有 `internal/events/pg_test.go:18-28` 固化同样 gap 规则；`dispatcher_pg_test.go:105-109` 使用 v1/v2，不能覆盖稀疏首事件。
|
||||
|
||||
**建议验收**：真实 PG 下测试首次 v42、v42→v47、部分事件订阅、毒消息隔离；按既有 ADR 恢复 bootstrap，或经明确新 ADR 引入独立事件序列及迁移。通用规范对应 MCS-15。
|
||||
|
||||
## A2. 同一批准动作存在 HTTP 与对话入口分叉
|
||||
|
||||
**高优先级待验证风险。** HTTP `internal/server/handlers.go:793-808` 调用 `docflow.Commands.Approve`，后者在 `internal/app/docflow/commands.go:173-188` 执行 UoW 与 EventApproved。
|
||||
|
||||
对话 `internal/chat/action_executor.go:68-76` 直接调用 GovernanceEngine.ApproverApprove；`internal/app/app.go:294-307` 已不再注册旧通知/批准 hook，`internal/docgov/engine.go:957-960` 的直接路径仅尝试旧 hook。
|
||||
|
||||
源码证明入口路径不同，存在绕过 durable workflow_advance/notify 的风险；本次未执行真实对话批准，不能把完整用户后果记为已复现。
|
||||
|
||||
**建议验收**：同一授权场景分别从 HTTP、对话、后台任务触发，比较授权拒绝、状态提交、事件、工作流推进与通知，所有入口汇入同一用例。通用规范对应 MCS-04。
|
||||
|
||||
## A3. 契约登记尚未成为完整运行时校验
|
||||
|
||||
`internal/events/registry.go:28-52` 登记 producer、consumer、schema、PayloadFields；`:75-91` 主要检查启用与消费者。
|
||||
|
||||
`internal/events/envelope.go:65-85` 检查基础字段、schema、digest/scope，但不按事件逐项校验 producer allowlist、JSON 必填/类型/额外字段。`internal/events/pg.go:32-47` 依赖此验证。`inventory.go:29-63` 也未完成 payload 结构检查。
|
||||
|
||||
实际 `internal/app/docflow/commands.go:279` 的 Producer 为 `docflow`，registry 示例为 `app/docflow`（`registry.go:42-46`），当前路径不会因此拒绝。消费 hydration `dispatcher.go:204-224` 与 handler 调用 `worker.go:252` 也不能证明所有入口统一重新校验。
|
||||
|
||||
**建议验收**：未知事件/schema、伪造 producer、缺必填、异类型、超大 payload、digest/tenant/environment 不符均有发布和消费负例。通用规范对应 MCS-08/09/18/21。
|
||||
|
||||
## A4. 消费者逻辑独立，但资源执行仍串行共享
|
||||
|
||||
`internal/events/worker.go:99-113` 逐一 RunOnce 各消费者；`:137-147` 一批先 claim 再逐个 handle。心跳直到该条 handle 才启动（`:208-234`）。
|
||||
|
||||
慢消费者会延迟同 worker 的其他消费者；预取队尾还可能在开始处理前耗掉 lease。增加副本能缓解吞吐，不证明消费者有独立预算和公平性。当前可隔离永久错误，不等于慢任务也隔离。
|
||||
|
||||
**建议验收**：阻塞一个消费者、保持另一个持续输入，后者满足自己的延迟预算；批量排队超过租期时不允许并发重复副作用。先按空闲槽 claim，并配置每消费者超时、并发、池配额；高风险任务再进程隔离。对应 MCS-14/17。
|
||||
|
||||
## A5. 去重与健康检查不能被扩大解释
|
||||
|
||||
`internal/events/pg.go:43` 对相同 event_id 使用 DO NOTHING，未比较已有 payload digest。因此“重复 ID 被忽略”并不保证“同键异载荷会冲突”。
|
||||
|
||||
`cmd/events/main.go:91-115` 的 health、ready、live 分别关注进程、DB/schema/注册条件、调度心跳；`worker.go:109-112` 在处理前 Touch 且忽略 RunOnce 返回错误。Compose healthcheck 使用 /health（`docker-compose.dev.yml:170-175`）。
|
||||
|
||||
**建议验收**：同 ID 同内容返回既有结果、不同内容冲突；依赖持续失败时最老消息年龄和分消费者失败数告警，不能依靠健康探针证明业务前进。对应 MCS-13/19/20。
|
||||
|
||||
---
|
||||
|
||||
## B1. 组合根、契约类型与实现仍相互渗透
|
||||
|
||||
优点：`internal/app/app.go:96` 集中装配，`internal/server/server.go:87` 接收 runtime。限制：`server.go:40-84` 持有领域具体服务、pool、上下文等，`:123-132` 还回填 Runtime 并初始化执行器。HTTP 适配器获得整个 Runtime，难以维持最小依赖。
|
||||
|
||||
`internal/app/stageflow/usecase.go:10-37` 是窄端口且未配置时 fail closed，但 `types.go:3-15` alias 到 bizdev 模型。`internal/app/chatflow/ports.go:75-106` 返回 ctxmgr/coordinator/projectinstance 具体类型。接口改变了调用位置，仍未彻底隐藏内部模型。
|
||||
|
||||
本次 server 生产 SQL 搜索未发现真实业务 SQL，**不能把持有 pool 等同于已经直接越权写表**。改造重点是缩小可用能力与未来变更影响，不虚构违规。
|
||||
|
||||
## B2. 单写者有登记，仍有明确例外
|
||||
|
||||
`.doc/system-design/module-boundaries.yaml:276-374` 登记表 owner，`:471-511` 登记 5 项 SQL 例外。
|
||||
|
||||
源码确认：`internal/docrevision/pg_store.go:456-477` 更新 freeform_documents/document_records；`internal/docduty/store.go:144`、`revoke.go:154` 修改 document_records；`internal/projectinstance/store.go:920` 更新 task_runs。
|
||||
|
||||
建议通过 owner repository/用例端口逐项归还写权，保留必需事务边界。不得为了删除一个 import，把同一 SQL 移到万能公共 repository。
|
||||
|
||||
## B3. 共享事务值得保留，不能随意替换为网络调用
|
||||
|
||||
`internal/app/docflow/commands.go:88-112` 使用 UoW 与 owner GetForUpdate；`internal/docrevision/pg_store.go:482-491` 加入同一事务；`internal/app/uow/pg_uow.go:52-80,95-124` 提供有界事务重试、锁等待和提交。
|
||||
|
||||
`internal/app/app.go:269-275` 接入 events.PGSink，`internal/events/pg.go:17-58` 拒绝无 UoW 发布并同事务创建 envelope/delivery。这是实质强一致性能力。若以后拆进程，必须重新定义跨域中间态、补偿和对账，不能用分布式锁替代事务。
|
||||
|
||||
## B4. 文件与前端状态也构成模块间隐式协议
|
||||
|
||||
文件证据：`internal/coordinator/context.go:456-459` 读取 output.md；`engine.go:691-701,895,1051` 读写/拼接共享产物路径；`internal/docgov/lease.go:415-416` 写 projection 文件。文件 owner、不可变引用、版本与发布原子性应与数据库同样治理。
|
||||
|
||||
前端证据：`web/src/App.tsx:130-170,1163-1204,1367-1406` 将消息、交付物、缓存及 setter 传给多个功能 hooks；`useSendMessage.ts:85-121` 可修改多个域状态。建议 owner 管理状态、对外命令/查询/事件；浏览器内无需强制 HTTP。
|
||||
|
||||
`web/src/api/authHeaders.ts:27-44` 已有认证辅助，但 chatStream、taskRuns、docgov 等仍各自 fetch。统一 client 应处理通用超时、错误、取消与身份，功能 DTO 继续分域。
|
||||
|
||||
## B5. 静态架构检查有价值，但证明范围有限
|
||||
|
||||
`internal/archtest/scan.go:38-70` 默认只扫 internal 生产 Go；`:169-205` 检查 import allowlist 和登记表的 SQL 字符串。它不涵盖前端、默认 cmd 范围、动态 SQL 完整语义、实际权限、兼容性和资源隔离。
|
||||
|
||||
`scan.go:18,392-410` 的事件匹配范围主要为 document.* / intent.plan.* 和特定调用模式，不能根据 YAML 中存在 taskrun/fav 就假定每条协议都被检查。
|
||||
|
||||
`module-boundaries.yaml:182-225` 仍允许 server 依赖大量领域；`:641-651` 登记 sql_write=5、path=16 基线。**这是读取到的配置，不是本次 arch-check 执行结果。**
|
||||
|
||||
---
|
||||
|
||||
## 可保留的隔离与演进能力
|
||||
|
||||
- 独立 worker：`cmd/events/main.go:68-89,127-130` 注册 notify/advance/projection，FAV 明确不注册；Compose 已有 events 服务。历史“没有独立 worker”的判断已过时。
|
||||
- 领取与确认：`dispatcher.go:49-97,163-200,227-259` 有原子 claim、owner/token、attempt、inbox/checkpoint；旧 ClaimIDs 已禁用。
|
||||
- DB 效果原子性：`worker.go:247-275` 的 handler、fenced ack、commit 同事务；仅适用于参与同一 DB 事务的效果，不能扩展为任意外部 IO。
|
||||
- 消费者实现：`internal/app/docproject/consumer.go:73-94` 使用事件回执与 no-replace；`docadvance/consumer.go:80-104` 使用同事务推进与通知。
|
||||
- 冻结执行输入：`internal/workflow/runtime/orchestrator.go:27-41,69-85` 从冻结实例取职责，缺失时拒绝，可泛化为任务绑定配置/契约版本。
|
||||
- PI Runner：`internal/agent/piagent.go:145-194` 有 HTTP/Bearer、超时、run_id、typed result 和大小限制；`remote_result.go:63-79` 对存在但非法 typed 字段 fail closed。
|
||||
|
||||
## 测试证据边界
|
||||
|
||||
以下是已有测试定义，不是本次 PASS：
|
||||
|
||||
| 路径 | 已有测试意图 | 本次状态 |
|
||||
|---|---|---|
|
||||
| internal/app/docflow/same_tx_pg_test.go | 状态与 outbox 同事务回滚 | 未运行 |
|
||||
| internal/events/dispatcher_pg_test.go | 多 worker、off/shadow、ack、隔离 | 未运行 |
|
||||
| internal/app/docnotify/e1a_pg_test.go | 通知权限、shadow/live、回滚 | 未运行 |
|
||||
| internal/app/docadvance/e1b_pg_test.go | 工作流事件消费 | 未运行 |
|
||||
| internal/app/docproject/e1c_pg_test.go | 投影与 no-replace | 未运行 |
|
||||
| internal/agent/piagent_typed_e2e_test.go | 条件启用的真实 PI | 未运行 |
|
||||
|
||||
PG 测试在 short 或缺少独立 DSN 时可跳过；PI 测试有显式开启条件。建议新增 A1–A5 的针对性场景，再做受影响用户入口验收。未经授权，本次不启动这些实现或共享环境测试。
|
||||
|
||||
## 与原方案的关系
|
||||
|
||||
继续引用 2026-09-20 A–G 分批整改作为现有依赖收敛清单，不能据此宣称原批次已经完成。A1–A5 是本次新增或细化的源码证据，实施时应并入同一治理链，避免开第二套互相冲突的解耦项目。
|
||||
|
||||
原规范保留模块化单体，本次通用规范允许按条件选择进程/服务隔离。两者分别用于“当前项目生效规则”和“未来项目待采纳标准”，没有自动覆盖关系。
|
||||
@@ -1,27 +0,0 @@
|
||||
# 历史问题补录：可选职责与正文哈希
|
||||
|
||||
补录日期：2026-09-23；owner：Codex；登记任务：[issue-learning-2026-09-23](../ops/short-term/2026-09-23-issue-learning.md)。这是两个问题的登记主记录，原审计、修复任务及验收报告继续作为事实证据；没有重新运行产品测试或读取业务数据。`evidence_basis=historical`，当前运行状态未复测，源码复核基线为 `2fdb6e548e3784771f27e6a9e79b9c364f76c566`。
|
||||
|
||||
## nullable-duty
|
||||
|
||||
- issue_id：`ISSUE-20260923-nullable-duty`；issue_state：`resolved`；severity：high；recurrence_count：0（指登记后重开次数，非历史发生总数）。
|
||||
- 发现/修复日期：2026-09-17；原处理 owner：Cursor；补录 owner：Codex；原任务：`fix/docgov-optional-duty-null-fk`。
|
||||
- 现象与已证实根因：[原审计](2026-09-17-docgov-optional-duty-null-fk.md)。可选 reviewer 缺席合法返回 0，但创建路径直接写入可空 FK；heal 路径已有空值映射，创建路径漏改。底层 FK 又被错误分型掩盖。
|
||||
- 同类范围：可选职责的创建/heal 写入边界。历史报告验证 reviewer/approver 为 NULL；不能由此推断所有 FK、全职责模式和全部授权边界均已验证。
|
||||
- 修复思路：保留可选职责语义，在 SQL 边界将缺席值映射 NULL，并改善错误分型；通过强制配置 reviewer 绕过错误会改变业务契约。未发现其他尝试的实测记录，不虚构失败实验。
|
||||
- 修复经过/提交：[原任务](../archive/ops/2026-09-17-docgov-optional-duty-null-fk.md)，历史合并 `e488d10`；本次只核对原文记录，不把短 SHA 当当前制品身份。
|
||||
- 验证与关闭范围：[原报告](../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md) 记录单测、PG 集成、真实任务 API 启动与 DB NULL；证明账本创建通过，不证明真实 UI 或 PI 全流程完成。历史 deployment=passed（dev，来源为原报告），当前运行未复测。
|
||||
- 本次复核：当前源码 `internal/docgov/engine.go` 创建路径仍调用 `nullIfZero`；这是源码检查，未重跑 PG。
|
||||
- 经验：[LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md)。后续触发：职责模型或任一持久化入口变化时复核，异常复发重开。独立的 flushSync 警告不在本条关闭范围。
|
||||
|
||||
## content-hash
|
||||
|
||||
- issue_id：`ISSUE-20260923-content-hash`；issue_state：`resolved`；severity：critical；recurrence_count：0（登记后）。
|
||||
- 发现/修复日期：2026-09-14；原处理：Cursor 修复、Antigravity UI 验收；补录 owner：Codex。
|
||||
- 现象与因果链：[原审计](2026-09-14-project143-controlled-content-404.md)。文件存在却被报 404；规范化去掉有硬换行语义的双空格，bootstrap 只改账本哈希未同步文件；并发 hydration 与无效轮询更新放大故障。
|
||||
- 同类范围：旧文档 bootstrap、规范化、账本/文件投影、错误映射与刷新竞态。历史扫描范围见原审计，不扩大为所有数据无问题。
|
||||
- 修复思路/选择：[整改方案](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md)。保持文本语义、原子投影和结构化错误；历史原文件与旧 head 先保全再显式 migration_repair。静默覆盖原文件会丢失语义，不能用于“对齐哈希”。这不是本轮数据操作授权。
|
||||
- 修复经过：[原审计关闭结果](2026-09-14-project143-controlled-content-404.md#关闭结果) 与 [最终报告](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；后续水合/缓存修复合入 `d0e8f60`、`36e4bc3`。报告保留早期失败及无效运行，只有 clean-run3 / full-chain-final 属最终有效证据。
|
||||
- 验证与关闭范围：原报告记录旧项目真实页面、全链路主阶段和重启恢复 PASS；历史 deployment=passed（dev）。不据此宣告当前 production_ready 或当前制品无回归。
|
||||
- 本次复核：`internal/docrevision/canonicalize.go` 已委托 doccontent；`canonicalize_golden_test.go` 包含硬换行和封装一致性测试。本次未执行这些测试。
|
||||
- 经验：[LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md)。后续触发：canonicalizer、bootstrap、投影或水合修改时复核；复发追加时间线并重开。
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
issue_id: ISSUE-20260923-matrix-status-regression
|
||||
issue_state: resolved
|
||||
severity: high
|
||||
owner: Cursor
|
||||
task_ids: [module-batches-ag-status-fix-2026-09-23]
|
||||
created: 2026-09-23
|
||||
occurred_at: 2026-09-23
|
||||
updated: 2026-09-23
|
||||
recurrence_count: 0
|
||||
evidence_basis: current
|
||||
lesson_ids: [LESSON-20260923-matrix-status-cas]
|
||||
---
|
||||
|
||||
# FEATURE-MATRIX 状态字段被合并冲突回退
|
||||
|
||||
按 [闭环规范](../ops/2026-09-23-issue-learning-workflow.md) 维护。关联任务：[module-batches-ag-status-fix](../ops/short-term/2026-09-23-module-batches-ag-status-fix.md)。
|
||||
|
||||
## 事实与证据
|
||||
|
||||
- **预期**：`module-batches-ag` 在 A–G 合入且 arch-check 全 0 后保持 `done`（提交 `77bdbdbc` 已写入）。
|
||||
- **实际**：本地 `dev` tip 上该行状态为 `planned`，剩余工作栏仍写「关闭本伞行」与 A–G 已合入事实矛盾；用户观感为「多次要求实现但未实现」。
|
||||
- **触发**：含 FEATURE-MATRIX 的 closeout / sync 合并冲突手解，取了无 `record_id` 或旧侧行内容。
|
||||
- **影响**：后续会话按 `planned` 错误前提规划，可能重复实施或延误收口；不构成发布 blocker（发布关系仍为 `non_blocker`）。
|
||||
- **环境**：本机 `dev` @ `18b9556f`（任务基线）；修复提交见本任务 feature 分支。
|
||||
- **复现（修复前）**：`git show 77bdbdbc:.doc/status/FEATURE-MATRIX.md` 该行 status=`done`；修复前 tip 同行为 `planned`。
|
||||
|
||||
## 根因与同类范围
|
||||
|
||||
- **已证实**：共享文档在 `docs apply` 行级 CAS / `record_id` 稳定键启用前窗口内，merge 冲突对手解无机器核验状态字段；手解取旧侧覆盖 `done`。
|
||||
- **已排除**：A–G 代码未合入（合入 merge commits 与 arch-check PASS 否定）。
|
||||
- **共用机制**：CURRENT / FEATURE-MATRIX 等协调 SSOT；任何绕过 `docs apply` 的整表手改或冲突取旧侧。
|
||||
- **同类入口**：其他矩阵行、CURRENT 认领行在无 CAS 收据时同样脆弱；本轮只修 `module-batches-ag`，不扩大扫全表 unless 另授权。
|
||||
|
||||
## 修复思路与过程
|
||||
|
||||
| 日期 | 假设 / 尝试 / 动作 | 实际结果与证据 | 决策 / 下一步 / owner |
|
||||
|---|---|---|---|
|
||||
| 2026-09-23 | 只读考古 git + arch-check | A–G 已落地；状态回退成立 | 按计划修正登记，不重做代码 / Cursor |
|
||||
| 2026-09-23 | docs apply 行级 CAS 恢复 `done` + 登记 lesson | MATRIX 行 status=`done`；header 同步；arch-check PASS | resolved；合入 local_dev / Cursor |
|
||||
|
||||
方案：恢复矩阵事实状态；登记问题与经验；强制后续矩阵变更走 `docs apply`；合入含 MATRIX 的合并后机器核对目标 `record_id` 状态列。
|
||||
|
||||
## 验收与关闭
|
||||
|
||||
- 原例：PASS — MATRIX `module-batches-ag` status=`done`（docs apply 收据 + commit `b9d09c97`）。
|
||||
- 同类：本任务不批量改其他行；风险已记入 lesson。
|
||||
- 正常：PASS — `docs apply` 无拒绝；`./scripts/arch-check.sh --mode block` PASS（worktree tip）。
|
||||
- deployment：`not_required`（纯文档）。
|
||||
- resolved：2026-09-23；范围=状态登记与台账，不含 Server 镜像字段增量。
|
||||
|
||||
## 经验与复发
|
||||
|
||||
- lesson：[LESSON-20260923-matrix-status-cas](../ops/lessons/2026-09-23-matrix-status-cas.md)
|
||||
- 防护：能力完成升 `done` 已有 `docs:approve` + evidence `cat-file` 门禁；复发时重开本 issue 并检查是否绕过 apply。
|
||||
@@ -1,297 +0,0 @@
|
||||
---
|
||||
title: "系统整改与重构方案 — 前两阶段及取消状态契约审核检查清单"
|
||||
status: done
|
||||
created: 2026-09-23
|
||||
updated: 2026-09-23
|
||||
severity: high
|
||||
task_id: modular-refactor-review-2026-09-23
|
||||
---
|
||||
|
||||
# 系统整改与重构方案 — 前两阶段及取消状态契约审核检查清单
|
||||
|
||||
## 1. 目的与范围
|
||||
|
||||
本清单供**产物机器**上的方案执行者，对照自查《系统整改与重构方案》中**阶段 1、阶段 2、取消状态契约**是否可审、可测、可回退。
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 目标方案（产物机器，本机不可见） | `.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md` |
|
||||
| 目标 worktree（产物机器） | `.worktrees/modular-contract-standard-2026-09-22` |
|
||||
| 本机清单基线 | local `dev@8f0e31e53a5f8d0dd25a908ba6d127a5bb6768a4` |
|
||||
| 本轮授权 | **仅编制清单并合入本机 dev**；不实施业务代码；不审核方案正文（本机无正文）；不 push |
|
||||
| 自查结果枚举 | `符合` / `偏差` / `阻断` |
|
||||
|
||||
**非目标**：阶段 3–6 全量逐条（除非阶段 1/2 或取消契约依赖它们）；业务实施；改 YAML 例外；FAV live / `production_ready` / test·main 晋升。
|
||||
|
||||
## 2. 「22 条规范」映射回填（本机未定位权威编号表）
|
||||
|
||||
本机可见权威材料中**没有**名为「22 条规范」的独立编号清单。邻近可对账来源：
|
||||
|
||||
| 候选来源 | 本机状态 | 与「22」的距离 |
|
||||
|---|---|---|
|
||||
| [模块开发规范](../system-design/2026-09-20-module-development-standards.md) §2–§4（端口规则表、事件契约、故障隔离红线 1–7、checklist） | active | 条目合计接近但**未编号为 1–22** |
|
||||
| [耦合审计](./2026-09-20-module-coupling-audit.md) + [A–G 分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md) | A–G 能力行已 `done` | 21 条 YAML `exceptions` + 边界规则，**非**「22 条规范」正文 |
|
||||
| 产物机器新方案（2026-09-22） | 本机不可见 | **应以方案正文为准** |
|
||||
|
||||
产物机器回填表（填完后本清单才可宣称「22 条已闭环对账」）：
|
||||
|
||||
| 规范编号 | 方案章节/工作包 ID | 本机对账锚点（规范/A–G/代码路径） | 阶段归属 | 自查 |
|
||||
|---|---|---|---|---|
|
||||
| N01 | _待填_ | _待填_ | 1 / 2 / cancel / 其他 | |
|
||||
| N02 | _待填_ | _待填_ | | |
|
||||
| … | | | | |
|
||||
| N22 | _待填_ | _待填_ | | |
|
||||
|
||||
若方案「22 条」≠ 上表候选来源，在回填表首行注明**权威出处路径 + SHA**，禁止用 A–G `done` 冒充新方案已验收。
|
||||
|
||||
## 3. 判定规则
|
||||
|
||||
| 判定 | 条件 |
|
||||
|---|---|
|
||||
| 符合 | 方案条目写明代码位置、依赖、责任范围、测试场景、回退条件；与本机锚点无冲突；测试可复现 |
|
||||
| 偏差 | 可合入意图成立，但路径过时、依赖遗漏、测试偏弱或回退含糊；实施前须修订方案 |
|
||||
| 阻断 | 与生效规范/[验证契约](../ops/2026-09-21-validation-contract.md)/表写者/事件至少一次语义冲突；或回退会丢数据/假 PASS |
|
||||
|
||||
每条核对项须留下：方案段落锚点、对照 SHA、结论、证据路径（可为本机相对路径或产物机器截图哈希）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 阶段 1 — 契约、模块职责、验证基线
|
||||
|
||||
### R1.1 三种通信契约完整且无第四种
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 模块开发规范 §2.1–§2.3；ADR 模块化单体 |
|
||||
| 应核对代码/文档 | `internal/app/*/ports.go`；`internal/events/registry.go` `StaticContracts()`；`internal/server` wire DTO；方案工作包是否禁止 gRPC/全局 bus/跨包未导出 helper |
|
||||
| 依赖与责任 | 消费者定义端口；组合根（`internal/app`、`cmd/*`）注入；server 不持领域 SQL |
|
||||
| 测试场景 | 新增端口无 JSON/`pgx`/物理路径；事件改动跑 registry↔YAML parity；HTTP 错误信封 `code/message/request_id` |
|
||||
| 回退核对 | 契约变更可单批 revert；不留下「半套第四种通信」 |
|
||||
| 自查 | |
|
||||
|
||||
### R1.2 表唯一写者与解包事务名单
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §4 红线 1–2；`module-boundaries.yaml` `table_owners` |
|
||||
| 应核对代码 | YAML `table_owners` / `tx_unpackers`；工作包是否把跨表原子性放在用例 UnitOfWork，而非各模块自开事务 |
|
||||
| 依赖与责任 | 非属主不得 `INSERT/UPDATE/DELETE`；server/chat 不得解包 `pgx.Tx`（除非已登记例外且有到期日） |
|
||||
| 测试场景 | `./scripts/arch-check.sh --mode block`；针对新增写路径的属主负例 |
|
||||
| 回退核对 | 回退代码与恢复/删除 exception **成对**，避免门禁与代码错位 |
|
||||
| 自查 | |
|
||||
|
||||
### R1.3 事件信封与至少一次投递 + 幂等
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §2.2、§3.2 |
|
||||
| 应核对代码 | `internal/events/registry.go`；`ClaimLeases` / outbox 同 UoW；消费者 inbox/`source_event_id`（例：`internal/notification/service.go` `EmitVisible*`） |
|
||||
| 依赖与责任 | 生产路径为 PG outbox + `cmd/events`；`MemoryBus` 仅特征测试 |
|
||||
| 测试场景 | 重复投递仅一个可见副作用；缺 `environment`/`project_id` fail closed；永久失败进 dead/quarantine 不堵其他订阅者 |
|
||||
| 回退核对 | 不回退到 SELECT-only claim（`ClaimIDs` 已禁用） |
|
||||
| 自查 | |
|
||||
|
||||
### R1.4 模块职责与 A–G 残留边界
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | [A–G 分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md)；FEATURE-MATRIX「模块解耦批次 A–G」=`done` |
|
||||
| 应核对 | 新方案 17 工作包是否**重复**已合入的 A–G，或明确「在 A–G 之上增量」；互斥 mutex 是否与已关闭批次冲突 |
|
||||
| 依赖与责任 | 新工作包不得把 FAV live / RPC / `production_ready` 回退写进完成定义 |
|
||||
| 测试场景 | 声明的依赖边在合入后可用 `go list` / arch-check 证明消失或未回潮 |
|
||||
| 回退核对 | 单工作包 revert；不整支回滚无关批次 |
|
||||
| 自查 | |
|
||||
|
||||
### R1.5 验证基线与门禁衔接
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | [验证契约](../ops/2026-09-21-validation-contract.md)；规范 §7 |
|
||||
| 应核对 | 方案阶段 1「验证基线」是否映射到：`arch-check --mode block`、`go vet ./...`、`go test -short ./...`；前端相关则 `npm test` / `npm run build`；纯文档不要求 PI |
|
||||
| 依赖与责任 | stub/SKIP 不得作交付 PASS；共享环境测试须持锁 |
|
||||
| 测试场景 | 方案每个工作包的「测试场景」列能落到精确包路径或 `-run` 名 |
|
||||
| 回退核对 | 失败时保留候选证据，不伪造 PASS |
|
||||
| 自查 | |
|
||||
|
||||
### R1.6 稳定词汇与跨包错误
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §3.3；批次 C |
|
||||
| 应核对 | `internal/contracts/vocabulary`；方案是否禁止新增 `docgov.State*` / `Role*` / `Err*` 跨包引用 |
|
||||
| 依赖与责任 | 带哈希/路径的函数留在属主模块（如 `doccontent`） |
|
||||
| 测试场景 | 热点引用改为端口或词汇后，原状态机测试仍绿；HTTP code 不变 |
|
||||
| 回退核对 | 单批 revert |
|
||||
| 自查 | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 阶段 2 — 通知事务、事件领取、授权、业务入口一致性
|
||||
|
||||
### R2.1 通知与领域提交同事务
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §2.2「副作用与 receipt 能进同一数据库事务的必须同事务」；§4 红线 4（持锁不做外部 IO） |
|
||||
| 应核对代码 | `internal/notification/service.go` / `document_events.go`（`EmitVisible*` 要求 caller fenced tx）；`internal/app/docadvance/consumer.go`；dispatcher `handle` 在 lease tx 内调用 handler |
|
||||
| 依赖与责任 | notify 消费者不在持锁路径调 LLM/HTTP/SSE；可见通知以 `source_event_id` / dedupe 幂等 |
|
||||
| 测试场景 | 提交失败无可见通知；重复 `source_event_id` 成功且不双写；`HashVisibleNotifications` 类对账 |
|
||||
| 回退核对 | 回退后不得留下「已提交领域、无通知」或相反的半状态；优先前滚修复 |
|
||||
| 自查 | |
|
||||
|
||||
### R2.2 事件领取：lease、续租、抢占
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §2.2；Phase 2 事件计划（投递/lease 语义） |
|
||||
| 应核对代码 | `internal/events/dispatcher.go` `ClaimLeases` / `HeartbeatLease`；`internal/events/worker.go`；`cmd/events` |
|
||||
| 依赖与责任 | 生产禁止 `ClaimIDs`；quarantine/expire 不可被再次 claim；多 worker 互斥由 `FOR UPDATE SKIP LOCKED` 语义保证 |
|
||||
| 测试场景 | `dispatcher_pg_test`：双 worker 仅一人领到；quarantine 不可领；续租失败不再处理 |
|
||||
| 回退核对 | 不恢复已禁用的 SELECT-only claim；lease 时长变更有观察窗 |
|
||||
| 自查 | |
|
||||
|
||||
### R2.3 授权检查收敛点
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §2.1「Principal 只来自已认证会话」；§2.3 授权拒绝不泄露存在性；多意图设计「卡片/SSE 不能替代授权」 |
|
||||
| 应核对代码 | `internal/authz`；`internal/server/*_handlers.go`（task/intent/freeform 等）在 Flush/副作用前鉴权；`events.AuthorizePrincipal` 于消费者路径 |
|
||||
| 依赖与责任 | 请求体不得覆盖 UserID/ProjectID；消费者授权失败 → quarantine，非无限重试 |
|
||||
| 测试场景 | 跨用户 IDOR 负例 403；SSE 鉴权在 Flush 前（对照 gap `AUTH-TASK-SSE`）；重复提交不绕过 |
|
||||
| 回退核对 | 回退不得重新打开已关闭 IDOR；测试与代码同批 |
|
||||
| 自查 | |
|
||||
|
||||
### R2.4 业务入口一致性（HTTP / 对话 / SSE / 事件投影）
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 规范 §2.3；多意图权威性排序：认证主体与资源 → 授权/不变量 → PG → 卡片投影 → SSE |
|
||||
| 应核对代码 | 同一命令是否只经一个用例入口；chat action 与 REST 是否共用端口；投影/SSE 是否只读权威状态 |
|
||||
| 依赖与责任 | GET 不修投影（红线 6）；修复为独立命令并写审计 |
|
||||
| 测试场景 | 双入口同输入同权威结果；刷新后以 GET 覆盖本地缓存；投影丢失仍能经 active discovery 找回 |
|
||||
| 回退核对 | 入口合并失败时可切回旧入口且状态不分裂 |
|
||||
| 自查 | |
|
||||
|
||||
### R2.5 与阶段 1 基线的衔接（方案自述三处衔接问题）
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 用户汇报：审阅发现的三处衔接问题已修正 |
|
||||
| 应核对 | 方案正文是否显式列出三处问题的**原描述、修正段落、回归检查**；是否仍依赖未合入的阶段 3+ 契约 |
|
||||
| 依赖与责任 | 修正不得静默改验证契约或放宽 arch-check |
|
||||
| 测试场景 | 针对三处各有一条可执行核对（文档锚点或测试名） |
|
||||
| 回退核对 | 修正可独立 revert 而不拆阶段 1 |
|
||||
| 自查 | |
|
||||
|
||||
---
|
||||
|
||||
## 6. 取消状态契约 — Runner 取消、未知结果、SSE 恢复
|
||||
|
||||
> 用户建议优先审核。本机可见实现重心：`internal/taskrun`（`Cancel`/`StatusCancelled`/`taskrun.cancelled` 事件）、`internal/server/task_run_handlers.go`（Cancel + SSE `after_seq`）、`internal/agent/piagent.go`、多意图计划中的 cancel 转移。
|
||||
|
||||
### R3.1 取消状态机覆盖全转移
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 方案「取消状态契约」；多意图步骤状态含 `cancelled`；`taskrun.cancelled` 事件登记 |
|
||||
| 应核对 | 状态集合是否覆盖：`cancel_requested` →（执行中）→ `cancelled` / `unknown`（或方案等价命名）；禁止从终态回退到 running |
|
||||
| 代码锚点 | `internal/taskrun/finalize.go`（`Commands.Cancel`、`StatusCancelled`、事件名）；`manager.go` `Cancel`；意图计划状态机（若工作包触及） |
|
||||
| 依赖与责任 | 取消与 finalize 竞态仅一个终态（见 `TestPG_FinalizeCancelRaceOneTerminal` / `TestCommands_CancelWinsOverFinalizeMemory`） |
|
||||
| 测试场景 | 用户取消、租约过期视同取消、Runner 已结束后的迟到取消、双端并发 cancel/finalize |
|
||||
| 回退核对 | 回退不得出现双终态或「已取消仍计费/仍写产物」 |
|
||||
| 自查 | |
|
||||
|
||||
### R3.2 未知结果：幂等重试与人工裁定
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 操作规范/AGENTS：Docker/网络超时先区分未知与未执行；管理器不自动撤销外部副作用 |
|
||||
| 应核对 | 方案是否定义 `unknown`（或等价）的进入条件、可见对外语义、幂等重试键、人工裁定 API/运维入口、超时升级 |
|
||||
| 代码锚点 | taskrun 结果应用路径；PI Runner 客户端（`internal/agent/piagent.go`）；方案工作包列出的裁定命令 |
|
||||
| 依赖与责任 | 未知不得冒充 `succeeded`/`cancelled`；重试必须带 fencing/idempotency，避免双执行 |
|
||||
| 测试场景 | Runner 超时无响应 → unknown；重试仅一次可见副作用；裁定后 SSE/GET 一致 |
|
||||
| 回退核对 | 清除 unknown 标记不得删除审计；禁止自动 Down/删库「恢复」 |
|
||||
| 自查 | |
|
||||
|
||||
### R3.3 执行租约、fencing 与取消的交互
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 多意图设计：短 lease + owner + lease_until + fencing；续租失败不再领步骤 |
|
||||
| 应核对 | 取消是否使 lease 立即失效；旧 fencing token 的迟到心跳/完成是否被拒绝 |
|
||||
| 代码锚点 | `internal/taskrun` store/lease；workspace lease 相关迁移与调用 |
|
||||
| 依赖与责任 | 持 lock 期间取消不调用外部 IO；取消收据与 outbox 同事务（若发 `taskrun.cancelled`） |
|
||||
| 测试场景 | 取消后旧 worker 心跳失败；fencing 错则拒绝 finalize |
|
||||
| 回退核对 | 放宽 fencing 视为阻断，不得以「兼容」绕过 |
|
||||
| 自查 | |
|
||||
|
||||
### R3.4 SSE 恢复后与权威状态一致
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 系统健康整改 Wave0（`after_seq`、心跳、Flush 前鉴权）；多意图「SSE 允许重复/乱序/丢失，缺口 GET 对账」 |
|
||||
| 应核对代码 | `internal/server/task_run_handlers.go`（`after_seq`、`extendSSEWriteDeadline`、Cancel handler）；`web/src/api/taskStream.ts`；聊天 SSE 同等语义 |
|
||||
| 依赖与责任 | SSE 非权威；取消/unknown 以 PG/GET 为准覆盖本地 |
|
||||
| 测试场景 | 断线重连不重复创建运行；取消过程中重连看到终态；WriteTimeout 后同 turn 不误 409（对照 `DOCREV-SSE-IDEM-BUSY` 经验） |
|
||||
| 回退核对 | 去掉 `after_seq` 视为回归阻断 |
|
||||
| 自查 | |
|
||||
|
||||
### R3.5 Runner 取消传播
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 规范来源 | 方案阶段 2/3 交界：Runner 取消与未知结果 |
|
||||
| 应核对 | HTTP/对话取消 → taskrun → PI Runner 取消信号是否端到端定义；Runner 已完成后的取消应答 |
|
||||
| 代码锚点 | `Manager.Cancel`；server cancel 路由；PI 客户端 cancel |
|
||||
| 依赖与责任 | 取消失败进入 unknown 而非假 cancelled（若方案如此定义则测试锁定） |
|
||||
| 测试场景 | Runner 可取消；Runner 无响应 → unknown；已终态 cancel 幂等成功 |
|
||||
| 回退核对 | 回退保留「至少不双执行」不变量 |
|
||||
| 自查 | |
|
||||
|
||||
---
|
||||
|
||||
## 7. 工作包级抽查模板（阶段 1/2 + 取消相关包）
|
||||
|
||||
对方案中每个相关工作包复制下表（ID 以方案为准）：
|
||||
|
||||
| 工作包 ID | 阶段 | 规范 Nxx | 代码位置（方案 vs 本机） | 依赖 | 责任范围 | 测试场景可执行？ | 回退可操作？ | 判定 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| WP-? | 1 | | | | | 是/否 | 是/否 | |
|
||||
| WP-? | 2 | | | | | | | |
|
||||
| WP-? | cancel | | | | | | | |
|
||||
|
||||
**阻断级缺省**（出现任一条则该包不得开工实施）：
|
||||
|
||||
1. 无精确文件/包路径，或路径在本机 `dev@8f0e31e5` 已改名且方案未更新。
|
||||
2. 测试场景只有「手动看看」或依赖 stub 作交付。
|
||||
3. 回退是「再想想」或要求硬重置/删库。
|
||||
4. 扩大写路径/mutex 未在任务登记中重新认领。
|
||||
5. 将卡片/SSE/前端缓存当作授权或权威状态。
|
||||
|
||||
## 8. 产物机器回填指引
|
||||
|
||||
1. 在产物机器打开方案 + 本清单（本清单合入本机 `dev` 后，经授权 `push` 或手动同步到产物机器）。
|
||||
2. 先填 §2 的 N01–N22 映射；未填完不得宣称阶段 1 审核通过。
|
||||
3. 按 §4–§6 逐条标 `符合`/`偏差`/`阻断`，证据写入方案附录或 `.doc/test-reports/`（普通文档级即可）。
|
||||
4. 若有 `阻断`：只改方案文档，**不**开工对应业务代码；修正后更新方案 `updated` 与衔接说明。
|
||||
5. 全部阶段 1/2 + 取消契约无 `阻断` 且偏差有修订计划后，在产物机器 CURRENT 登记「方案审核通过、待实施授权」——实施须**另开**任务与授权，不由本清单授权。
|
||||
6. 本清单单列任务 `modular-refactor-review-2026-09-23`；方案合入/实施不得冒用本 task_id 扩权。
|
||||
|
||||
## 9. 本机环境与证据边界
|
||||
|
||||
| 项 | 记录 |
|
||||
|---|---|
|
||||
| 本机 | macOS Darwin；仓库 `/private/tmp/Agent-System` |
|
||||
| 方案正文 | **不可见**（另一主机 `/home/weichen/projects/...`；origin/frp-mix 无对应分支） |
|
||||
| agentctl | 本机已可用 `with` / `docs apply` / `validate` / `integrate`（进程层）；创建本任务时已 `task register` |
|
||||
| 清单性质 | 审核**方法**与核对项，不是对方案正文的已审结论 |
|
||||
|
||||
## 10. 相关链接
|
||||
|
||||
- 任务记录：[../ops/short-term/2026-09-23-modular-refactor-review.md](../ops/short-term/2026-09-23-modular-refactor-review.md)
|
||||
- 模块开发规范：[../system-design/2026-09-20-module-development-standards.md](../system-design/2026-09-20-module-development-standards.md)
|
||||
- A–G 分批：[../remediation/2026-09-20-module-decoupling-batch-plan.md](../remediation/2026-09-20-module-decoupling-batch-plan.md)
|
||||
- 耦合审计：[./2026-09-20-module-coupling-audit.md](./2026-09-20-module-coupling-audit.md)
|
||||
- 验证契约：[../ops/2026-09-21-validation-contract.md](../ops/2026-09-21-validation-contract.md)
|
||||
- gap-matrix：[../remediation/gap-matrix.md](../remediation/gap-matrix.md)
|
||||
- 操作规范：[../ops/2026-09-21-agent-worktree-workflow.md](../ops/2026-09-21-agent-worktree-workflow.md)
|
||||
@@ -1,67 +0,0 @@
|
||||
# 管理员重置密码 / 登录凭据缺陷 — 问题主记录
|
||||
|
||||
更新：2026-09-24。任务：`admin-password-reset-2026-09-24`。
|
||||
|
||||
## ISSUE-20260924-admin-reset-dead
|
||||
|
||||
### 问题
|
||||
|
||||
管理台「重置密码」按钮调用 `authClient.adminResetPassword`，客户端硬 `throw`，后端无 `reset-password` 路由；UI 仍硬编码 `ResetPass123` 暗示成功。验收脚本曾重置 `chenwei` 哈希且不披露口令后，管理员无法通过 UI 恢复访问。
|
||||
|
||||
### 根因
|
||||
|
||||
T20-F4 已设计未实施（选项 B 卡产品）。`password_changed_at` 停在 2026-09-20 证明重置从未入库。
|
||||
|
||||
### 修复
|
||||
|
||||
`POST /api/v1/admin/users/{id}/reset-password`：服务端随机临时口令、`must_change_password=true`、撤销会话、审计表 `user_password_reset_audits`（goose 00067）；前端接线并去掉硬编码。
|
||||
|
||||
### 状态
|
||||
|
||||
resolved（本任务合入后）。
|
||||
|
||||
---
|
||||
|
||||
## ISSUE-20260924-login-error-envelope
|
||||
|
||||
### 问题
|
||||
|
||||
登录失败响应 `code=AUTHZ` / `message=无权访问`，前端再把整段 JSON 原文塞进 `Error.message`，用户误判为权限问题。
|
||||
|
||||
### 根因
|
||||
|
||||
`httpx.CodeFromStatus(401)=AUTHZ` + `SafeMessage`；`auth.ts` login 未用信封解析、未优先 `error` 领域字段。
|
||||
|
||||
### 修复
|
||||
|
||||
`authErrorMessage` 优先取信封 `error`；不改全局 AUTHZ 映射（事件复用与安全取舍另立专项）。
|
||||
|
||||
### 状态
|
||||
|
||||
resolved。
|
||||
|
||||
---
|
||||
|
||||
## ISSUE-20260924-zombie-credentials
|
||||
|
||||
### 问题
|
||||
|
||||
`CreateUser` 在 `PasswordHash==""` 时静默跳过 `user_credentials` 插入；`LEFT JOIN` + `COALESCE` 使登录哈希为空串，任意密码均失败且报错与真凭据错误相同。
|
||||
|
||||
### 盘点（只读，2026-09-24）
|
||||
|
||||
| 环境 | total | missing_cred | empty_username |
|
||||
|---|---|---|---|
|
||||
| dev | 416 | 263 | 255 |
|
||||
| test | 9 | 0 | 0 |
|
||||
| main | 4 | 3 | 0 |
|
||||
|
||||
main 三行为 goose 00011 seed（`seed-admin` 等），非业务用户。本任务**不清理**存量；仅 fail-closed 防新增。
|
||||
|
||||
### 修复
|
||||
|
||||
PgStore/MemoryStore `CreateUser` 拒绝空哈希；`Login` 对空哈希记 `slog.Warn(user_id)` 仍统一 401。
|
||||
|
||||
### 状态
|
||||
|
||||
resolved（机制）；存量清理 = open / 另授权。
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
issue_id: ISSUE-20260924-cursor-hook-event-contract
|
||||
issue_state: open
|
||||
severity: medium
|
||||
owner: Cursor
|
||||
task_ids: [cursor-governance-hooks-2026-09-24]
|
||||
created: 2026-09-24
|
||||
occurred_at: 2026-09-24
|
||||
updated: 2026-09-24
|
||||
recurrence_count: 0
|
||||
evidence_basis: current
|
||||
lesson_ids: [LESSON-20260924-cursor-hook-advisory-gates]
|
||||
---
|
||||
|
||||
# Cursor hook 事件字段契约未文档化
|
||||
|
||||
## 事实与证据
|
||||
|
||||
预期：`beforeMCPExecution` / `sessionStart` / `stop` 的 stdin 字段名与 matcher 匹配串在官方文档中明确，便于 failClosed 硬门禁。
|
||||
实际：官方 create-hook skill 仅明确 `beforeShellExecution` 的 `command` 字段；`beforeMCPExecution` 不支持 `updated_input`；`sessionStart` 无文档化返回字段可注入上下文；`MCP: ...` matcher 形式只写给 `preToolUse` 族。实现层字符串探测存在 `mcp_server_name`/`tool_name`/`tool_input`，但非文档契约。
|
||||
|
||||
证据：本任务调研记录；单元测试用多名容错驱动；真实 Cursor IDE 事件采样待 `CURSOR_HOOKS_PROBE=1`。
|
||||
|
||||
## 根因与同类范围
|
||||
|
||||
客户端 hook API 文档滞后于实现。同类：任何依赖未文档化 hook 输入的 failClosed 门禁都有假阴性/假阳性风险。
|
||||
|
||||
## 修复思路与过程
|
||||
|
||||
| 日期 | 动作 | 结果 | 下一步 |
|
||||
|---|---|---|---|
|
||||
| 2026-09-24 | 落地 advisory hooks + 多名容错 + probe 开关；异形 fail-open | 单元回归 PASS | 用户触发真实 MCP/shell 事件采样后收紧 |
|
||||
|
||||
## 验收与关闭
|
||||
|
||||
- 静态/单元：已覆盖（见测试报告）
|
||||
- 实机：打开 `CURSOR_HOOKS_PROBE=1`，触发一次 `pi_subagent_roles` 与一次 shell，归档 `.cursor/hook-probe.jsonl` 片段到测试报告 assets；确认字段名后可将 matcher/`failClosed` 收紧并将本 issue → verifying/resolved
|
||||
|
||||
## 经验与复发
|
||||
|
||||
见 [LESSON-20260924-cursor-hook-advisory-gates](../ops/lessons/2026-09-24-cursor-hook-advisory-gates.md)。
|
||||
|
||||
## 2026-09-24 IDE 采样更新
|
||||
|
||||
- `postToolUse` 审计：`tool_name` / 审计字段为 `MCP:pi_subagent_roles`（带 `MCP:` 前缀）。
|
||||
- 修复：`_lib.normalize_tool_name` 剥前缀；回归 `test_ask_mcp_prefixed_tool_name_bad_sha`。
|
||||
- `pi_subagent_roles` IDE MCP 调用 PASS；`postToolUse` 收据 checklist 已注入。
|
||||
- `beforeMCPExecution` 完整 stdin 仍缺（Cursor 进程未设 `CURSOR_HOOKS_PROBE=1`）；issue 保持 verifying。
|
||||
- `agentctl`/`jev` 未出现在 IDE MCP 缓存目录；进程可手动 stdio 启动；与路径修复独立，另记。
|
||||
@@ -1,37 +0,0 @@
|
||||
# ISSUE-20260924-non-author-400-duty
|
||||
|
||||
## 摘要
|
||||
|
||||
非编制项目成员无法上传/总结/对话写草稿；权限错误经 `writeDocGovError` 默认落成 HTTP **400**。
|
||||
|
||||
## 根因
|
||||
|
||||
1. `domainHTTPStatus` 未映射 `ErrOnlyAuthorCanEdit` / `ErrReviewerCannotEdit` / `ErrApproverCannotEdit` → 403。
|
||||
2. `classifyAccess` / `AllowedTaskKeys` / `CanEditDocumentContent` 将 run/edit 绑编制职责（三道门协同过宽）。
|
||||
3. 前端写意图路由偶发把「总结+写动词」送入 task run。
|
||||
|
||||
## 处置（deny_only_submit）
|
||||
|
||||
- run/edit → 项目成员级；submit/review/approve 保留职责门禁。
|
||||
- AuthorID 仍归编制职责人（`docduty.Resolve` 不变）。
|
||||
- 人工编辑传 `ActorIsMember`，不复用 `RoleSystem`。
|
||||
|
||||
## 验证
|
||||
|
||||
见 [测试报告](../test-reports/2026-09-24-non-author-member-access-test-report.md)；真实 PI PASS。
|
||||
|
||||
## 状态
|
||||
|
||||
resolved（2026-09-24）
|
||||
|
||||
## 五态收口（2026-09-24）
|
||||
|
||||
| 字段 | 值 |
|
||||
|---|---|
|
||||
| review_state | accepted（真实 PI `TestNonAuthorMember_PiAgent_RunEditSubmitGates` PASS；工程门禁 PASS） |
|
||||
| integration_state | merged_local_dev（`dev@e98e2d71`；feature tip `8b2621a4` 为祖先） |
|
||||
| deployment | not_required（本轮未要求加载 launchd 业务制品） |
|
||||
| cleanup | pending（`.worktrees/non-author-member-access-2026-09-24` 与 integrate 现场待独立维护者复查后清理；禁止 `--force`） |
|
||||
| remote_sync | pushed（`origin/dev` = `e98e2d71`，`./scripts/git-push-dev.sh dev` 已成功） |
|
||||
|
||||
相关 agentctl 任务：`non-author-member-access-2026-09-24`、`non-author-member-access-docs-2026-09-24`、`integrate-non-author-docs-2026-09-24` 均为 `done`。
|
||||
@@ -1,45 +0,0 @@
|
||||
# PI Subagent 执行器初版边界审查
|
||||
|
||||
task_id：subagent-workflow-standard-2026-09-24；issue_id：ISSUE-20260924-pi-executor-boundaries。
|
||||
owner：Cursor（修复）/ Codex（复核）；issue_state：resolved；severity：high。
|
||||
本记录针对尚未发布的执行器初版，不表示 dev 或产品 Runner 存在这些实现。
|
||||
|
||||
## 事实与机制
|
||||
|
||||
1. 独立验证发现 PI 内置工具的路径规范化与扩展守卫不一致。安装版本 0.85.1 的 tools/path-utils.js 中 resolveToCwd 使用 stripAtPrefix 并展开 home；初版守卫使用 path.resolve(root,input)。
|
||||
2. 以专门创建的 /tmp/pi-guard-audit-* 临时目录及 outside.txt 假文件测试 @绝对路径，实际结果为 guard_blocked=false、actual_tool_path_escapes=true。没有读取真实密钥或业务文件。
|
||||
3. 同类范围：@ 前缀、~ 前缀、相对父路径、符号链接、Unicode/读取路径规范化；MCP 的同仓/工作区验证和临时文件写入；报告幂等与损坏收据；进程树/输出上限/环境变量隔离。
|
||||
4. 初版静态阅读另发现：跨仓 MCP 可能执行目标仓脚本；输出仅在 communicate 完成后截断；只回收仍存活 leader 的进程组；测试环境黑名单不足；模型报告用关键词推导 PASS。上述需要实现修复和负例，不以本行代替实测。
|
||||
5. 初版测试夹具存在 eager stderr.read()，在 MCP 仍存活时阻塞。host 两次仅终止 /tmp/pi-subagent-test-* 的假 MCP 子进程以释放测试，未终止产品或用户进程。
|
||||
|
||||
## 复现与迭代
|
||||
|
||||
- 初次 RED：19 项，7 failures / 11 errors，主实现未创建；存在性/调用失败为已缺失功能，不当作实现通过。
|
||||
- 初版回归：19 项，4 failures / 7 errors；耗时含夹具死锁处理。后续错误数不作为发布质量结论，待主机完整重跑。
|
||||
- Cursor 首轮 supervisor 已由 host 为明确的修复交接发送 TERM，退出143；源文件保留。没有未知写副作用后盲目重派，第二轮是带具体修复清单的新执行。
|
||||
- 本机 Qwen3.8-Flash、GLM-5.3-Flash 无工具短请求连通通过，实际 provider/model 与配置一致，正常 stop + agent_end/agent_settled。仅连接证据。
|
||||
- GLM-5.3 对初版整包快照的只读审查 300 秒超时，无完整结论；不报审查 PASS。进程由 subprocess 超时处理结束，未授予工具，无仓库写入。
|
||||
|
||||
## 修复与验收要求
|
||||
|
||||
Cursor 修复清单已交接：统一/拒绝路径规范化；MCP 同仓注册验证和无租约写入；有界双向进程通信/整体回收；测试环境白名单；严格请求/配置与冻结 SHA；损坏收据禁止重派；报告完成与审查通过分离；最终事件完整性；禁用 PI 隐式重试；相关真实 Git/进程/MCP 回归。
|
||||
|
||||
关闭条件：静态发现均落实对应修复或有证据排除；原例与同类负例通过；真实 PI 调用经新执行器完成；审查与测试报告保存。修复中，不新增 validated 经验；验证后再总结。
|
||||
|
||||
## 2026-09-24 修复关闭
|
||||
|
||||
issue_state=resolved 仅针对未发布初版的约定缺陷；代码提交 69ffaa677e23a1dd9aa0528bb09b3acfcd38b119，主机完整工程回归 173 项通过，提交后专项 34 项通过；最终 Cursor CLI→MCP→PI 中 ls/read 全通过。实际覆盖、早期失败和独立 GLM 审查边界见[报告](../test-reports/2026-09-24-pi-executor-test-report.md)。
|
||||
新增[经验](../ops/lessons/2026-09-24-pi-tool-boundaries.md)。本文件前面的“修复中/待验证”为初版历史，当前结论以本节为准。dev 集成/客户端 IDE 验收不由本问题关闭状态推导。
|
||||
|
||||
## cursor-cli-mcp-path
|
||||
|
||||
issue_id：ISSUE-20260924-cursor-cli-mcp-path；issue_state：deferred；severity：medium；owner：工程维护；日期：2026-09-24。
|
||||
本机 Cursor CLI 2026.09.18 在项目 MCP args 中未展开 workspaceFolder 变量，原样传给 Node。pi-subagents 新入口已改工作区相对路径并实测通过。
|
||||
同类只读检查：agent mcp list 也显示既有 agentctl / jev Connection failed，它们仍使用相同变量写法；codegraph ready。未进一步修改/验收这两个既有服务，也未断言 IDE 同样失败。官方支持声明与本机观测须分开。
|
||||
此残差不阻塞 PI MCP（其内部直接调用主仓治理 CLI），不构成本轮产品发布结论；后续由工程维护在 Cursor CLI 升级或这两项 MCP 接入验收时检查路径/stdio 协议，形成独立修复与实际客户端证据。仅保留问题，不宣称已修复。
|
||||
|
||||
|
||||
## cursor-cli-mcp-path 续：NDJSON 回包
|
||||
|
||||
2026-09-24 IDE：`pi-subagents`/`codegraph` ready；`agentctl`/`jev` 不在 MCP 缓存。
|
||||
根因补充：后两者 `send()` 使用 `Content-Length` 帧，而可加载的 `pi-subagents` 使用换行分隔 JSON-RPC。已改为 NDJSON 回包并补 `"type":"stdio"`；仍接受 Content-Length 请求。单元：`scripts/tests/test_mcp_ndjson_framing.py`。IDE 重载后需再核 `list-tools`。
|
||||
@@ -1,111 +0,0 @@
|
||||
# Cursor Auto 与 Subagent 工作流研究及文档验证报告
|
||||
|
||||
日期：2026-09-24；owner：Codex；task_id：subagent-workflow-standard-2026-09-24。
|
||||
范围：现行规范、Cursor 项目配置及官方文档；交付[规范草案](../ops/2026-09-24-subagent-workflow-standard.md)。未运行 Cursor 对话/真实 subagent，未修改产品或运行环境。
|
||||
|
||||
## 1. 研究结论
|
||||
|
||||
推荐主 Agent 协调、按需委派、独立审查与验证的流程。用户提出的八步可作为起点，但需在开始明确授权/验收标准，在方案阶段设计测试，在实施中自测，合并后核对实际运行结果，最后归档和清理。
|
||||
|
||||
| 方案 | 收益 | 代价/缺陷 | 结论 |
|
||||
|---|---|---|---|
|
||||
| 单 Agent 顺序完成全部阶段 | 简单、额外上下文成本低 | 实施者自审容易沿用错误假设 | 适合小型文档/研究；代码交付补独立审查 |
|
||||
| 每阶段固定一个 Agent / 固定模型 | 阶段职责直观 | 无效启动和文档重复；固定模型背离 Auto；阶段间易丢授权/版本 | 不采用 |
|
||||
| 主 Agent + 按需 analyst/reviewer/verifier | 保留上下文入口，独立检查，成本可控 | 需可靠派发包、证据接收和异常恢复 | 推荐；实现并行按风险逐步启用 |
|
||||
|
||||
这是本项目基于现状的设计判断，不是 Cursor 平台保证。
|
||||
|
||||
## 2. 官方能力与推论
|
||||
|
||||
查阅日期为 2026-09-24。在线文档会变化，客户端接入必须另验；不采用社区传闻作为技术契约。
|
||||
|
||||
| 来源 | 查证事实 | 对本规范的影响 |
|
||||
|---|---|---|
|
||||
| [Cursor Subagents](https://cursor.com/docs/subagents) | 自定义角色可位于 .cursor/agents；model 默认 inherit；readonly 与后台字段可配置；子上下文需要主 Agent 提供输入；默认共享 checkout | 采用继承策略、显式交接、仓库管理的写隔离；只读报告由主 Agent 保存 |
|
||||
| [Cursor Models & Pricing](https://cursor.com/docs/models-and-pricing) | Auto 是平台模型路由选项，公开文档列有不同优化模式 | 规则不绑定模型、价格或固定路由；按实际 UI/账户能力记录 |
|
||||
| [Cursor Rules](https://cursor.com/docs/rules) | 支持 AGENTS.md 和项目规则 .mdc | 根入口/客户端入口只指向单一规范，避免重复规则漂移 |
|
||||
|
||||
推论与限制：inherit 能表达继承意图，不足以证明实际模型身份或所有 Auto 请求的路由；独立上下文不保证跨模型独立性；只读权限与运行测试的写产物需要区别处理。Auto 可用性、角色加载、权限、真实派发及费用均未在本会话实测，不保证任何套餐或所有版本可用。云执行不在本次授权与建议默认范围内。
|
||||
|
||||
## 3. 当前仓库证据
|
||||
|
||||
检查基线：dev = 5423b261f97f371bdf7fa5066e9305f9eddaef42；本地 origin/dev 跟踪引用比较为 ahead 74 / behind 0。未 fetch，不能据此声明服务器当前引用。
|
||||
|
||||
- AGENTS / PROJECT：已定义授权分级、任务 worktree、独立状态、业务实施和研究边界。
|
||||
- worktree 操作规范：已有 agentctl 租约、候选验证/合入、共享环境持锁、清理负例和收口要求。
|
||||
- 验证契约：依据变更范围取并集，要求真实用户流程与持久证据；文档变更不要求产品回归。
|
||||
- 文档地图/任务模板：已有最小文档原则，可以按阶段留证而不制造九份重复文档。
|
||||
- .cursor/rules：已有 agentctl、文档、Git 和测试入口。rg --files .cursor 未发现项目 .cursor/agents 角色定义；不推断用户全局目录没有角色。
|
||||
- .cursor/hooks.json：存在 beforeShellExecution 的 Git 守卫；未见本流程阶段完整性校验。此处仅配置阅读，没有实际触发 hook。
|
||||
- cursor --version：3.21.16 / 8ae78e8eee1e63479c7e0504b664bc0a80c68000 / x64；agent --version：2026.09.18-9a7762b。CLI 版本不代表 IDE 当前会话配置已验收。
|
||||
- agentctl status：当前配置 policy_revision 为 agent-governance-2026-09-23-fav-constraint-restored；存在其他任务持 env:dev。研究不使用该环境，不改他人任务。
|
||||
|
||||
已读规范修订与工具配置 revision 不同，记录两者分别是什么，不把一个全局字段视作所有 Markdown 修订版本。
|
||||
|
||||
## 4. ISSUE-20260924-cursor-test-rule-drift
|
||||
|
||||
issue_state：open；严重度：medium；owner：Codex（研究）；evidence_basis：本次源码/配置阅读；产品影响未复现。
|
||||
预期：客户端测试规则只引用验证契约，由适用范围和批准环境决定套件/Runner。
|
||||
实际：.cursor/rules/test-reports-standard.mdc（alwaysApply=true）仍要求报告附全量 go test -v ./...，固定 MiniMax-M2.7-highspeed，并指向已不存在的 PROJECT §8。与验证契约中的范围选择、实际批准模型、普通小任务记录方式不一致。
|
||||
|
||||
已证实机制：客户端复制完整测试规则形成第二份来源，主规范修订后副本继续陈旧。未证实：实际 Cursor 是否因此执行了错误模型/测试、费用或运行行为是否受影响。
|
||||
为何已有保护不足：静态读取显示没有针对该副本文案与验证契约的一致性证据；本次没有运行 hook/CI，不能断言所有自动防护都缺失。
|
||||
同类检查范围：.cursor/rules 下五个规则文件及 hooks 配置、根 AGENTS/PROJECT、验证契约、规范登记、任务/收口模板。其余四个 mdc 主要转发入口；本次未检查所有其他客户端和全局规则。
|
||||
|
||||
推荐修复：将该 mdc 缩为验证契约与报告路径指针；结构要求归并现有权威文件，避免再复制模型与全量命令。不是改产品 Runner 模型或删除必要验证。
|
||||
验收：规则文本无固定模型/无条件全量测试/失效章节；文档任务、Go 任务、产品 PI 任务分别映射到既有验证矩阵；Cursor 实际读取入口并正确选择验证层级。静态修复与实机行为分别报告。
|
||||
时间线：2026-09-24 发现并登记；本次仅提出修复，未实施，issue 保持 open。无新 validated lesson；未验证修复不包装成经验。
|
||||
|
||||
## 5. 风险和关键设计
|
||||
|
||||
- 阶段和角色不是一对一关系：固定九名 Agent 会增加交接成本；初期三角色足够，主 Agent 可实施。
|
||||
- 只读 reviewer 无法自行写审查文件：主 Agent 转存并保留作者/ID，避免“要求只读同时要求落盘”的矛盾。
|
||||
- verifier 运行构建/测试会写缓存、数据甚至环境：单独授权，持对应租约，不能装作普通只读检查。
|
||||
- 子 Agent 默认共享目录：采用单写者；并行写另建登记 worktree，主会话的自动隔离配置不替代仓库门禁。
|
||||
- 审查和测试必须绑定版本：修复后重审受影响范围；候选变化重验；运行制品与报告提交分开。
|
||||
- 清理在验收后：唯一日志/截图先归档，owner 退出后由维护者复查，不主动删除当前使用的工作区。
|
||||
- 人工确认默认在可审方案形成后；已有端到端授权则沿用。用户未回复偏好，本草案采用该可调整默认，不把沉默当批准。
|
||||
- 模型路由和自动审批不同：Auto 不扩大业务或环境权限，普通 Cursor 不套用 Herdr 固定模型。
|
||||
- 阶段规范为 manual；文档审核通过不等于自动执行系统已实现。
|
||||
|
||||
## 6. 文档验收与未运行项
|
||||
|
||||
本次仅文档研究。静态检查结果在任务“验证与证据”节记录；检查对象为本次全部变更文件内容。
|
||||
情景自审覆盖：研究-only、简单文档、标准功能、修复回环、并行冲突、readonly 转存、子任务未知、候选变化、验收失败、清理拒绝、上下文恢复。该项是文档推演，不能作为运行负例 PASS。
|
||||
|
||||
本次未执行：Cursor Auto 真实派发、Cursor 项目角色配置安装、并行写锁实测、业务测试、产品 PI、浏览器、部署和清理。新规范的 V1–V10 实机清单是后续接入验收项。
|
||||
|
||||
## 7. 文档情景自审记录
|
||||
|
||||
审查者：Codex 主 Agent；独立性：self_review。以下为阅读草案逐项推演，结果仅表示文字路径可执行，不表示已运行客户端。
|
||||
|
||||
| 情景 | 对照位置 | 结论 |
|
||||
|---|---|---|
|
||||
| 只研究方案，未授权实现 | §2、S3 | 可交付研究，其后标不适用；不会顺推业务实现 |
|
||||
| 一处低风险文档修改 | §4、§7 | 主 Agent 自检，一份主文档可承载阶段，无需九个角色 |
|
||||
| 代码已修改但审查未回收 | S5、§5 | 不进入集成；后台结果需接收 |
|
||||
| 修复后旧审查/旧测试仍通过 | S5–S7 | 新版本需适用复核与验证，旧 PASS 不覆盖 |
|
||||
| readonly reviewer 需要报告 | §4、§7 | 子角色回传，主 Agent 在租约内转存 |
|
||||
| 测试生成缓存或写环境 | S6、§8 | verifier 可写但须明确产物范围/环境与租约 |
|
||||
| 两个子任务争用同路径 | §5 | 单写者或独立登记隔离，不能无锁并发 |
|
||||
| 子任务超时且副作用未知 | §6 | 保留 unknown，核对现场后决定恢复 |
|
||||
| 合并前 dev 已变化 | S7 | 重建候选并重新验证 |
|
||||
| 已合入但运行验收失败 | S8、S9 | 不宣布完成、不清理；修复/交接 |
|
||||
| owner 仍在 worktree 或有唯一日志 | S9、§5 | 保留现场，归档后由独立维护者复查 |
|
||||
| 会话中断后恢复 | §6、§7 | 从首个未满足门禁继续，核对未回收子任务 |
|
||||
|
||||
初次静态检查真实输出：`FILES=8 LOCAL_LINKS=84 STAGES=10 ISSUE_IDS=5 / PASS`。
|
||||
命令：`git diff --check`（exit 0）；Python 内联检查全部本次 Markdown 变更（含 untracked）的相对链接/锚点、S0–S9、规则状态字段和 issue ID 唯一性（exit 0）。不验证外部网页永久可达或实际 Cursor 行为。
|
||||
只读 `agentctl docs drift`：status=ok、regressions=[]；开放能力候选未修改，不等于产品就绪。
|
||||
|
||||
## 8. 后续决策：本机 PI 与可调整模型配置
|
||||
|
||||
用户在同一任务后续对话明确：子智能体采用 gmktec 本机 PI；仅允许 minimax-cn/MiniMax-M3、zai-coding-cn/glm-5.3、zai-coding-cn/glm-5.3-flash、qwen-token-plan-cn/qwen3.8-max、qwen-token-plan-cn/qwen3.8-flash。随后明确代码由 Cursor 实施，并因 M3 的实际使用反馈将其移出默认流程，最后确认该默认安排并要求可调整文档。
|
||||
|
||||
这些用户决策取代本报告前文 r1 中 Cursor 原生 .cursor/agents/inherit 的接入建议；前文保留为研究历史，不再作为当前实现方向。现行模型映射唯一来源为[模型配置](../ops/2026-09-24-subagent-model-config.md)，流程草案同步到 r2。没有改变 Herdr 或产品 Runner。
|
||||
|
||||
2026-09-24 再次执行 pi --offline --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files --no-approve --list-models，exit 0；精确五个 provider/model 均存在。此命令没有模型推理，不证明各角色能力或连接状态。配置字段由主 Agent 人工读取，当前不含执行器/热加载/自动校验实现。
|
||||
|
||||
## 9. 执行器已接入（后续实现）
|
||||
|
||||
用户进一步授权接入自动调用 PI 的执行器。代码提交 69ffaa677e23a1dd9aa0528bb09b3acfcd38b119，真实 Cursor CLI→MCP→PI 和 173 项工程回归通过，详情见[验证报告](../test-reports/2026-09-24-pi-executor-test-report.md)及[运行说明](../ops/2026-09-24-pi-subagent-executor.md)。前文关于未接入/未调用的说明属于当时研究阶段；当前交付范围与未覆盖项以上述新报告为准。完整流程草案审批、dev 集成和远端同步分别记录。
|
||||
+1
-25
@@ -13,30 +13,6 @@
|
||||
|
||||
## 核心文档（按阅读顺序推荐）
|
||||
|
||||
### 模块化重构方案审核检查清单（2026-09-23）
|
||||
|
||||
**文件**: [2026-09-23-modular-refactor-plan-review-checklist.md](./2026-09-23-modular-refactor-plan-review-checklist.md)
|
||||
|
||||
**结论**: 产物机器方案（`modular-contract-standard-2026-09-22`）本机不可见；本清单按已生效模块开发规范与 A–G/验证契约，覆盖阶段 1、阶段 2 与取消状态契约自查项，并留「22 条规范」映射回填。不实施业务代码。
|
||||
|
||||
**任务**: [short-term](../ops/short-term/2026-09-23-modular-refactor-review.md)
|
||||
|
||||
### 模块耦合现状（2026-09-20）
|
||||
|
||||
**文件**: [2026-09-20-module-coupling-audit.md](./2026-09-20-module-coupling-audit.md)
|
||||
|
||||
**结论**: 模块化单体与事件总线已在；残留扩散点是 server 具体类型装配、chat/app/coordinator 逻辑环、docgov 词汇泄漏，以及 2026-09-28 到期的 sql_write/path 例外。不改 `production_ready`。
|
||||
|
||||
**整改**: [分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md) · [开发规范](../system-design/2026-09-20-module-development-standards.md)
|
||||
|
||||
### 系统全量体检（2026-09-20）
|
||||
|
||||
**文件**: [2026-09-20-system-triage-audit.md](./2026-09-20-system-triage-audit.md)
|
||||
|
||||
**结论**: 迁移 00054 断链 + 三项 IDOR + taskrun channel panic + 凭证硬编码/暴露为 P0；main 分支与生产 schema 脱节记 backlog。
|
||||
|
||||
**整改**: [P0 热修方案](../remediation/2026-09-20-p0-remediation-plan.md) · [short-term](../ops/short-term/2026-09-20-p0-hotfixes.md)
|
||||
|
||||
### 可选职责空审核人 CreateOrGetDocument FK（2026-09-17）
|
||||
|
||||
**文件**: [2026-09-17-docgov-optional-duty-null-fk.md](./2026-09-17-docgov-optional-duty-null-fk.md)
|
||||
@@ -197,7 +173,7 @@
|
||||
|
||||
**结论**: 消息仍在数据库；文档任务与激活前消息缺阶段作用域，被刷新后的窗口过滤器剔除，而统计仍返回未过滤数量。
|
||||
|
||||
**整改**: [对话刷新恢复与阶段授权一致性整改方案](../remediation/2026-09-13-chat-history-refresh-remediation.md)（2026-09-22 口径裁定：gap `CHAT-HISTORY-REFRESH` = PASS；见 [reconcile](../ops/short-term/2026-09-22-chat-history-refresh-reconcile.md)）
|
||||
**整改**: [对话刷新恢复与阶段授权一致性整改方案](../remediation/2026-09-13-chat-history-refresh-remediation.md)
|
||||
|
||||
### 0️⃣ 当前状态（Live SSOT）
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
# 问题与修复台账
|
||||
|
||||
维护规则：[问题记录与开发经验闭环](../ops/2026-09-23-issue-learning-workflow.md)。每个问题一个稳定 ID；主记录是事实与状态来源，本表为可检索投影。新发现及时登记，修复后保留记录；发布 blocker 仍见 [gap-matrix](../remediation/gap-matrix.md)。
|
||||
|
||||
更新：2026-09-24。Cursor 治理层：测试规则漂移/MCP 路径改为 verifying；新登记 hook 事件契约 issue；历史 resolved 不表示本日产品回归通过。
|
||||
|
||||
| issue_id | 模块 / 检索词 | 问题 | 严重度 | issue_state | owner | 证据日期 / 范围 | 唯一主记录 | 经验 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| ISSUE-20260923-nullable-duty | docgov / nullable / 23503 / reviewer_id | 可选职责空值写 0 导致 FK 失败 | high | resolved | Codex（历史补录） | 2026-09-17；历史 PG / API 冒烟；当前未复测 | [主记录](2026-09-23-historical-issue-records.md#nullable-duty) | [LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md) |
|
||||
| ISSUE-20260923-content-hash | docrevision / canonicalize / hard-break / 404 | 规范化破坏 Markdown 语义并造成正文哈希漂移 | critical | resolved | Codex（历史补录） | 2026-09-14；历史真实 UI / 重启；当前未复测 | [主记录](2026-09-23-historical-issue-records.md#content-hash) | [LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md) |
|
||||
| ISSUE-20260923-coordination-authority | agentctl / claim / SQLite / CAS / CURRENT / FEATURE-MATRIX | 本地副本 CAS 与任务许可不能表达跨主机全局权威认领 | high | investigating | Codex（研究） | 2026-09-23；源码/只读状态，未复现具体丢写 | [主记录](../ops/short-term/2026-09-23-coordination-db-daemon-research.md#issue-20260923-coordination-authority) | 沿用 content-hash 投影经验；跨机结论待实施验证 |
|
||||
| ISSUE-20260923-matrix-status-regression | FEATURE-MATRIX / module-batches-ag / merge / docs-apply | 矩阵行 done 被 closeout 合并冲突手解回退为 planned | high | resolved | Cursor | 2026-09-23；本机 tip 与 git 考古；docs apply 已恢复 | [主记录](2026-09-23-matrix-status-regression.md) | [LESSON-20260923-matrix-status-cas](../ops/lessons/2026-09-23-matrix-status-cas.md) |
|
||||
| ISSUE-20260924-admin-reset-dead | auth / adminResetPassword / T20-F4 / chenwei | 管理台重置密码死按钮；验收口令不可知后无法恢复 | high | resolved | Cursor | 2026-09-24；test 库实查 + API 单测 | [主记录](2026-09-24-admin-password-reset-issues.md#issue-20260924-admin-reset-dead) | 待补 LESSON |
|
||||
| ISSUE-20260924-login-error-envelope | auth / AUTHZ / 无权访问 / auth.ts | 登录失败展示裸 JSON / 「无权访问」误导 | medium | resolved | Cursor | 2026-09-24；wire 复现 + 前端单测 | [主记录](2026-09-24-admin-password-reset-issues.md#issue-20260924-login-error-envelope) | 待补 LESSON |
|
||||
| ISSUE-20260924-zombie-credentials | auth / user_credentials / LEFT JOIN / CreateUser | 空哈希静默建号导致永久无法登录 | high | resolved | Cursor | 2026-09-24；三环境只读盘点；机制修复不含存量清理 | [主记录](2026-09-24-admin-password-reset-issues.md#issue-20260924-zombie-credentials) | 待补 LESSON |
|
||||
| ISSUE-20260924-cursor-test-rule-drift | Cursor / test-reports / 固定模型 / 规则副本 | Cursor 测试规则与验证契约存在固定模型及范围冲突 | medium | verifying | Cursor | 2026-09-24；规则文本已缩为验证契约指针；客户端实际读取行为待实机 | [主记录](2026-09-24-subagent-workflow-research.md#4-issue-20260924-cursor-test-rule-drift) | [LESSON-20260924-cursor-hook-advisory-gates](../ops/lessons/2026-09-24-cursor-hook-advisory-gates.md) |
|
||||
| ISSUE-20260924-pi-executor-boundaries | PI executor / 路径规范化 / MCP / 子进程 / 幂等 | 未发布初版只读边界与执行可靠性缺陷 | high | resolved | Cursor/Codex | 2026-09-24；173 工程回归与真实 Cursor CLI/MCP/PI | [主记录](2026-09-24-pi-executor-boundaries.md) | [工具路径与输入隔离](../ops/lessons/2026-09-24-pi-tool-boundaries.md) |
|
||||
| ISSUE-20260924-cursor-cli-mcp-path | Cursor CLI / MCP / workspaceFolder / NDJSON | agentctl/jev MCP 加载失败（路径 + Content-Length 回包） | medium | verifying | Cursor | 2026-09-24；相对路径+NDJSON 已修；待 IDE 重载后 list-tools 实机 | [主记录](2026-09-24-pi-executor-boundaries.md#cursor-cli-mcp-path) | [LESSON-20260924-cursor-hook-advisory-gates](../ops/lessons/2026-09-24-cursor-hook-advisory-gates.md) |
|
||||
| ISSUE-20260924-cursor-hook-event-contract | Cursor / hooks / beforeMCPExecution / probe | hook 事件 stdin 字段名与 matcher 官方未文档化 | medium | verifying | Cursor | 2026-09-24；IDE postToolUse tool_name=`MCP:pi_subagent_roles` 已采样；beforeMCP 全量 stdin 仍缺 | [主记录](2026-09-24-cursor-hook-event-contract.md) | [LESSON-20260924-cursor-hook-advisory-gates](../ops/lessons/2026-09-24-cursor-hook-advisory-gates.md) |
|
||||
| ISSUE-20260924-non-author-400-duty | iam-authz / docgov / duty / 400 / 非编制 | 权限不足误报 400；run/edit 与编制职责绑死导致成员无法上传总结写草稿 | high | resolved | Cursor | 2026-09-24；真实 PI `TestNonAuthorMember_PiAgent_RunEditSubmitGates` PASS | [主记录](2026-09-24-non-author-member-access.md) | [LESSON-20260924-deny-only-submit](../ops/lessons/2026-09-24-deny-only-submit.md) |
|
||||
@@ -16,10 +16,7 @@
|
||||
| GET /api/v1/tasks/runs/{id} | task_run | view | taskrun | 403 非 owner/非 owner 成员 |
|
||||
| POST /api/v1/tasks/runs/{id}/cancel | task_run | cancel | taskrun | 403 取消他人 |
|
||||
| POST /api/v1/chat/stream | chat | send | chat+stage | 403 无阶段权限 |
|
||||
| GET /api/v1/docgov/* | document | * | docgov+duty | view：成员；run/edit：成员（deny_only_submit）；submit/review/approve：对应职责，403 |
|
||||
| POST /api/v1/docgov/content | document | edit | docgov+member | 403 非项目成员或锁定态 |
|
||||
| POST /api/v1/docgov/submit-review | document | submit | docgov+author | 403 非编制职责人 |
|
||||
| POST /api/v1/tasks/run | task | run | bizdev+member | 403 非成员 / 非活动阶段；不再要求编制职责 |
|
||||
| GET /api/v1/docgov/* | document | * | docgov+duty | 403 非职责人 |
|
||||
| GET /api/v1/admin/* | admin | * | authz RBAC | 403 非 admin/细粒度 perm |
|
||||
| GET /health, /api/v1/health | system | health | server | 公开 |
|
||||
|
||||
|
||||
@@ -1,110 +1,94 @@
|
||||
# Herdr 多 Agent 编排 v1.2
|
||||
# Herdr Agent 角色、审批与备援 SSOT
|
||||
|
||||
更新：2026-09-21；owner：Herdr 任务协调者；本轮规范修订 `herdr-v1.2`。本文件是 Herdr 角色、额度、审批与备援的唯一来源，取代原 2026-09-13 路由。实现/核验见[任务记录](../archive/ops/2026-09-21-herdr-orchestration-v12.md)。
|
||||
**更新**: 2026-09-13
|
||||
**owner**: `orchestrator_codex`
|
||||
**status**: active
|
||||
|
||||
## 1. 生效范围与前提
|
||||
本文只管理工程协作终端，不管理产品运行时智能体。通用分支、worktree、mutex、集成槽、密钥和破坏性操作规则仍以仓库根 [AGENTS.md](../../AGENTS.md) 为准。
|
||||
|
||||
**仅在明确使用 Herdr 编排、启动或派发任务时适用本表分工。** 普通 Codex、Claude Code、Cursor 独立会话，以及仅研究/编辑本规范的任务，不自动套用 Cursor 唯一实施通道，也不自动启动多 Agent。通用授权、分支、锁、验证、清理始终遵循 [AGENTS](../../AGENTS.md) 与 [worktree 操作规范](./2026-09-21-agent-worktree-workflow.md)。
|
||||
## 1. 身份边界
|
||||
|
||||
只有 `HERDR_ENV=1` 才能查看/控制当前 Herdr 会话；外部会话可读规范、跑 dry-run 与隔离测试。用户已授权这些客户端自动通过工具请求；不为已授权步骤再等待人工批准。自动审批不产生额外环境、外部写入或破坏性操作授权。
|
||||
| 名称 | 唯一含义 | 禁止混称 |
|
||||
|------|----------|----------|
|
||||
| Herdr PI / `context_pi` | Herdr pane 内运行的 PI CLI，当前目标模型 MiniMax M3，负责工程调研与长上下文分析 | 不代表后端 runner，不作为产品 E2E 证据 |
|
||||
| 产品 PI Agent Runner | Compose/服务端调用的产品执行器；模型与验收要求见 PROJECT | 不参与 Herdr 工程任务路由 |
|
||||
|
||||
Herdr 中的 PI CLI（例如 `context_pi`）是工程协作客户端；Compose 中“产品 PI Agent Runner”是业务执行器。二者不共享验收结论，不修改产品模型配置来满足本表。
|
||||
文档、提示词和 handoff 中禁止只写“PI”；必须写 `context_pi` 或“产品 PI Agent Runner”。
|
||||
|
||||
## 2. 资源与取舍
|
||||
## 2. 稳定角色
|
||||
|
||||
订阅价格与个人额度优先级来自用户本次说明，是预算输入，不是实测余额或供应商无限量承诺。
|
||||
| 逻辑名 | 客户端 / 目标模型 | 主责 | 工作量策略 | 首选备援 |
|
||||
|--------|-------------------|------|------------|----------|
|
||||
| `orchestrator_codex` | Codex / GPT Sol 5.6 | 需求澄清、系统方案、任务拆解、调度、跨模块风险、代码终审、发布判断 | 保留推理容量，原则上不承担大批量机械实现 | `context_kimi`；关键争议才用 `reserve_claude` |
|
||||
| `implementer_cursor` | Cursor / Auto | 前后端实施、测试补齐、重构、浏览器验证、按 checklist 收口 | 主力实施席，承担最大常规工作量 | `implementer_cline` → `verifier_antigravity` → `orchestrator_codex` |
|
||||
| `verifier_antigravity` | Antigravity / Gemini 3.8 Flash | 快速只读排查、测试设计、文档核对、日志归纳、低风险小修 | 低成本高频；不得单独作安全或发布终审 | `implementer_cline` → `implementer_cursor` |
|
||||
| `context_pi` | PI CLI / MiniMax M3 1M | 全仓长上下文扫描、文档/代码交叉研究、候选清单、handoff 压缩 | 长材料首选；结论由 Codex 或 reviewer 复核 | `context_kimi` → `orchestrator_codex` |
|
||||
| `context_kimi` | Kimi Code / Kimi K3 1M | PI 备援、长文档审查、跨文件一致性检查、方案反证 | 额度有限，优先作长上下文备援而非日常实现 | `context_pi` → `orchestrator_codex` |
|
||||
| `implementer_cline` | Cline / GLM 5.3 Flash | 机械实现、测试修复、格式化、重复性迁移、Cursor 备援 | CLI 已可调用；进入主路由前需完成一次隔离 worktree 写验收 | `implementer_cursor` → `verifier_antigravity` |
|
||||
| `reserve_claude` | Claude Code / Sonnet 5 | P0/P1 架构争议、安全关键复核、Codex 失败后的第二强意见 | 额度极少，禁止日常调研、批量实现和首轮测试 | `orchestrator_codex` → `context_kimi` |
|
||||
| `reserve_devin` | Devin / 尚未接入 | 预留长任务自治席 | `standby`，不得派发 | 无 |
|
||||
|
||||
| 资源 | 用户预算 | Herdr 纪律 |
|
||||
|---|---|---|
|
||||
| Cursor Ultra | $200/月，实施优先 | 默认唯一产品代码实施通道；高额度仍监测限流/余额，不自动开启额外付费 |
|
||||
| Qwen 3.8 max/flash | 百炼最高档，充裕 | max 分析、报告、监督判断；flash 例行检查和执行已有测试 |
|
||||
| GLM 5.3/flash | 高档 token plan，充裕 | 规划、执行跟踪、代码审查；模型额度共享时不把两个客户端当两份预算 |
|
||||
| MiniMax M3 | ¥119/月，中等 | 失败归因、二线审查；每个失败问题至多两轮归因，重复失败转交带证据复核 |
|
||||
| Kimi Code | ¥699/月，个人调研/报告优先 | Herdr 默认不用；仅可选正式报告终稿检查，或有理由的应急借用；合计每逻辑任务最多一次 |
|
||||
| Codex / GPT-6 | 稀缺 | 终审仲裁、高歧义与两轮审查仍未解决的争议；不作日常监督/机械实施 |
|
||||
| agy / Antigravity | 最低档，极少 | 轻量杂活与测试想法；耗尽转 flash，不做高频轮询或安全终审 |
|
||||
模型名称来自当前工作区约定；启动脚本不猜测各 CLI 的模型别名。每次新会话由 orchestrator 在首条状态回报中确认实际模型，不一致则停止高风险任务并记录 handoff。
|
||||
|
||||
修正“Cursor 订阅不限量”：官方[用量说明](https://prod.cursor.com/help/models-and-usage/usage-limits)仍描述用量池/限制。其他“充裕”也只是调度优先级，任务开始记录 available/low/exhausted/unknown；unknown 不等于无限。价格不写进程序阈值。
|
||||
## 3. 任务泳道与自动备援顺序
|
||||
|
||||
## 3. 角色、客户端与路由
|
||||
| lane | 适用任务 | 路由顺序 |
|
||||
|------|----------|----------|
|
||||
| `governance` | 方案、拆解、跨模块决策、普通 review | Codex → Kimi → Cursor → Claude |
|
||||
| `critical-review` | 鉴权、安全、迁移、发布 blocker 终审 | Codex → Claude → Kimi |
|
||||
| `implementation` | Go/React/SQL 实施与测试 | Cursor → Cline → Antigravity → Codex |
|
||||
| `ui` | React、交互、Playwright | Cursor → Antigravity → Cline |
|
||||
| `test` | 单测、集成测试、失败定位 | Cursor → Cline → Antigravity |
|
||||
| `fast-check` | 日志、静态核对、文档一致性、小修 | Antigravity → Cline → Cursor |
|
||||
| `long-context` | 全仓/全量文档审读、证据汇总 | PI → Kimi → Codex |
|
||||
|
||||
模型路由基于本机帮助和已配置别名，启动后还须确认实际模型。`pi --list-models` 只证明配置目录可识别，不证明账户余额、远端可用或本任务真实输出质量。
|
||||
Claude 只在 `critical-review` 中作为前排备援；其他 lane 放在最后或不进入路由，以保护额度。Codex 的实现兜底只用于阻塞交付的关键路径。
|
||||
|
||||
| 角色 / lane | 默认 → 备援 | 交付边界 |
|
||||
|---|---|---|
|
||||
| 例行监督 `supervision` | qwen_flash → qwen_max → verifier_antigravity | 读任务/测试/锁状态；阻塞判断交 max，僵局显式 critical-review |
|
||||
| 需求分析 `analysis` | qwen_max → qwen_flash | 可验收需求、歧义、边界；高歧义显式终审升级 |
|
||||
| 规划 `planning` | reviewer_glm → qwen_max → glm_pi | 步骤、依赖、允许写范围、测试计划 |
|
||||
| 执行计划 `execution` | reviewer_glm → qwen_max | 调度、跟踪、核对产物；不与实施者同时改产品代码 |
|
||||
| 实施 `implementation` / `ui` | implementer_cursor | 可运行改动、回归测试；仅明确写入接管理由时追加 reviewer_glm → qwen_max |
|
||||
| 代码审查 `code-review` | reviewer_glm → context_pi | 对冻结 diff 独立审查；两轮未过显式 critical-review |
|
||||
| 系统测试 `test` | qwen_flash → verifier_antigravity | 执行确定性测试命令；不能以“模型判断通过”替代进程退出码与断言 |
|
||||
| 失败归因 `test-analysis` | context_pi → reviewer_glm | 可重现输入、原因、最小修复建议；修复回实施通道 |
|
||||
| 报告 `report` | qwen_max → qwen_flash | max 写交付稿；flash 仅草稿，须回 max 定稿 |
|
||||
| 报告二审 `report-review` | reviewer_glm | max 自审后，GLM 独立查来源/逻辑/未验收声明 |
|
||||
| 可选终稿 `report-final-check` | context_kimi | max 完成正式交付稿后，至多一次，非每任务必经 |
|
||||
| 终审 `critical-review` | orchestrator_codex → reviewer_glm | GPT-6 仲裁；GLM 若是原作者/审查者须独立上下文并补跨模型复核，未解决风险保留 blocked |
|
||||
| 轻量杂活 `fast-check` | verifier_antigravity → qwen_flash | 小范围静态核对和整理 |
|
||||
| 长材料 `long-context` | qwen_max → glm_pi | 相关证据扫描，不默认占 Kimi |
|
||||
| 特例借用 `quota-emergency` | context_kimi | 百炼等故障、任务确需借个人额度；与终稿入口共用一次计数 |
|
||||
## 4. 自动派发和接管协议
|
||||
|
||||
兼容旧 lane `governance` 转到规划 GLM → max，已移除日常 Codex/Kimi 路由。Cline、Devin 和旧 `reserve_claude` 不在 v1.2 活跃路由；Claude Code 是客户端名称，本机路由到 GLM，不把它算作另一份 Claude 高端模型额度。
|
||||
1. Orchestrator 先创建 short-term、认领 mutex、建立独立 worktree；之后才启动或选择 agent。
|
||||
2. 实例必须使用上表逻辑名，且 `cwd` 必须与任务 worktree 完全相同。派发器不会占用名称不规范或其他目录的实例。
|
||||
3. 只向 `idle` / `done` 实例投递。同一 mutex 同时只允许一个执行者写入。
|
||||
4. 以下情况可自动尝试下一个备援：实例不存在、启动前已 blocked、认证失败、明确额度耗尽、客户端在写入前失败。
|
||||
5. Agent 只有在尚未写文件、未运行有副作用命令时，才可返回派发器给出的本次唯一 `HERDR_RETRY:<dispatch-id>:<reason>` 行触发降级。
|
||||
6. `timeout`、`agent_prompt_stalled`、`unknown` 或无终态标记均不能证明任务未执行；派发器必须停止，不得盲目重投。先读取 pane，必要时写 handoff。
|
||||
7. 接管前确认原实例不再 `working`；有部分改动时由原实例或 orchestrator 写 handoff，备援串行续作，不得并发覆盖。
|
||||
8. Review 可由不同 worktree 的多个只读实例并行；写任务仍受 mutex 单写者约束。
|
||||
|
||||
| profile | 标准逻辑名 | 启动选择 |
|
||||
|---|---|---|
|
||||
| claude | reviewer_glm | Claude Code `--model opus`，本机 Opus 别名配置为 GLM 5.3；不修改全局配置 |
|
||||
| codex | orchestrator_codex | 默认已配置 GPT-6；仅角色名称兼容旧脚本，其职责收窄为终审 |
|
||||
| cursor | implementer_cursor | cursor-agent 的已配置模型 |
|
||||
| pi-max | qwen_max | qwen-token-plan-cn / qwen3.8-max |
|
||||
| pi-flash | qwen_flash | qwen-token-plan-cn / qwen3.8-flash |
|
||||
| pi-glm | glm_pi | zai-coding-cn / glm-5.3 |
|
||||
| pi | context_pi | minimax-cn / MiniMax-M3 |
|
||||
| kimi | context_kimi | Kimi Code 已配置模型 |
|
||||
| antigravity | verifier_antigravity | agy 已配置模型 |
|
||||
## 5. 自动审批不是无限授权
|
||||
|
||||
独立上下文审查有价值，但规划和审查都用 GLM 仍可能同源盲点；高风险争议增加 MiniMax/GPT-6 跨模型意见。简单任务采用“实施 → 验证/审查 → 收口”最短路径，不强制走九个角色；大任务按依赖拆分，最多一个产品代码写者/重叠范围，独立 worktree 可并行。
|
||||
统一入口为 [`scripts/herdr-agent-start.sh`](../../scripts/herdr-agent-start.sh)。当前安装版本验证过的参数如下：
|
||||
|
||||
## 4. 预算闸门
|
||||
| profile | 自动审批参数 | 保留的边界 |
|
||||
|---------|--------------|------------|
|
||||
| Claude | `--dangerously-skip-permissions` | 仍受本规范和任务提示约束 |
|
||||
| Codex | `--ask-for-approval never --sandbox workspace-write` | 保留 workspace 沙箱；失败回传模型，不询问人工 |
|
||||
| Cursor | `--force --sandbox enabled --approve-mcps --trust` | 保留 Cursor 沙箱和显式 deny |
|
||||
| Antigravity | `--dangerously-skip-permissions --sandbox` | 保留其终端沙箱 |
|
||||
| PI | `--approve` | 信任项目本地文件；该 CLI 没有独立的逐工具审批开关 |
|
||||
| Kimi | `--auto` | Never Ask 模式 |
|
||||
| Cline | `--tui --auto-approve true` | 所有工具自动批准 |
|
||||
|
||||
- 每任务记录一个不可随子任务/重试变化的 task_id、角色调用、升级原因、审查/归因轮次、实际来源与结果。轮询优先直接读机器状态，只在状态改变或阻塞时调用模型。
|
||||
- Kimi 默认不进入普通分析、代码审查、测试归因或报告撰写备援。协调者在既有授权内判断是否值得调用，显式填 `--kimi-reason`，不用再向用户索取工具批准。
|
||||
- 派发器在发送前向主仓 `.locks/state.sqlite` 的 `herdr_kimi_uses` 原子登记；同一 task_id 两个入口合计 ≤1。发送失败/结果未知也占用，不自动退款，不通过新 task_id 重置。此计数是一次投递，不是模型内部工具轮数或真实账单 token 上限；输入只含最终稿/必要来源，禁止继续发多轮 Kimi。
|
||||
- 个人调研额度告急时，协调者在主仓 `.locks/herdr-kimi.disabled` 留停用标记，所有后续受管 Kimi 派发拒绝；确认恢复后移除此标记。它不控制个人在 Herdr 之外的 Kimi 主业，也不能自动读取个人用量。
|
||||
- Kimi 停用：max 自审 + GLM 二审。GPT-6 耗尽：GLM 复核；仅交付文档可以用尚未使用的 Kimi 终稿检查，不能拿文稿检查顶替代码安全/发布终审。百炼故障先用 GLM/MiniMax 支撑，确需 Kimi 才借用；故障消除即回原通道，不形成新默认。
|
||||
- 机器强制范围是统一派发入口的一次计数；直接在 Kimi pane 手工发问可绕过，禁止据此声称全账户硬限额已完成。MiniMax 轮次/GPT 升级由任务记录管理，尚无跨供应商余额 API。
|
||||
即使客户端不弹确认框，Agent 也不得自行执行：删库/清空数据、强推、删除主干或 worktree、停止 Herdr server、覆盖其他 Agent 未合并改动、泄露密钥、未获用户授权的外部写入。需要新权限时写 handoff/blocker，不把确认框转交给用户逐条点击。
|
||||
|
||||
## 5. 自动通过请求与实际启动
|
||||
## 6. 操作入口
|
||||
|
||||
所有 Herdr 启动均走 [start](../../scripts/herdr-agent-start.sh)；仅影响该次进程参数，**不改个人客户端的全局审批设置**。以下来自本轮安装 CLI `--help`，不是猜测同名产品能力。
|
||||
|
||||
| 客户端 | 参数 | 说明 |
|
||||
|---|---|---|
|
||||
| Claude Code | `--dangerously-skip-permissions --model opus` | 自动通过工具权限，使用用户已配置 GLM 别名 |
|
||||
| Codex | `--ask-for-approval never --sandbox danger-full-access` | 不再等待批准；授权内操作仍须 agentctl/Git 门禁 |
|
||||
| Cursor | `--force --sandbox disabled --approve-mcps --trust` | Run Everything + MCP 自动批准 + workspace trust；显式 deny 仍有效 |
|
||||
| agy | `--dangerously-skip-permissions` | 自动通过工具请求，不再添加旧脚本的限制性 sandbox |
|
||||
| PI CLI | `--approve` + 明确 provider/model | 内置工具本就无逐工具弹窗；该参数处理项目文件信任，不能说它关闭了不存在的权限系统 |
|
||||
| Kimi | `--auto` | Never Ask；`--yolo` 仍可能询问，不替代 auto |
|
||||
|
||||
[Cursor 参数](https://cursor.com/docs/cli/reference/parameters)、[Kimi 参数](https://www.kimi.com/code/docs/en/kimi-code-cli/reference/kimi-command)、[Claude 参数](https://code.claude.com/docs/en/cli-reference)与本机帮助一起核对。CLI 升级后先重新核验 flags；外部认证、显式 deny、企业策略或扩展交互无法由统一参数保证消失，失败写 blocker，不反复向用户弹批准，不擅自清除已有安全规则。
|
||||
在任务 worktree 的 Herdr pane 中启动标准实例：
|
||||
|
||||
```bash
|
||||
# 先用 agentctl 注册 task-id。名称可用 base__短任务后缀，完整长度最多 32。
|
||||
./scripts/herdr-agent-start.sh --dry-run pi-max qwen_max__demo w1:p2
|
||||
./scripts/herdr-agent-start.sh --task task-id pi-max qwen_max__demo w1:p2
|
||||
./scripts/herdr-agent-dispatch.sh --explain report
|
||||
./scripts/herdr-agent-dispatch.sh --task task-id report '根据已提交证据撰写报告'
|
||||
./scripts/herdr-agent-dispatch.sh --task task-id --kimi-reason '正式报告的一次终稿核验' report-final-check '核验最终稿与来源'
|
||||
./scripts/herdr-agent-dispatch.sh --task task-id --implementation-fallback 'Cursor 额度已耗尽，已核对无在途写入' implementation '接续已登记范围'
|
||||
./scripts/herdr-agent-start.sh codex orchestrator_codex <pane-id>
|
||||
./scripts/herdr-agent-start.sh cursor implementer_cursor <pane-id>
|
||||
```
|
||||
|
||||
启动/派发仅接受注册任务的直接 `.worktrees` 工作区；目标 pane/agent cwd 必须匹配。标准名后缀支持不同任务同时有自己的同角色 Agent；同任务同角色出现多个可用实例时拒绝歧义。旧命名实例先由其 owner 完成/交接，不自动抢占、改名或停止。
|
||||
预览某泳道路由，或自动投递：
|
||||
|
||||
## 6. 监督、失败、恢复与交接
|
||||
```bash
|
||||
./scripts/herdr-agent-dispatch.sh --explain implementation
|
||||
./scripts/herdr-agent-dispatch.sh implementation "读取任务文并完成已认领范围，验证后写 handoff。"
|
||||
```
|
||||
|
||||
1. 协调者读取任务与本规范，确认预算、角色、分支、允许写路径、实际客户端/模型和精确 head。启动后核验身份；标准名字只能表达意图，不能证明客户端模型没被手工切换。
|
||||
2. Herdr 的新 pane 不是 `agentctl with` supervisor 的子进程；禁止把短命令租约凭据复制进去。worker 按每条写命令取自己的任务 path 租约，提交另取 git:index；共享 CURRENT/MATRIX 用 docs apply。监督者不长期持有所有资源锁。
|
||||
3. 只投递同任务的 idle/done Agent；已工作/blocked/unknown 不发第二份。等待最多 60 秒；超时只观察，不把超时当未执行或自动终止任务。
|
||||
4. 已选实例的 prompt RPC 出错统一视为可能已发送，不根据输出里出现 quota/auth 字样自动转发。只有已 settled 且返回本轮唯一 HERDR_RETRY 标记、明确未写入/无副作用时才可备援；仍是合作协议，不是任意工具副作用的机器证明。
|
||||
5. 不抢主目录、不切他人分支、不覆盖旧 CURRENT；合入/环境验收由独立协调者按机器锁串行处理。模型返回“完成”不等于测试通过或 dev 已部署。
|
||||
6. 每次交接含冻结 SHA、改动范围、实际验证/缺项、未完成副作用、下一执行者与预算用量。owner 退出并确认文件/进程/祖先证据后再清理；异常现场保留 cleanup_pending，不强删。
|
||||
派发器只处理规范命名且已在线的实例，不擅自创建 pane、不重启 agent、不抢集成槽。缺少实例时由 orchestrator 用启动脚本补齐。
|
||||
|
||||
## 7. 当前可用性基线
|
||||
|
||||
2026-09-13 现场基线：Herdr client/server 0.9.0、协议 22；Claude/Codex/Cursor/Antigravity/PI/Kimi 集成已安装且 current；Cline CLI 3.0.61 可调用，但尚无在线标准命名实例；Devin 尚未接入。在线状态是瞬时信息，派发前必须重新运行 `herdr agent list`。
|
||||
|
||||
@@ -1,154 +0,0 @@
|
||||
# Agent worktree 与 L1 操作规范
|
||||
|
||||
**修订**：`agent-governance-2026-09-21-r1`。来源：[AGENTS](../../AGENTS.md)、[规范登记](./2026-09-21-policy-registry.md)。工具为 `scripts/agentctl`（Python 标准库，macOS/Linux 双平台），协议 v1；实际安装与验证见[实施任务](../archive/ops/2026-09-21-agent-governance-implementation.md)。
|
||||
|
||||
本规范约束合作 Agent 的统一操作入口和 Git 提交/引用门禁。任意同 UID shell、修改管理器或跳过 hooks 仍可绕过；不把 L1 宣称为 OS 沙箱。共享服务配置与产品数据库不属于任务素材。
|
||||
|
||||
## 1. 首次启用与旧锁兼容
|
||||
|
||||
由获授权协调者在干净主目录 dev 执行一次：
|
||||
|
||||
```bash
|
||||
./scripts/agentctl init
|
||||
./scripts/agentctl hooks install
|
||||
./scripts/agentctl doctor
|
||||
```
|
||||
|
||||
`init` 只在主目录运行；明确初始化主仓唯一 `.locks/state.sqlite` 和身份文件，不能从 linked worktree 自动建立第二套状态。现有 `.git/agent-control/dev-integration.lock` 保留，用硬链接使 `.locks/os/dev-integration.lock` 指向同一 inode；旧操作未结束、旧锁忙或新旧身份不符均拒绝迁移。状态目录整体被 Git/Docker 忽略，禁止自行删锁/删库/复制 WAL/重建空目录。
|
||||
|
||||
`status`、`doctor` 只读，未初始化返回结构化错误而不创建文件；每次打开管理库都会核对旧新 dev 锁身份。`hooks install` 拒绝覆盖外来 hook 或既有自定义 hooksPath；不能把别人的保护脚本直接替换掉。启用前必须完成主目录集成，并让旧任务在下一次写/集成前读取本修订。
|
||||
|
||||
## 2. 创建任务并登记范围
|
||||
|
||||
从任一同仓工作区使用已验证工具：
|
||||
|
||||
```bash
|
||||
./scripts/agent-worktree.sh create feature/task-id
|
||||
# 输出 worktree 路径和本次实际 base_dev_sha；所有新任务显式来自当前 dev。
|
||||
cd .worktrees/task-id
|
||||
../../scripts/agentctl task register --id task-id --owner Codex --scope internal/example --scope .doc
|
||||
```
|
||||
|
||||
示例名称、范围应替换为实际 task_id 与最小写范围；要维护 CURRENT 自己的行，task_id 与该行 task 字段一致。工具定位唯一主仓，不在任务区嵌套 `.worktrees`。分支只接受 `feature/<task-id>` 或 `fix/<task-id>`，重名/路径占用/符号链接均拒绝。旧目录清理由 Git 真实映射定位，不按名字猜测。
|
||||
|
||||
任务登记保存 owner、分支、worktree、源提交、允许写路径和能力；不隐式扩展已有登记。任务 scope 是允许范围，实际写许可由每次 `with` 获取。文件路径为仓库相对路径或目录前缀，`.` 表示全仓源文件范围，仅供明确需要的治理/集成任务；不能登记 `.git`、`.locks` 或运行数据作为源码写范围。
|
||||
|
||||
特殊能力按任务授权登记，例如 `--capability docs:publish`、`git:dev`、`env:dev`；test/main/shared 能力不能由普通 dev 任务顺带申请。能力字段记录的是已授予的任务边界，不自行产生用户授权。
|
||||
|
||||
## 3. 写操作与长驻客户端
|
||||
|
||||
```bash
|
||||
# 每次命令包裹完整操作；不是先拿一次 fd 锁，再换一个 shell 假定仍持有。
|
||||
../../scripts/agentctl with --task task-id --resource path:internal/example -- <command> <args>
|
||||
|
||||
# Git 暂存/提交用同一 supervisor 包住，另持任务自身的 index 锁。
|
||||
../../scripts/agentctl with --task task-id --resource path:internal/example --resource git:index -- <git-write-script>
|
||||
```
|
||||
|
||||
`with` 可包裹任务客户端或包含多条命令的受控脚本；不必由模型手工续租。它是非重入操作锁：不在持有某资源的 child 中再次申请同一资源。长期 worker 只持实施路径，不长期占共享文档/集成资源；提交、共享文档更新和 task close 由协调者在 worker 退出后以新的短操作完成。需要自主逐步提交的客户端使用逐命令 `with`，不套全任务的大锁。默认 child cwd 为登记的任务 worktree，只有明确环境/集成操作可选择主目录。代码审查、查询或读取不可变 Git 快照不必持写锁。`--shared` 仅供稳定读取，不能通过写操作 guard。
|
||||
|
||||
锁资源支持目录层级冲突；多个资源一次申请、全部获准才启动 child。同任务不同路径可并发；index 单独排他。每个执行器持工作区生命周期 SH 锁，删除必须取得 EX，防止检查完清理后又进入新任务。`--wait` 为有限秒数，默认立即拒绝冲突；失败给 request_id/holder，可做不冲突工作或用原 request_id 重试。没有后台无限排队服务，也不需要常驻产品容器。
|
||||
|
||||
会话身份包含 PID/start-time/boot、操作代次与 epoch；继承凭据只对真实 supervisor 的子孙进程有效。锁不会因超时自动转给别人；异常进程和未完成 operation 保留恢复状态。SIGINT/SIGTERM、孤儿子进程和未完成文档写回按实现的恢复门禁处理。
|
||||
|
||||
## 4. 共享文档：短锁、行版本和写回收据
|
||||
|
||||
当前提供 CURRENT 与 FEATURE-MATRIX 的受控更新；普通任务只改 CURRENT 中自己的 task 行，不能覆盖别人的状态或自行释放槽位。模块行使用现有唯一模块名称定位；重复/歧义 ID 拒绝。发布入口不是对旧文件的整份覆盖。
|
||||
|
||||
```bash
|
||||
../../scripts/agentctl docs snapshot --file .doc/ops/CURRENT.md --record task-id
|
||||
../../scripts/agentctl docs apply --task task-id --request /tmp/task-state-delta.json
|
||||
```
|
||||
|
||||
请求格式（示意，hash 使用 snapshot 的实际结果）：
|
||||
|
||||
```json
|
||||
{"request_id":"task-id-state-1","changes":[{"file":".doc/ops/CURRENT.md","record_id":"task-id","expected_sha256":"<old-row-hash>","replacement":"| Codex | task-id | feature/task-id | .worktrees/task-id | module | in_progress |"}]}
|
||||
```
|
||||
|
||||
新增行使用 `expected_sha256: null`。必须登记目标文件 scope 和 `docs:publish` 能力。工具在同一个短租约中重新读取、行级 CAS、保留其他内容、记录 operation、原子替换并保存文件 hash 收据。同一 request_id 同一请求重放不会重复写；更换载荷不能复用 ID。存在未经管理的本地共享文档改动时拒绝将它们混入收据，先保留现场并对齐正确基线。
|
||||
|
||||
多个文档先全部预检再写；中断留下可恢复的前后内容，不能把两个 rename 声称为任意文件读取者的一次原子发布。以同一 Git 提交作为持久发布边界。文件正常更新后，在自己的 task worktree 持对应 path + git:index 租约暂存/提交；hook 检查暂存文件 hash 与已生成收据一致。
|
||||
|
||||
FEATURE-MATRIX 从未完成升为 done 需要 `docs:approve` 和已在该任务 HEAD 提交的 `evidence` 路径，不能因任务退出自动关闭能力。仅有工具日志不等于产品验收。文档布局/焦点维护使用显式 `docs:admin` 与 `record_id: "@document"` 的整文档 hash CAS；它不能修改 CURRENT 集成槽位，也不能绕过模块完成证据规则。普通任务没有此入口权限。
|
||||
|
||||
## 5. 验证与候选集成
|
||||
|
||||
按[验证契约](./2026-09-21-validation-contract.md)选真实检查。工程工具自测入口：
|
||||
|
||||
```bash
|
||||
python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v
|
||||
```
|
||||
|
||||
冻结待交付提交 T。从最新 dev D 创建独立 `feature/integrate-<id>` 候选工作区并登记，合并 T 形成 `--no-ff` 节点 M；候选的两名父提交中第一名必须是 D。发生业务冲突回原任务修复。
|
||||
|
||||
```bash
|
||||
# 在候选工作区：登记 candidate-id、实际写范围和 git:dev 能力。
|
||||
../../scripts/agentctl validate --task candidate-id -- <verification-command> <args>
|
||||
../../scripts/agentctl integrate --task candidate-id --expected-dev <D>
|
||||
```
|
||||
|
||||
validate 要求干净树、记录精确 HEAD 与命令摘要；必要的实际命令/测试输出仍保存在任务验收证据。不能拿 `true` 替代验证契约。integrate 要求对应验证收据、干净主目录 dev、基线仍为 D，再接收同一 M；dev 前进则重建候选并重验，不能重用陈旧 PASS。
|
||||
|
||||
本地 hooks 检查主干直接提交、task 身份、暂存 scope/实际租约、共享文档收据与敏感运行路径；引用事务门禁复用同一候选父节点和 task-bound 验证检查；dev 还要求由 integrate 创建、绑定 old/new 的操作身份，不能借 with 的租约直接快进或 update-ref 绕过。test/main 仍需要各自明确授权的候选与能力。所有管理工具始终以主仓已生效版本为准，旧 worktree 的旧脚本不能代表新协议已接入。
|
||||
|
||||
## 6. 共享服务与镜像
|
||||
|
||||
```bash
|
||||
# task 已获 env:dev；从主目录执行，源码须干净。
|
||||
./scripts/agentctl with --task task-id --resource env:dev --cwd <main-root> -- ./scripts/env-service.sh dev rebuild
|
||||
```
|
||||
|
||||
服务写动作在任何配置创建、网络或 Docker 调用前检查：调用目录与脚本目录都属于主目录、主分支为 dev、当前执行身份与目标环境租约有效。`all` 必须显式持有四个环境资源；不为方便隐式扩大权限。`status/ps/logs` 不初始化 env/data，也不要求写租约。
|
||||
|
||||
`candidate-images-build.sh --commit SHA` 要求实际源码 HEAD==SHA 且源码干净；仅允许现有 nightly 的固定 promotion-receipts 目录内未跟踪证据。它从该提交 `git archive` 到私有临时目录，Dockerfile 和上下文均来自不可变导出，不读取随后被其他操作修改的工作树或未跟踪证据。清单记录 source_tree/source_context；临时目录在退出时删除。镜像清单通过临时文件/fsync/rename 发布，避免截断 receipt 被当作完整证据。制品与报告版本分别记录；restart 不是新代码部署证明。
|
||||
|
||||
影响产品运行的变更合入后按授权更新 dev，核对实际镜像、挂载、schema、health/ready 与受影响业务。普通工程规范与本地治理工具更新无需重建产品容器。使用共享 dev 的长 E2E 持有环境租约到结束，不能让另一部署改变验收对象。
|
||||
|
||||
## 7. 查询、恢复与冻结
|
||||
|
||||
```bash
|
||||
./scripts/agentctl status
|
||||
./scripts/agentctl operation <run-id>
|
||||
./scripts/agentctl recover --run <run-id> --reason '<现场检查与恢复依据>'
|
||||
```
|
||||
|
||||
已结束且结果明确的请求可按 ID 查询；busy 不证明旧操作死亡。recover 仅在原 supervisor 和子进程组均已消失、物理锁可获得时继续；文档现场必须匹配该 operation 的原/目标内容，第三方变化则停止。外部 Docker/Git 未知结果必须先核对现场，理由写入恢复记录；管理器不能自动撤销已经发生的外部副作用。
|
||||
|
||||
必要维护可用 freeze/unfreeze 对已授权资源显式冻结，带 task 与 reason；有效持有者也不能绕过冻结。不能删除锁文件“解锁”，也不能恢复一份旧库后把旧租约自动标 active。损坏、身份变化、文件系统异常时停止受保护写入并交接。
|
||||
|
||||
## 8. 收口与清理
|
||||
|
||||
任务状态、集成、部署、远端同步和 cleanup 分别记录，见[收口清单](./templates/session-close-checklist.md)。命令结束不等于任务完成；task close 会拒绝仍有运行或待恢复 operation 的任务。
|
||||
|
||||
### 8.1 只读盘点（先盘点，再人工处置）
|
||||
|
||||
```bash
|
||||
# 批量 worktree 清理就绪度；verdict=ready 才可考虑 remove。从不自动删除。
|
||||
./scripts/agentctl cleanup report
|
||||
|
||||
# FEATURE-MATRIX 状态漂移：硬告警仅 done→非 done（ISSUE-20260923 工具化）；
|
||||
# open_capabilities 为人工判断候选。从不自动升 done / 写 MATRIX。
|
||||
./scripts/agentctl docs drift
|
||||
```
|
||||
|
||||
daemon 前台循环可按 `--audit-every N`（默认 30）周期跑上述盘点；**不在 daemon 内调用 `docs apply`**（主目录 cwd 必 `WORKTREE_MISMATCH`）。常驻 systemd/launchd 装载需独立授权，本规范默认不装载。
|
||||
|
||||
### 8.2 关闭与删除
|
||||
|
||||
```bash
|
||||
./scripts/agentctl task close --id task-id --status done
|
||||
./scripts/agent-worktree.sh remove feature/task-id --delete-branch
|
||||
```
|
||||
|
||||
清理由目录外的维护者执行，核对实际 Git 映射、dev 祖先、所有证据、tracked/untracked/ignored 文件、未完成 Git 操作、registry、生命周期锁和使用目录的进程。只用普通 remove/-d，拒绝时保留 cleanup_pending 和复查责任，不换成强制删除。盘点只读；删除仍人工；拒绝即保留 cleanup_pending。
|
||||
|
||||
**本机限制**：无法读取某些同 UID 进程 cwd 时，工具不能证明其未使用目录，故保留 cleanup_pending；明确识别的 OS 用户 launchd（macOS）/systemd（Linux）管理进程有诊断性例外。进程 cwd 可见性走双路径：Darwin 用 `lsof`，Linux 用 `/proc`；测试中的删除正例可替换对应枚举以模拟可见主机，其余 Git/锁/文件条件为真实执行；可见占用、未知不可读、未合入、脏文件与活跃登记的拒绝另有真实/针对性测试。不要把这项限制转成跳过检查的通用开关。
|
||||
|
||||
保护任务、旧 detached 工作区和非本次产物不自动清理。用户未要求 push 时仅本地提交/合入；用户已要求时再按授权同步并核对远端引用。
|
||||
|
||||
### 8.3 CodeGraph（治理加速器）
|
||||
|
||||
- `agentctl init` 与 `agent-worktree.sh create` 会 best-effort 初始化/同步 `.codegraph/`（CLI 缺失则跳过，不阻断）。
|
||||
- `hooks install` 安装 `post-merge` / `post-checkout` → `hooks codegraph-sync`（fail-open，永不阻断 integrate）。
|
||||
- 会话启动执行 `codegraph sync -q`。索引是 tree-sitter **近似**：有假阴性；**grep 是完整性唯一权威**；重命名与穷举调用方必须 grep 确认。
|
||||
@@ -1,67 +0,0 @@
|
||||
# Agent 规范来源与生效登记
|
||||
|
||||
## 生命周期与权威
|
||||
|
||||
`proposed → approved → active → deprecated` 是规则生命周期；与任务的 `planned/in_progress/blocked/done/cancelled` 分开。`manual/enforced` 是工具执行能力，独立于规则状态。规则获批准不证明脚本已经强制执行。
|
||||
|
||||
本轮修订 ID：`agent-governance-2026-09-21-r1`。owner：`orchestrator_codex`。批准依据：[规范审查](../audit/2026-09-21-agent-policy-review.md) R01–R10 与用户后续实施授权，具体授权回链由[实施任务](../archive/ops/2026-09-21-agent-governance-implementation.md)保存；审查原文保留历史“待采纳”语境，不改写成执行证据。
|
||||
|
||||
本轮规则已通过 `7e9317b849e0696e110bac5b27749861178d7e3d` 合入 dev 并为 `active`；**包含本修订的受控 dev 集成提交**是 `effective_commit`，从该提交进入 dev 后为 `active`。集成者在实施任务记录完整 SHA 与验证证据，避免自引用提交散列。读取时先核对该集成提交是否为当前 dev 祖先；尚未集成的规则不能冒充全仓已生效。任务记录读取的 dev SHA 和修订 ID；旧任务集成前比较规则变化，只按已生效规则补齐适用条件。
|
||||
|
||||
| 唯一来源 | 范围 | 本轮 revision/state | owner | 生效提交 |
|
||||
|---|---|---|---|---|
|
||||
| [AGENTS](../../AGENTS.md) | 任务分级、授权、安全、Git/收口硬边界 | r1 / active | orchestrator_codex | 本修订 dev 集成提交 |
|
||||
| [PROJECT](../../PROJECT.md) | 仓库地图、环境、工具与模块入口 | r1 / active | orchestrator_codex | 同上 |
|
||||
| [验证契约](./2026-09-21-validation-contract.md) | 测试范围、精确 PI 用例与报告 | r1 / active | orchestrator_codex | 同上 |
|
||||
| [worktree 操作规范](./2026-09-21-agent-worktree-workflow.md) | 创建、租约、共享文档、候选、环境、恢复、清理 | 本轮更新 active；既有规则按历史集成记录 | orchestrator_codex | 本轮实施任务及既有历史交接 |
|
||||
| [Herdr roster](./2026-09-13-herdr-agent-roster.md) | 角色与备援；实际模型/可用性须重新核验 | 既有规则 active；本轮澄清 active | orchestrator_codex | Git 历史及本轮实施任务 |
|
||||
|
||||
客户端入口仅指向上述来源；不独立制定第二套测试、提交或凭证规则。外层系统约束及当前用户授权优先，内部冲突按 AGENTS 硬边界、PROJECT 项目细则、专门操作流程的职责解决；仍无法同时满足时记录冲突并请求范围决策。
|
||||
|
||||
## 能力与证据登记
|
||||
|
||||
具体工具版本、已验收能力与不覆盖范围由 [操作规范](./2026-09-21-agent-worktree-workflow.md) 和实施任务中的真实负例验收记录定义。文档/脚本存在不等于 `enforced`：只有指定版本入口及其测试证明的边界可记 enforced。普通 prose、未接入 hooks、绕过入口的直接文件修改、跨机器权限隔离不得因此声称已被强制。
|
||||
|
||||
CURRENT 是带时间的活跃协调快照；Git/机器状态用于核验实际分支、锁与进程，FEATURE-MATRIX 是能力声明，gap-matrix 是发布门禁。审计、方案、历史报告和较新日期均不能自行覆盖上述权威。保留每条结论的范围、提交、环境与日期，避免把旧的通过结论当作当前运行事实。
|
||||
|
||||
## Herdr v1.2 局部修订
|
||||
|
||||
用户已授权采纳经研究修正的资源分工与自动审批。Herdr roster 的角色/额度/客户端参数由 `herdr-v1.2` 取代旧路由，仅在明确使用 Herdr 时激活，不扩展通用会话工作流。具体来源、验证与生效集成见[本轮任务](../archive/ops/2026-09-21-herdr-orchestration-v12.md)。已通过 dev 合并提交 `8c5e3477585fe27a485343dac97a670d95cf8905` 生效；profile/dry-run、入口保护和 Kimi 原子计数有隔离验收，真实 Herdr pane 启动未在本轮执行，不将其记为已实测。
|
||||
|
||||
## 系统问题分析局部修订
|
||||
|
||||
修订 ID：`systemic-issue-analysis-2026-09-23-r1`；owner：`Codex`；state：`active`（已通过 `958dd44fee8bbea8d19129457fc0ad749fdebdbe` 合入 dev）；工具能力：`manual`。用户明确要求将“由个案追查同类根因、潜在问题，研究并提出方案”加入规范，授权与验证见 [任务记录](./short-term/2026-09-23-systemic-issue-analysis.md)。
|
||||
|
||||
核心行为唯一来源为 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求)，验证范围由 [验证契约](./2026-09-21-validation-contract.md#问题修复的回归范围) 定义，[分析模板](./templates/audit-note.md) 承载证据。客户端继续引用统一入口。生效提交为 `958dd44fee8bbea8d19129457fc0ad749fdebdbe`，候选验证与受控集成收据见任务记录；不新增业务实施或环境操作授权。
|
||||
|
||||
## 问题记录与经验复用局部修订
|
||||
|
||||
修订 ID：`issue-learning-2026-09-23-r1`；owner：Codex；state：`active`（已通过 `7bbd7a407f857515005c0324d90339017ea5f3e8` 合入 dev）；执行能力：`manual`。用户要求同时管理出现的问题、修复记录和思路，并及时总结为开发注意事项，授权与验证见 [任务](short-term/2026-09-23-issue-learning.md)。
|
||||
|
||||
[闭环规范](2026-09-23-issue-learning-workflow.md) 为本流程唯一来源；AGENTS 增加按任务触发的读取/更新入口，模板承载证据，问题台账和经验索引提供检索。生效提交为包含本修订的首个受控 dev 集成提交，以任务收据与 Git 父链核实；未合入不能声称全仓生效。此修订不新增产品功能、自动门禁或运行权限。
|
||||
|
||||
## CodeGraph 与只读盘点局部修订
|
||||
|
||||
修订 ID：`codegraph-governance-2026-09-24-r1`；owner：`Cursor`；state：`active`（生效 tip `19eb56e3744d3c7d4b69b065c87e27689e8caa53` / fixup `0c676afe1faf831020c7c3201509d7cec0328d53`）；工具能力：盘点命令与 hooks sync 为 `enforced`（脚本已落地）；常驻 daemon 装载仍为 `manual`（本机默认不装载）。用户授权：将 CodeGraph 纳入治理启动/建场/sync，并对 worktree 清理与 FEATURE-MATRIX 做只读盘点提醒（不自动删除、不自动升 done）。
|
||||
|
||||
唯一来源增补：[AGENTS §1/§4](../../AGENTS.md)、[worktree 操作规范 §8](./2026-09-21-agent-worktree-workflow.md)、[收口清单](./templates/session-close-checklist.md)。命令入口：`agentctl cleanup report`、`agentctl docs drift`、`agentctl hooks codegraph-sync`、建场 `agent-worktree.sh create` 的 best-effort `codegraph init`。不改产品 SWBOOT-10 stub，不装载 systemd coordinator（需另授）。
|
||||
|
||||
## Subagent 工作流拟议修订
|
||||
|
||||
修订 ID：`subagent-workflow-2026-09-24-r2`；owner：Codex；state：`proposed`；能力：`manual`；effective_commit：无。
|
||||
用户要求研究 Cursor Auto 下的 subagent 分工、阶段流程及报告，授权与本次验收见[任务](short-term/2026-09-24-subagent-workflow-standard.md)。[规范草案](2026-09-24-subagent-workflow-standard.md)为拟议行为的唯一来源，[研究报告](../audit/2026-09-24-subagent-workflow-research.md)给出事实和待修冲突，[模板](templates/subagent-stage-record.md)承载交接。
|
||||
用户后续明确采用 Cursor Auto 实施 + gmktec 本机 PI 子任务，并批准默认模型分工及可调整文档。[模型配置](2026-09-24-subagent-model-config.md)为模型路由唯一来源，decision_state=approved；流程整体仍 proposed；已批准的模型配置与执行器已合入本地 dev。原 Cursor 原生角色/inherit 方案被替代。执行器已在任务分支实现并验证 Cursor CLI→MCP→PI，代码 69ffaa677e23a1dd9aa0528bb09b3acfcd38b119；[运行说明](2026-09-24-pi-subagent-executor.md)与[验证报告](../test-reports/2026-09-24-pi-executor-test-report.md)限定已验证的机器边界。dev 集成/完整流程审批仍独立记录；不以派发器可用宣称全阶段自动门禁。
|
||||
|
||||
## Cursor 治理层局部修订
|
||||
|
||||
修订 ID：`cursor-governance-2026-09-24-r1`；owner：`Cursor`；state：合入 local_dev 后 `active`（effective_commit 以集成收据为准）；工具能力分层：
|
||||
- 规则/skill 文本：`manual`（Agent 读取执行）
|
||||
- hook 脚本 stdin→stdout 行为：`enforced`（`scripts/tests/test_cursor_hooks.py`）
|
||||
- hook ↔ Cursor IDE 接线：`advisory`/`manual`（事件字段待 probe 采样；见 ISSUE-20260924-cursor-hook-event-contract）
|
||||
|
||||
用户授权：在 PI 执行器合入后补齐 skills/rules/hooks；范围与验收见[任务](short-term/2026-09-24-cursor-governance-hooks.md)。客户端入口：`.cursor/rules/cursor-hooks.mdc`、`pi-subagents.mdc`、`test-reports-standard.mdc`（缩为验证契约指针）；skills `pi-subagent-dispatch` / `subagent-stage-record`；hooks 见 `.cursor/hooks.json`。不改变产品 Runner、不扩大执行器硬门禁语义。
|
||||
|
||||
## 治理目录库与需求重叠检测拟议修订
|
||||
|
||||
修订 ID：`governance-catalog-2026-09-24-r1`；owner：`Cursor`；state：`proposed`；能力：schema/门禁落地后为 `enforced`，向量层 `fail-open`；effective_commit：无（随受控合入记录）。
|
||||
用户授权实施跨对话需求重叠检测与治理目录（扩展既有 `.locks/state.sqlite`，不碰业务 PG）。唯一来源：[方案](./2026-09-24-governance-catalog-plan.md)；任务：[short-term](./short-term/2026-09-24-governance-catalog.md)。策略键 `catalog_gate`/`catalog_vector` 为可选，不得破坏 `shared_docs` 等集合相等校验。
|
||||
@@ -1,71 +0,0 @@
|
||||
# 按变更范围选择验证与证据
|
||||
|
||||
规则状态、owner 与生效条件见 [规范登记](./2026-09-21-policy-registry.md)。本文件是项目验证范围和报告要求的唯一来源；客户端仅引用。执行共享环境测试前，先满足 [操作规范](./2026-09-21-agent-worktree-workflow.md) 的授权、环境身份和持锁条件。
|
||||
|
||||
## 验证矩阵
|
||||
|
||||
| 变更范围 | 必需验证 | 不足以验收的证据 |
|
||||
|---|---|---|
|
||||
| 纯规范/普通文档 | diff、相对链接、状态、所有入口指令一致性 | 未核对来源的文案结论 |
|
||||
| 治理脚本 | 临时 Git 仓库中的真实分支/锁/并发/异常退出与拒绝路径 | 仅语法检查或 stub |
|
||||
| Go/接口 | 对应单测；`./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`；受影响 PG 和鉴权负例 | short 测试替代被跳过的 PG/真实链路 |
|
||||
| 前端 | `web/` 中 `npm test`、`npm run build`；受影响交互的真实浏览器验证 | API 直调替代 UI 操作 |
|
||||
| 迁移/运行配置 | 独立环境升级、兼容性、回退/前滚条件及就绪验证 | 重启/health 替代版本与持久性证据 |
|
||||
| 产品 Agent/工作流（含运行模板/提示词） | 受影响真实产品 PI Agent Runner 链路；对应用户流程、持久状态和 UI | stub、SKIP、测试名未匹配、仅健康检查 |
|
||||
|
||||
多类变更取并集。按 [模块开发标准](../system-design/2026-09-20-module-development-standards.md) 追加边界与 registry parity 等范围门禁。开发阶段可用 stub；交付验收不能冒充真实执行。纯文档无需产品 PI 或全量 Go，也不为形式重建服务。
|
||||
|
||||
## 问题修复的回归范围
|
||||
|
||||
Bug/系统问题修复先按 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 确定问题类别和影响范围，再从上表选择验证层级。验收须包含：原始复现案例；通过同一机制的其他输入、措辞或入口；相关边界/异常路径；应保持不变的正常行为。场景按实际因果链选择，不机械穷举；不适用或未覆盖的项记录理由与风险。
|
||||
|
||||
验证机制和预期行为，不以硬编码原句、固定回复文本或单个样例通过代替回归。能在修复前复现失败的场景记录修复前后对照；不能复现时说明证据限制。报告逐项区分通过、失败、未运行与待验证；只提供分析/方案时列出验收设计，不声称已经运行或修复。
|
||||
|
||||
## 产品 PI 基线与精确追加
|
||||
|
||||
优先入口：`./scripts/run-nightly-real-pi.sh`。调用前核验并从获授权配置提供（不在命令/报告贴凭证值）：
|
||||
|
||||
- 独立可写 `TEST_DATABASE_URL`，不得指向真实生产业务库；确认 Runner 与测试所需工作区/`DATA_DIR` 挂载相容。
|
||||
- `PI_AGENT_RUNNER_URL` 和 `PI_AGENT_RUNNER_AUTH_TOKEN` / `RUNNER_AUTH_TOKEN`；真实 Runner 可访问。
|
||||
- 共享 KB 的授权连接与必要凭证；正常验收要求在线。`KB_ALLOW_OFFLINE=1` 只证明显式降级场景。
|
||||
- 目标环境批准的实际模型、协议及制品；通过 `PI_AGENT_MODEL` 传入批准值并比对 Runner 实际配置。脚本默认值不构成批准，也不证明实际模型。
|
||||
- 脚本可能构建候选镜像、写 promotion receipt；须满足构建身份/授权条件。`NIGHTLY_SKIP_IMAGE_BUILD=1` 不能补足缺失的制品摘要证据。
|
||||
|
||||
脚本当前筛选 **五项**（U8 + 四条工作流治理链）：
|
||||
|
||||
```text
|
||||
TestMultiIntentU8_RealPI_ConfirmGenerate_PG
|
||||
TestWorkflowGovernance_PiAgent_PG_FullChain
|
||||
TestWorkflowGovernance_PiAgent_PG_ProductManager_FullChain
|
||||
TestWorkflowGovernance_PiAgent_PG_TestManager_FullChain
|
||||
TestWorkflowGovernance_PiAgent_PG_FullNoneMixedChain
|
||||
```
|
||||
|
||||
它覆盖 main / product_manager / test_manager / FullNone 四条工作流治理链，但**不是**「全部工作流通过」，也不含 rdev P3 Go 顶层（rdev 仍用 Python 三样本 harness）。按变更范围追加精确名称，例如（前提条件已核验，且已处于相应环境执行租约/独立环境）：
|
||||
|
||||
```bash
|
||||
go test -count=1 -timeout 2h -v ./internal/server/ -run '^TestPiAgent_FullLifecycle_MultiRole_RealWorld_E2E$'
|
||||
go test -count=1 -timeout 90m -v ./internal/server/ -run '^TestWorkflowGovernance_PiAgent_PG_(FullChain|ProductManager_FullChain|TestManager_FullChain)$'
|
||||
```
|
||||
|
||||
当前源码前提：上述 PG/U8 用例的 `piAgentRunnerHealthy` 预检固定访问 `127.0.0.1:18865`，不能仅设置其他 Runner URL 就假定能执行；FullLifecycle 配置写死 `MiniMax-M3` 且使用临时 DataDir/内存模式，不能用它单独证明 PG 持久性，也不能声称 `PI_AGENT_MODEL` 已改变该用例模型。执行前确认这些条件符合目标环境批准范围；不符时记录缺项并安排相应测试适配，不静默换模型或把 SKIP 当验收。
|
||||
|
||||
测试筛选区分大小写；`-run 'PI'` 不能选择名称中的 `PiAgent`。追加用例先读其环境前提；FullLifecycle 中 `RUN_FULL_ADHOC_WBS` 与 `RUN_HEAVY_STAGES` 控制额外段，不能把默认未跑段报为已覆盖。普通 PG 用例同样以源码中的精确名称/前提为准。
|
||||
|
||||
运行前列 `expected_tests`（含必须子场景），运行后逐项对照执行、PASS、FAIL、SKIP、未匹配及重试。退出码 0 或 nightly receipt `pass` 不能替代该对照：基线脚本逐项核对五个预期顶层测试；额外子场景/用例仍须逐项核验。缺项不记 PASS，基础设施问题记录 blocker/infra_fail。保留首轮与重试关系，不隐藏失败。
|
||||
|
||||
## 模型与环境证据
|
||||
|
||||
模型以目标环境批准配置为准；dev/test/main 的 Compose 默认值可能不同，不能将某个模型全局写成验收条件。每次记录目标环境、源码 SHA、镜像/制品摘要、schema、Runner 实际模型/协议、配置来源与核验时间；仅有环境变量不能证明实际值。发现不符先查明并记录，不为满足文档自行换模型。不得用 Herdr `context_pi` 的模型信息替代产品 Runner。
|
||||
|
||||
共享环境的长 E2E 持锁至结束；无权使用该环境则在独立固定环境执行。制品/候选变更后重新确认适用证据，不把旧提交 PASS 搬到新提交。
|
||||
|
||||
## 报告与真实性
|
||||
|
||||
小型文档/脚本任务可以在主文档设验证节；独立报告放 `.doc/test-reports/YYYY-MM-DD-<slug>-test-report.md`，附件放 `.doc/test-reports/assets/<report-slug>/`。任何层级至少记录：范围、被测 SHA、实际命令、环境、预期与实际、判定、证据链接、缺项/风险。命令包含秘密时记录参数名与脱敏方式，不记录值。
|
||||
|
||||
跨模块/业务交付使用完整报告：背景、目标、方案/环境、预期、逐例实际结果与耗时、实际执行套件汇总、结论与剩余条件。套件汇总只列本次适用并实际运行的检查，不无条件要求全量 Go。声明 PASS 必须有对应真实输入/输出或足够判定的真实片段；来源与结论可核实，脱敏不得改写结果。无需提交原始完整日志、个人信息、业务正文或秘密截图。记下删减/脱敏范围，唯一证据清理前先安全归档。
|
||||
|
||||
## 工程工具验收补充
|
||||
|
||||
本地协调与运维守卫使用 `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`，在临时真实 Git/SQLite/进程环境执行；Docker 守卫测试使用受控目标记录调用，不重建共享服务。nightly 入口现在核对最终尝试日志中五个预期顶层测试均恰好执行且 PASS；零用例、部分 SKIP 或重复拼接证据均不能生成 PASS 收据。该日志核验不是本轮执行了产品 PI 的声明。
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: "agentctl Cursor 能力层（skills / MCP / rules / hooks）"
|
||||
status: active
|
||||
created: 2026-09-23
|
||||
updated: 2026-09-23
|
||||
owner: Cursor
|
||||
task_id: agentctl-cursor-integration-2026-09-23
|
||||
---
|
||||
|
||||
# agentctl Cursor 能力层
|
||||
|
||||
把已上线的 agentctl 管理面包装为 Cursor 原生能力，使 agent 默认走租约 / docs 收据 / 候选合入。
|
||||
|
||||
## 能力清单
|
||||
|
||||
| 层 | 路径 | 作用 |
|
||||
|---|---|---|
|
||||
| MCP | [`.cursor/mcp.json`](../../.cursor/mcp.json) → [`scripts/mcp/agentctl-mcp.mjs`](../../scripts/mcp/agentctl-mcp.mjs) | `status` / `task_*` / `lease_run` / `docs_*` / `validate` / `queue_enqueue` / `quarantine_status` |
|
||||
| Skills | [`.cursor/skills/agentctl-*`](../../.cursor/skills/) | 会话启动、建场、租约写、集成收口 |
|
||||
| Rule | [`.cursor/rules/agentctl-mandatory.mdc`](../../.cursor/rules/agentctl-mandatory.mdc) | alwaysApply：强制走 agentctl |
|
||||
| Hooks | [`.cursor/hooks.json`](../../.cursor/hooks.json) + `guard-git.sh` | `git push` / 破坏性 git → `permission: ask` |
|
||||
|
||||
权威规则仍是 [AGENTS.md](../../AGENTS.md) 与 [操作规范](./2026-09-21-agent-worktree-workflow.md)；本目录不复制全文。
|
||||
|
||||
## 启用
|
||||
|
||||
1. 合入 local `dev` 后，在 Cursor 中 **Reload Window** 或重载 MCP。
|
||||
2. 确认 MCP 服务器 `agentctl` 出现在工具列表；hooks 出现在 Cursor Hooks 设置页。
|
||||
3. 会话开始跟 skill `agentctl-session-start`（核对 `daemon status`）。
|
||||
|
||||
## 与管理面关系
|
||||
|
||||
- launchd `com.agentctl.coordinator` 持续 `queue schedule`；本能力层只封装 CLI，不替代 daemon。
|
||||
- git hooks（pre-commit / pre-merge / reference-transaction）仍由 `agentctl hooks` 管理，与 Cursor `beforeShellExecution` 互补：前者执行租约/候选门禁，后者拦未授权 push/强推。
|
||||
|
||||
## 非目标
|
||||
|
||||
不 push；不晋升 test/main；不改 gap-matrix；不卸载 daemon。
|
||||
@@ -1,61 +0,0 @@
|
||||
# 问题记录与开发经验闭环
|
||||
|
||||
修订：`issue-learning-2026-09-23-r1`；owner：Codex；生效条件见 [规范登记](2026-09-21-policy-registry.md)。执行能力为 `manual`：依靠 Agent 读取、任务记录与审查；本轮没有增加自动检索、CI 阻断或模型训练。
|
||||
|
||||
## 入口与职责
|
||||
|
||||
| 入口 | 回答的问题 | 权威边界 |
|
||||
|---|---|---|
|
||||
| [问题台账](../audit/ISSUES.md) | 出现过什么问题，目前处理到哪一步？ | 索引和状态投影；事实、修复经过以链接的唯一问题主记录为准 |
|
||||
| 问题主记录 | 为什么发生、考虑过哪些方案、改了什么、如何验证？ | 放 audit，或沿用已有任务/审计中的明确章节；使用 [问题模板](templates/issue-record.md) |
|
||||
| [开发经验](lessons/INDEX.md) | 遇到类似工作应先检查什么？ | 按机制提炼的注意事项；使用 [经验模板](templates/development-lesson.md)，不替代现行规范 |
|
||||
| CURRENT / FEATURE-MATRIX / gap-matrix | 当前协调 / 能力 / 发布门禁 | 维持原职责；只有对应状态改变才更新 |
|
||||
|
||||
修复方案、任务、提交、验收报告通过链接串联，已有材料直接复用。一个 task 可处理多个 issue，一个 issue 可跨分析/实施任务；研究任务 done 不等于问题 resolved。一个 lesson 可覆盖多个同根因 issue。短问题可在任务主文档内记录，无需机械创建一套文件。
|
||||
|
||||
## 何时记录、检索和总结
|
||||
|
||||
1. **设计、编码、排障或运维前**：按模块、路径、错误码、症状和共用机制检索问题台账及经验索引。先查索引、再读命中条目的来源；核对当前源码/规范是否仍适用。在任务记录填写检索词、命中 ID、采纳的检查；无命中明确记录。简单信息答复不要求建任务或检索整库。
|
||||
2. **首次发现问题时**：在当前任务 worktree 建立或补充问题主记录和台账行，记录预期/实际、影响、环境/版本、owner、下一步及证据缺口；尚未定位也可以登记。ID 使用 `ISSUE-YYYYMMDD-<slug>`，日期为登记日；发生日期另列，跨 worktree 以语义 slug 避免抢序号。
|
||||
3. **定位、改方案、完成修复或发现验收失败时**：在同一主记录追加时间线和尝试结果；保留被否定假设、失败方案及不适用条件，区分观察、推测和已证实根因。按 [问题分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 检查共用机制和同类入口。
|
||||
4. **根因与修复得到验证后、任务收口前**：提炼经验或更新已有同机制经验，并链接回问题。若尚无验证证据，只能建 `candidate`；若没有新增可复用结论，记“不新增经验”及理由，仍保留问题记录。分析-only、未修复或验收失败的问题继续留在台账。
|
||||
5. **经验落到开发动作**：写清触发条件、机制、应做检查、错误做法及原因、验证方法、适用边界。优先链接现有测试/约束；需要新增回归、lint、架构门禁或规范时，在当前授权内实施，超出授权则记录 owner/后续任务。仅提出自动化建议不能标为已落实。
|
||||
6. **复发或规则变化时**：同一故障未解决的复现追加原 issue；已关闭问题再次出现，重开原 issue 为 `investigating`，递增 `recurrence_count` 并保留原关闭证据。不同根因建立新 issue 并互相链接。复盘为何已有经验/测试未生效：未检索、范围不适用、遗漏入口、检查未执行或实现回退，并更新防护。模块/接口/规范变化时复核命中经验；确认过时标 `superseded` 并链接替代条目，无替代则 `retired`，保留历史。
|
||||
|
||||
检索示例（在任务工作区执行，替换为本任务关键词）：
|
||||
|
||||
```bash
|
||||
rg -n -i 'docgov|nullable|23503|职责' .doc/audit/ISSUES.md .doc/ops/lessons
|
||||
```
|
||||
|
||||
owner 在上述里程碑及时更新，最迟在会话交接前保存事实和未完成项；不依赖定时服务。经验不会自动改变模型参数，作用是让后续 Agent 能检索、有证据地复用，并逐步把重复风险转换为可执行检查。
|
||||
|
||||
## 问题状态与关闭条件
|
||||
|
||||
问题的 `issue_state` 与任务 `status` 分开；台账保留当前投影，主记录保留变迁历史。
|
||||
|
||||
| issue_state | 含义 / 转移要求 |
|
||||
|---|---|
|
||||
| open | 已登记，等待定位 |
|
||||
| investigating | 正在复现、验证假设和范围 |
|
||||
| fixing | 修复方案明确且已获实施授权 |
|
||||
| verifying | 修复待验收，或必要证据尚缺 |
|
||||
| resolved | 约定范围的修复、必要环境验收均有证据，经验已总结或有不新增理由 |
|
||||
| deferred | 暂缓处理；保留风险、责任人、复查触发和授权/决策依据，不冒充修复 |
|
||||
| duplicate | 指向唯一主 issue，保留原报告和去重理由 |
|
||||
|
||||
定位失败可保留 investigating；临时止血不代表 resolved，必须标清剩余根治项。验证失败回到 investigating/fixing，不能覆盖失败记录。关闭至少能追溯：根因、同类范围、修复提交或获授权的处理动作、原例/变体/正常行为验收及缺项、实际部署状态、lesson 或不新增理由。业务改动待部署时不能把目标环境问题关闭；无需部署写 not_required。
|
||||
|
||||
**历史补录**：发生日、修复日和补录日分开。只按旧报告已证明的范围记录 `resolved`，同时标 `evidence_basis=historical` 和当前运行未复测；缺乏关闭证据用 `verifying` 并说明原因，不从旧任务 done 推导修复完成。历史条目不能用于宣布当前系统就绪。本轮仅补录两个有来源案例，不代表穷尽全部历史问题。
|
||||
|
||||
## 经验质量与维护
|
||||
|
||||
`lesson_state`：`candidate | validated | superseded | retired`。validated 表示注意事项有可核对的因果证据且已复核适用边界，不表示所有模块或当前线上均测试通过。需记录 reviewer、last_reviewed、reviewed_revision、来源 issue、证据日期、关键词、关联测试、适用/不适用范围及仍缺的防护。
|
||||
|
||||
同机制优先更新已有 lesson，保留修订记录；新机制才新增 `LESSON-YYYYMMDD-<slug>`。将通用经验升级成强制规范时，只在对应规范的唯一来源修改并登记生效条件，经验条目保留理由与链接。经验与现行规范冲突时先按有效规范执行，登记冲突与复核项；历史经验不能授予数据修复、部署或扩大范围的权限。
|
||||
|
||||
## 并发、验收与敏感信息
|
||||
|
||||
所有写入沿用 [worktree 操作规范](2026-09-21-agent-worktree-workflow.md)。问题/经验索引使用各自 `path:` 短租约；当前 `agentctl docs apply` 仅覆盖 CURRENT/FEATURE-MATRIX，不宣称新索引有行级 CAS。写入前读最新内容、只改自己的条目；从旧 dev 分出的工作区在集成前合并最新 dev 并处理索引冲突，保留他人条目。索引和主记录在同一逻辑提交同步，避免状态分叉。
|
||||
|
||||
文档验收包括链接/锚点、ID 唯一、主记录与索引状态一致、来源及日期、入口/模板可达和情景检查。运行回归按 [验证契约](2026-09-21-validation-contract.md)；未运行、缺项与历史证据单独标明。只保留足够判断的脱敏证据，业务正文、凭证和个人数据不复制进经验库。
|
||||
@@ -1,46 +0,0 @@
|
||||
# 治理目录库与跨对话需求重叠检测（方案）
|
||||
|
||||
**修订 ID**：`governance-catalog-2026-09-24-r1`
|
||||
**state**：`proposed` → 实施后随合入升 `active`
|
||||
**owner**：Cursor
|
||||
**工具能力**：schema/CRUD/门禁 `enforced`（落地后）；向量层 `fail-open`
|
||||
**任务**：[short-term](./short-term/2026-09-24-governance-catalog.md)
|
||||
|
||||
## 问题
|
||||
|
||||
跨对话新设计与既有功能/需求重叠时，现有 agentctl 仅做路径级 `overlaps()` 互斥，无需求语义比对。CURRENT/ISSUES/test-reports 为 Markdown 台账，机器无法强制开工前探测。
|
||||
|
||||
## 方案摘要
|
||||
|
||||
在既有 `.locks/state.sqlite`（与业务 PG 物理隔离）上 additive 扩展 Catalog 表：
|
||||
|
||||
| 表 | 用途 |
|
||||
|---|---|
|
||||
| `catalog_requirements` | R-ID 需求条目 |
|
||||
| `catalog_features` | 对齐 FEATURE-MATRIX record_id |
|
||||
| `catalog_req_text` | FTS5 CJK 逐字索引（禁用 trigram） |
|
||||
| `catalog_overlaps` / `catalog_decisions` | 检测结果与裁决留痕 |
|
||||
| `catalog_issues` / `catalog_tests` / `catalog_releases` | 缺陷/测试/发布投影 |
|
||||
| `catalog_embeddings` | 可降级向量增强 |
|
||||
|
||||
### 分级门禁
|
||||
|
||||
1. **L1 结构化**：`same_mutex` / `same_feature` / `same_scope` / `same_req_id` → hard deny
|
||||
2. **L2 语义**：FTS5 bm25 软门，须 `catalog overlap ack` 显式裁决后才可编码
|
||||
3. **L3 向量**：读 `EMBEDDING_*`；401/超时/缺钥 → `vector_layer=degraded`，不阻断
|
||||
|
||||
### 策略
|
||||
|
||||
`catalog_gate` / `catalog_vector` 为**可选键**（不得加入 `shared_docs` 等集合相等校验字段）。
|
||||
|
||||
### 权威关系
|
||||
|
||||
`.doc` Markdown 仍为事实来源；Catalog 为可检索投影 + 门禁依据；冲突时 `catalog drift` 告警，不自动改文档。
|
||||
|
||||
## 边界
|
||||
|
||||
不新建第二库/容器；不读写业务 PostgreSQL；不改 `overlaps()` 既有语义；不做跨机权威。
|
||||
|
||||
## CLI / MCP
|
||||
|
||||
`agentctl catalog {add,list,show,search,overlap,ack,status,drift}`；MCP：`catalog_requirement_add` / `catalog_overlap_probe` / `catalog_overlap_ack` / `catalog_search` / `catalog_status`。
|
||||
@@ -1,47 +0,0 @@
|
||||
# 本机 PI Subagent 执行器接入方案与实施记录
|
||||
|
||||
task_id：subagent-workflow-standard-2026-09-24；operation_task_id：subagent-workflow-standard-2026-09-24-executor。
|
||||
用户授权：“接入自动调用 pi 的执行器”；既有约束：Cursor Auto 实施，PI 模型限[配置](2026-09-24-subagent-model-config.md)，M3 默认停用。本次是同任务的实现续作。
|
||||
|
||||
## 目标与边界
|
||||
|
||||
Cursor 能通过项目 MCP 自动按角色调用 gmktec 本机 PI，读取配置，提供冻结输入，获得持久报告和可核验状态。CLI 同步提供可复现入口。
|
||||
不修改产品服务/Runner、不操作真实业务数据、不安装 daemon、不 push。代码只在原登记 worktree 修改，当前 main 有其他任务的未跟踪 promotion receipt，保留不动。
|
||||
本次复核 local dev=6858e21d477571696a8458032e2c884449e773fd；原任务 HEAD=52462b45e985f596b2a503fc70ac12c3bd5fe571；新增 dev 差异为 internal/squad，与本次脚本无交叉。没有重新建场或切换主目录分支。
|
||||
|
||||
## 分工与执行方式
|
||||
|
||||
- Cursor Auto：编写执行器、MCP 接口、权限限制与测试。host Codex：需求/契约、文档、证据核验、审查与受控提交。
|
||||
- Cursor CLI 在已登记原任务 worktree、agentctl with 监督和精确路径租约内执行；不授予提交/合并/推送/环境操作权限。模型请求 Auto；实际底层模型不可见时记录 unknown。
|
||||
- 本次使用 ce-work 的执行/验证思路、CodeGraph 定位、test-driven-development 和 writing-for-agents。仓库 AGENTS 的原任务 worktree/agentctl 规则优先于技能中 detached 临时工作区机制；使用仓库 supervisor 派发 Cursor，代码路径单写者，外层核对差异。该隔离不是 OS 沙箱。
|
||||
- 范围：scripts/pi_subagents.py、scripts/pi-subagent-readonly.ts、scripts/mcp/pi-subagents-mcp.mjs、scripts/tests/test_pi_subagents.py、scripts/mcp/README.md、.cursor/mcp.json、.cursor/rules/pi-subagents.mdc，以及本任务相关 .doc 文档。
|
||||
- 认领能力仅 docs:publish；不注册 env:* 或 git:dev。后续集成另按受控候选流程处理。
|
||||
|
||||
## 设计契约
|
||||
|
||||
1. 配置文档是唯一模型来源，每次派发解析严格表格，记录 revision/hash 和实际 provider/model。禁用、未知、循环、M3 关键职责路由失败关闭；没有静默备用。
|
||||
2. 新鲜 PI 会话；冻结 source SHA 与显式 tracked 输入文件（拒绝秘密/业务 data/路径穿越/符号链接），上限限制。模型只得到选定输入与允许的只读工具，无任意 shell、源码写入或递归派发。
|
||||
3. 测试角色仅运行主 Agent 显式提供、带来源的 argv 计划；独立源码副本、净化环境、超时和输出限制，模型不生成可执行命令。共享业务环境本版不接入，返回明确限制。
|
||||
4. MCP 提供角色预览、运行、结果查询；跨 worktree 调用核对同仓与 task 注册；运行由权威 agentctl with 包裹，并由执行器校验继承租约。
|
||||
5. 每个 request_id 绑定输入摘要；同请求重放只查询，变更载荷拒绝，running/unknown 不重派。每请求独立短范围 report 路径锁，跨调用者统一并发上限。
|
||||
6. 运行前保存 running；完成保存 receipt.json/report.md，含命令、版本、输入摘要、配置摘要、状态/结论、报告来源。结果未知/失败不冒充通过，进程退出0不替代模型最终事件和必需测试结果。
|
||||
7. timeout/cancel 处理进程组并回收；未知副作用保留现场。凭证仅由 PI 客户端读取，绝不进入模型输入/报告；测试子进程不继承模型密钥或租约身份。
|
||||
8. MCP 用标准 stdio JSON-RPC，查询不被运行调用阻塞。项目规则告诉 Cursor 何时选择哪种 role_id，具体模型仍从配置读取。
|
||||
9. 实施与修复始终交给 Cursor；PI 负责分析/审查/验证。模型结论和 acceptance_owner 的最终验收分开。
|
||||
|
||||
## 验证计划
|
||||
|
||||
- 隔离真实 Git/agentctl：注册/租约负例、路径范围、报告落盘、请求幂等、并发与异常退出。
|
||||
- 本地假 PI 仅作为协议传输夹具：模型参数、权限开关、JSON 事件、错误/空响应/超时/子进程清理；不得当作真实模型能力验收。
|
||||
- MCP 实进程：initialize、tools/list、roles、run、result；错误必须 isError。
|
||||
- 实际本机 PI：至少一条真实分析请求与独立代码审查；模型/权限/配置/源码身份可追溯。不得把 CLI/MCP 接口实测写成 Cursor IDE 页面已实测。
|
||||
- 主机核验聚焦测试与工程脚本套件，按失败证据补回归；无需运行无关产品全量 Go、重建服务或产品 PI。
|
||||
- 收口保留运行结果和剩余条件，分别记录 local commit / integration / deployment / remote_sync / cleanup。
|
||||
|
||||
## 当前进度
|
||||
|
||||
2026-09-24：Cursor Auto 已在 agentctl supervisor 内启动；本轮尚未宣称实现完成。机器租约身份和终端输出由 host 核验，待实施结果后补测试与审查。
|
||||
|
||||
## 已验证结果
|
||||
|
||||
执行器代码已提交为 69ffaa677e23a1dd9aa0528bb09b3acfcd38b119。完整工程回归 173 项、提交后专项 34 项、真实 Cursor CLI→MCP→PI 自动路由与最终 ls/read 均通过，详见[报告](../test-reports/2026-09-24-pi-executor-test-report.md)。文档配置已改为程序读取；完整审批状态机仍人工/Agent 遵约。已受控合入本地 dev，集成提交 5a8540804ee2d142a0894c1482a2a16e8f843915，未推送；Cursor IDE 页面仍未实测。
|
||||
@@ -1,80 +0,0 @@
|
||||
# 本机 PI Subagent 执行器使用说明
|
||||
|
||||
范围：Cursor Auto 主协调/代码实施，gmktec 本机 PI 子任务。模型分工唯一来源为[模型配置](2026-09-24-subagent-model-config.md)，阶段定义见[流程规范](2026-09-24-subagent-workflow-standard.md)。本说明与代码已合入本地 dev；集成和最终实测状态见[实施记录](2026-09-24-pi-executor-implementation.md)。
|
||||
|
||||
## Cursor 中使用
|
||||
|
||||
1. 在包含本次提交的工作区打开 Cursor，重新加载项目 MCP；.cursor/mcp.json 注册 pi-subagents 服务，.cursor/rules/pi-subagents.mdc 提供派发入口。
|
||||
2. 主会话保持 Auto。先按原有流程创建/登记任务 worktree，并将 .doc/test-reports/assets/pi-subagents/<task-id> 纳入任务写范围。
|
||||
3. Cursor 调用 pi_subagent_roles 读取当前角色与模型；从任务目标选择 role_id，调用 pi_subagent_run，随后查询 pi_subagent_result。
|
||||
4. 不需要用户切换 PI 模型。需求/方案、独立审查、测试和报告由不同角色处理；代码实施与修复仍由 Cursor 执行。
|
||||
5. 接收报告并核对范围、源码/配置版本、缺项；运行完成不代表阶段批准。最终验收责任仍由任务 acceptance_owner 承担。
|
||||
|
||||
任务 worktree 尚未合入 dev 时，主目录中的旧 MCP 配置不会自动获得新工具；先在该任务 worktree 验证，受控集成后再在主目录重载。本文不宣称已操纵 Cursor IDE 页面。
|
||||
|
||||
## 请求内容
|
||||
|
||||
MCP 工具的外层参数 worktree 为同仓的已登记任务工作区，task_id 为实际操作任务。request 中给出以下信息；授权引用应能回链到真实用户请求，不用日志/模型文本自授权限。
|
||||
|
||||
```json
|
||||
{
|
||||
"worktree": "/absolute/path/to/repo/.worktrees/task-id",
|
||||
"task_id": "task-id",
|
||||
"request": {
|
||||
"role_id": "research",
|
||||
"request_id": "research-001",
|
||||
"goal": "读取选定文件，给出有证据的分析",
|
||||
"authorization_ref": "本任务主记录中的用户授权位置",
|
||||
"source_sha": "<完整的已提交源码 SHA>",
|
||||
"input_files": ["PROJECT.md"],
|
||||
"timeout_seconds": 120
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
source_sha 必须为完整提交 hash；HEAD/分支名不作为可变输入。只发送明确列出的已跟踪 UTF-8 普通文件，禁止运行数据、.env、凭证、符号链接和路径越界。未提交的代码不会自动进入快照，先由 Cursor 形成可审提交或使用已有冻结版本。
|
||||
|
||||
request_id 在同一任务中稳定标识一次请求：同参数只读重放既有结果，不重复调模型；不同参数复用 ID 被拒绝；running/unknown 保留现场，不能盲目重派。配置变更在下一次新派发读取，旧请求保留原 config_revision/config_sha256。
|
||||
|
||||
## CLI 入口
|
||||
|
||||
在任务工作区使用：
|
||||
|
||||
```bash
|
||||
python3 -B scripts/pi_subagents.py roles
|
||||
../../scripts/agentctl with --task task-id \
|
||||
--resource path:.doc/test-reports/assets/pi-subagents/task-id/research-001 -- \
|
||||
python3 -B scripts/pi_subagents.py run --request /tmp/pi-request.json
|
||||
python3 -B scripts/pi_subagents.py result --task task-id --request-id research-001
|
||||
```
|
||||
|
||||
CLI 请求文件需包括 task_id；也可用 run --stdin 输入 JSON。直接裸调 run 会被租约校验拒绝。上述名称是示例，不构成任何任务或环境授权。
|
||||
|
||||
## 测试角色
|
||||
|
||||
test_run / acceptance_check 还需 approved_commands（argv 数组的数组）和 plan_digest（外部已批准计划 SHA-256）；执行器另记录 approved_commands_sha256，不能以任意字符串冒充命令与计划的同一摘要。
|
||||
|
||||
命令在独立测试快照中运行，使用净化环境和私有 HOME/cache/tmp，标准输入关闭。PI 模型根据收到的命令摘要、退出码和日志引用分析，不生成或修改被执行命令；完整日志由主 Agent 核验并在需要时补充上下文。模型分析快照保持原始源码内容，与测试可写副本分离。必要的 stdout/stderr 保存到本请求报告目录以便核对，不仅保留一段摘要。
|
||||
|
||||
依赖未安装、用例缺失或命令失败须如实记录。本版不自动安装依赖，不直接连接共享 dev/test/main 或操作真实业务数据；相关检查继续由主 Agent 通过现有环境授权/租约流程执行。命令退出 0 只证明命令层执行成功；必需用例是否执行、SKIP、持久性/UI 和业务验收仍按验证契约核对。
|
||||
|
||||
## 证据与状态
|
||||
|
||||
输出位置：.doc/test-reports/assets/pi-subagents/<task-id>/<request-id>/。
|
||||
|
||||
- receipt.json：请求摘要、配置摘要、源码/输入文件摘要、配置与观察到的模型、运行状态、命令结果、工具调用摘要。
|
||||
- report.md：可读报告；模型分析是审查输入，主 Agent 核对后再推进阶段。
|
||||
- 命令日志：按收据记录的位置查询；报告目录受对应 path 租约保护。
|
||||
- 模型私有 thinking 不作为归档材料。错误输出与日志按敏感信息规则处理；不保存凭证。
|
||||
|
||||
run_status 与 verdict 分开：模型正常结束可以是 succeeded，但非测试报告仍为 review_state=pending / verdict=not_applicable。测试报告的 commands_passed/pass 只针对提交的命令，不能直接赋值到任务的 review_state 或 acceptance。失败、取消、结果未知不能换成 PASS。
|
||||
|
||||
超时、取消和输出超限处理整个受控进程组。只读结果查询可推断 orphan 为 unknown，但不能通过查询无租约改写收据。错误前置检查未形成业务收据时，MCP 返回可核对的执行拒绝，不能让主 Agent 一直等待不存在的结果。
|
||||
|
||||
## 调整与边界
|
||||
|
||||
角色默认模型、enabled、升级角色和并发上限在模型配置文档维护。禁用角色前同步处理指向它的升级关系。程序仅接受当前明确批准的五个 provider/model 组合；扩大模型池还需用户授权并更新硬边界校验，不是任意改一行即放宽权限。
|
||||
|
||||
本工具提供配置解析、模型启动、有限工具/输入范围、租约、进程监督和证据保存；没有把全部 S0–S9 的审批实现成不可跳过的状态机。Cursor 通过规则决定何时调用；模型失败不会触发隐式换 provider 或降级到 M3。
|
||||
|
||||
进程组和工具权限限制不是 OS 沙箱。批准的测试代码与本机工程工具属于可信执行面；外部不可信项目/代码不能因使用本工具就获得运行授权。普通 Cursor/PI 配置与 Herdr、产品 PI Runner 各自独立。
|
||||
@@ -1,88 +0,0 @@
|
||||
# Subagent 模型分配配置
|
||||
|
||||
config_revision：`subagent-models-2026-09-24-r1`
|
||||
|
||||
owner：用户；维护执行者：当前任务主 Agent。
|
||||
|
||||
decision_state：`approved`（本会话确认）；integration_state：`merged`；execution：`enforced`（本执行器已验证的配置/租约/工具/进程边界）；阶段审批仍为 manual。
|
||||
|
||||
**这是模型分配的唯一配置文档。** 用户调整下列表格；主 Agent 每次派发前读取，并把解析结果写入[派发记录](templates/subagent-stage-record.md)。`scripts/pi_subagents.py` 已直接解析本文件，Cursor MCP 提供角色预览、派发与结果查询；每次新派发读取配置，旧请求保留旧摘要。实测与边界见[运行说明](2026-09-24-pi-subagent-executor.md)和[报告](../test-reports/2026-09-24-pi-executor-test-report.md)。完整流程见[协作规范](2026-09-24-subagent-workflow-standard.md)。
|
||||
|
||||
## 1. 日常调整入口
|
||||
|
||||
| 想调整什么 | 修改位置 | 生效方式 |
|
||||
|---|---|---|
|
||||
| 某角色的默认模型 | §3 对应角色的“默认模型”列 | 修改后递增 config_revision；下一次派发读取 |
|
||||
| 复杂任务的升级去向 | §3 “升级角色”列 | 升级时保留原报告与原因；以目标角色重新派发 |
|
||||
| 启停某角色 | §3 enabled 列 | false 时不自动派发；引用该角色的升级关系须同时调整；必需职责暂停或显式重新分配，不能跳过门禁 |
|
||||
| 允许使用的 provider/model | §2 模型池 | 使用本机精确 ID；新增模型需用户明确调整授权范围并更新程序硬边界校验 |
|
||||
| 并发量、失败处理 | §4 | 主 Agent 按配置与任务实际资源取更严格边界 |
|
||||
| 只改本次任务 | 在任务主记录写 override | 记录用户指令、角色、原值/新值、期限；不改全局默认 |
|
||||
|
||||
文档中表格值为配置；其他文件只引用本文件，不重复维护模型名。用户可以直接编辑，也可以说“把本任务 code_review 改用 qwen_max”或“以后 report 都用 glm_full”。后者需按仓库 worktree/受控集成流程保存。
|
||||
|
||||
字段规则：enabled 只取 true/false；默认模型引用 §2 的 alias；升级角色引用 §3 的 role_id，或 none；缺字段、未知 alias、循环升级、角色越权时停止该派发并报告错误，不自行猜测模型。
|
||||
|
||||
## 2. 允许的模型池
|
||||
|
||||
主会话：**Cursor，模型选择 Auto**；工程子任务：**gmktec 本机 PI CLI**。这份配置不改变 Cursor UI 模型开关、PI 全局默认设置或产品 PI Agent Runner。
|
||||
|
||||
| alias | provider | model（精确 ID） | 使用限制 |
|
||||
|---|---|---|---|
|
||||
| qwen_max | qwen-token-plan-cn | qwen3.8-max | 可分配分析、规划、报告与复核 |
|
||||
| qwen_flash | qwen-token-plan-cn | qwen3.8-flash | 默认检索、资料与初稿；复杂任务升级 |
|
||||
| glm_full | zai-coding-cn | glm-5.3 | 默认评估、独立审查和复杂归因 |
|
||||
| glm_flash | zai-coding-cn | glm-5.3-flash | 默认测试执行与证据收集；复杂判断升级 |
|
||||
| minimax_aux | minimax-cn | MiniMax-M3 | 默认停用，仅明确启用后用于易核验辅助任务；不能承担关键判断 |
|
||||
|
||||
本机 provider 是 qwen-token-plan-cn；用户提到的 qwen-token-plan 在此明确映射到该通道。相同模型名出现在其他 provider 不构成可替换授权。M3 不进入规划、代码审查、根因裁决、最终验收或主力自动备用链；需要改变这些限制时由用户明确修订本节。
|
||||
|
||||
目录核对：2026-09-24，通过本机 pi 的离线 --list-models 核实以上五个组合。存在于目录不等于远端连通、工具调用、性能和任务质量已实测。
|
||||
|
||||
## 3. 角色路由表
|
||||
|
||||
代码实施与修复固定由 **Cursor Auto** 承担；下表只路由 PI 子任务。PI 不修改产品代码或测试源码，所需修复/新测试交回 Cursor。
|
||||
|
||||
| role_id | 工作 | enabled | 默认模型 | 升级角色 | 执行边界 |
|
||||
|---|---|---|---|---|---|
|
||||
| research | 检索、代码定位、资料摘录、需求初稿 | true | qwen_flash | planning | 只读；结论回传主 Agent |
|
||||
| planning | 需求分析、方案制定、复杂问题综合分析 | true | qwen_max | none | 只读；保留假设与依据 |
|
||||
| requirements_review | 独立评估需求与影响 | true | glm_full | none | 新上下文；不代替用户取舍 |
|
||||
| plan_review | 独立方案审查 | true | glm_full | none | 不自审自己编制的方案 |
|
||||
| code_review | 代码审查与回归风险检查 | true | glm_full | none | 冻结 diff；不修改被审内容 |
|
||||
| diagnosis | 复杂失败归因、跨模块机制分析 | true | glm_full | none | 只读分析；复现操作由 test_run 在授权环境执行 |
|
||||
| test_run | 按已批准验证计划执行测试、收集证据、初步分析 | true | glm_flash | diagnosis | 仅批准命令、测试产物与环境；不修改源码 |
|
||||
| acceptance_check | 按既定 AC 执行检查、核对真实证据 | true | glm_flash | diagnosis | 不代签最终验收；涉及业务取舍交 acceptance_owner |
|
||||
| stage_notes | 阶段记录与报告初稿 | true | qwen_flash | report | 忠实整理原证据；主 Agent 持锁落盘 |
|
||||
| report | 最终报告、复杂材料综合 | true | qwen_max | none | 汇总不能改写原始失败或推导未验证的 PASS |
|
||||
| auxiliary | 格式整理、清单提取等易核验工作 | false | minimax_aux | none | 明确启用后派发；保留来源供核验 |
|
||||
|
||||
一个模型可承担多种角色，但派发必须区分上下文与职责。即使用户将规划和审查映射到同一模型，独立审查仍须新上下文/不同执行实例；模型不同也不自动证明审查独立。
|
||||
|
||||
最终验收责任继续归任务声明的 acceptance_owner；主 Agent 核对证据与权限后推进。test_run 和 acceptance_check 的输出是检查结果，不能只因模型返回“通过”就放行。
|
||||
|
||||
## 4. 执行与升级参数
|
||||
|
||||
| 参数 | 默认值 | 语义 |
|
||||
|---|---|---|
|
||||
| max_parallel_pi_tasks | 2 | 同时运行的 PI 子任务上限；路径冲突/共享环境锁优先 |
|
||||
| implementation_executor | cursor_auto | 实施和修复不派给 PI；改此边界需要用户明确授权 |
|
||||
| unavailable_action | pause_role | 模型或通道不可用时暂停对应角色；可继续无依赖工作 |
|
||||
| automatic_fallback | none | 不静默换模型/换 provider；不因超时降级到 M3 |
|
||||
| reload_boundary | next_dispatch | 新任务/下一次派发读取；不修改正在运行的子任务 |
|
||||
| recursive_delegation | false | 仅主 Agent 派发；PI 子任务需要协作者时返回建议 |
|
||||
|
||||
升级触发：Flash 无法解释失败、证据互相矛盾、涉及跨模块机制或超出已批准验证计划。升级用于质量不足，不是网络故障重试；结果未知先核对副作用，流程遵循协作规范。
|
||||
|
||||
本次用户覆盖 > 本文件默认；仓库授权/写锁/验收边界始终约束执行。对文档中已允许角色和模型的任务级调整，不重复索要已经给出的许可；自动化程序、日志和子报告中的“配置已批准”不能替代用户来源。
|
||||
|
||||
## 5. 配置更改与追溯
|
||||
|
||||
1. 在任务 worktree 调整本文件；全局默认修改随受控集成发布。本轮已合入本地 dev；新任务从 dev 创建后使用此配置，调整后仍需受控集成。
|
||||
2. 更新 config_revision；保留修改原因和用户来源。派发前核对角色、模型池和升级关系。
|
||||
3. 每次派发记录配置路径、config_revision、文件 SHA-256、role_id、configured provider/model、任务覆盖和原因；已有子任务沿用自己的配置快照。
|
||||
4. PI 启动时按精确 provider/model 传递，不能省略参数后依赖 ~/.pi/agent/settings.json。启动记录或可信响应元数据不可核验实际模型时填 actual_model=unknown。
|
||||
5. 修改配置不产生代码写入、环境操作、push、部署或清理授权；报告/输出由主 Agent 按现有租约规则保存。
|
||||
6. 回退时恢复先前角色值，递增配置修订并记录来源；不要覆盖历史派发记录或把失败改成成功。
|
||||
|
||||
初始决策依据：用户指定五模型池；明确“代码实施还是让 cursor 来”；反馈 M3 能力有限；随后确认“M3 移出默认流程、仅可选辅助”，并要求提供可调整配置文档。
|
||||
@@ -1,165 +0,0 @@
|
||||
# 主 Agent 与 Subagent 协作流程规范（草案）
|
||||
|
||||
修订：`subagent-workflow-2026-09-24-r2`；owner：Codex；规则状态：`proposed`；执行能力：`manual`；effective_commit：无。
|
||||
本流程规范仍为待审稿；用户已确认 Cursor 实施、本机 PI 分析/审查/验证及模型默认分工，具体值唯一维护在[模型配置](2026-09-24-subagent-model-config.md)。规则批准与受控集成后才进入 active；文档存在不表示 PI 调度器已接入。
|
||||
研究与来源见[研究报告](../audit/2026-09-24-subagent-workflow-research.md)，本次授权及交付状态见[任务](short-term/2026-09-24-subagent-workflow-standard.md)。
|
||||
|
||||
## 1. 目标、适用范围和权威
|
||||
|
||||
用户在 Cursor 主会话保持 Auto；Cursor 负责主协调、代码实施和修复，通过 gmktec 本机工程 PI CLI 委派分析、审查、测试和报告。每阶段产生可恢复记录。此配置不自动适用其他客户端或 Herdr。
|
||||
|
||||
本规范只定义角色、阶段、交接和证据引用。授权边界沿用 [AGENTS](../../AGENTS.md)，写锁/候选合并/环境/清理沿用 [worktree 操作规范](2026-09-21-agent-worktree-workflow.md)，测试层级沿用[验证契约](2026-09-21-validation-contract.md)，问题闭环沿用[既有规范](2026-09-23-issue-learning-workflow.md)。不建立第二套测试门禁。
|
||||
|
||||
普通 Cursor 会话不启用 Herdr 角色和固定模型路由；只有明确使用 Herdr 时适用其专门规范。工程 subagent 与产品 PI Agent Runner 分开记录，前者的执行不能替代后者的验收。
|
||||
|
||||
## 2. Auto、授权和推进规则
|
||||
|
||||
- **模型策略**：主会话选择 Auto；PI 子任务按[模型配置](2026-09-24-subagent-model-config.md)的角色、provider 和 model 派发。Cursor 原生 subagent 的 model: inherit 方案已被用户后续选择替代，本规范不以 .cursor/agents 实现 PI 路由。
|
||||
- **能力核验**：首次接入、客户端升级或模型行为异常时，记录客户端版本、角色可发现性、派发 ID、工作目录、配置模型策略及可观察的实际模型；不可见时写 `actual_model=unknown`。不得从自我介绍推断模型。
|
||||
- **证据边界**：记录配置指定值与可核验的实际模型；未核验不声称模型调用成功。模型多样性不替代独立上下文和证据。
|
||||
- **授权策略**：Auto 只表示模型选择，不表示自动授权 shell、外部写入、合并、部署、推送或删除。任务开始记录已有授权，后续不重复询问相同范围。
|
||||
- **默认确认点（待用户采纳）**：需求形成、评估、方案编制可连续进行；方案可审后，一次确认方案与实施范围。已明确授权按该方案端到端执行，则该确认已经满足。只有范围/环境/外部副作用扩大、破坏性动作或需要用户作业务取舍时再确认。
|
||||
- **验收人**：需求阶段明确 acceptance_owner。技术验收检查可由获授权 acceptance_check 执行；产品效果/业务取舍需要用户判定时，技术通过后保留 `acceptance=pending`，不由 Agent 代签。用户预先委托按明确客观标准验收时，记录委托来源和证据即可。
|
||||
- 仅请求研究/方案的任务交付可审产物后结束。实现、运行验证、合并等阶段逐项写 `not_applicable + 原因`，不为了流程齐全擅自执行。
|
||||
|
||||
## 3. 标准流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[建场与授权记录] --> B[形成需求和验收标准]
|
||||
B --> C[评估需求与影响]
|
||||
C --> D[制定方案和验证计划]
|
||||
D --> E{实施授权是否满足}
|
||||
E -->|是| F[实施和开发自测]
|
||||
E -->|否| P[交付可审方案]
|
||||
F --> G[独立代码审查]
|
||||
G -->|需修改| F
|
||||
G -->|通过| H[冻结交付版本并验证]
|
||||
H -->|失败| F
|
||||
H -->|通过| I[构造候选并验证合并结果]
|
||||
I -->|通过| J[受控合入 dev]
|
||||
J --> K[按授权部署与运行验收]
|
||||
K -->|失败| R[保留现场并修复或交接]
|
||||
R --> F
|
||||
K -->|通过或不适用| L[确认交付并归档证据]
|
||||
L --> M[owner退出后独立复查清理]
|
||||
```
|
||||
|
||||
测试计划在方案阶段形成；自测贯穿实施；独立审查和必要测试必须覆盖最终版本。清理安排在验收与证据保存之后。合并前的工程验证与合并后的运行验收分别报告。
|
||||
|
||||
### 阶段、产物和放行条件
|
||||
|
||||
每行都是阶段记录要求，不要求每行一个文件。记录使用[阶段模板](templates/subagent-stage-record.md)。
|
||||
|
||||
| 阶段 | 责任与输入 | 最小产物 | 放行条件 / 失败去向 |
|
||||
|---|---|---|---|
|
||||
| S0 建场 | 主 Agent；用户请求、当前规则、Git/认领状态 | task 主记录：目标、授权、基线、写路径、环境、交付终点、policy_revision | 允许范围明确；持久成果在任务 worktree；按现行入口登记 |
|
||||
| S1 形成需求 | Cursor 与用户，可委派 research/planning；原始描述 | 需求记录：用户场景、范围/非目标、R-ID、AC-ID、优先级、验收人 | 可验证预期明确；影响方案的歧义解决，小型假设标注 |
|
||||
| S2 评估需求 | requirements_review；S1 和当前证据 | 评估报告：现状差距、替代方案、依赖、风险、复杂度和建议 | 结论为 proceed / revise / defer；高风险未知有验证路径；revise 回 S1 |
|
||||
| S3 制定方案 | Cursor 协调 planning 编制、plan_review 独立复核；S2 | 方案：改动位置、接口/数据影响、实施依赖、写者、验证矩阵、恢复方案；附方案审查结论 | AC 映射到验证项；必要权限齐备；授权不足交付方案等待；设计疑问回 S2 |
|
||||
| S4 实施与自测 | Cursor；已授权方案 | 实施记录：变更、提交、偏差、自测与失败记录 | 实现满足方案且自测有证据；范围变化回 S1/S3；不得降低 AC 迁就实现 |
|
||||
| S5 独立代码审查 | code_review；需求/方案、base/head、完整差异 | 审查报告：范围、审查者、严重度、位置、依据、处置与复核 | 无未解决阻断项；修复回 S4，变更后的代码需复核 |
|
||||
| S6 交付验证 | test_run；冻结版本、AC、验证契约 | 测试报告：预期用例、实际命令/输入/输出、环境、SHA、PASS/FAIL/SKIP/未运行 | 适用必需项均通过；SKIP/基础设施失败保留阻塞；失败回 S4 或 S3 |
|
||||
| S7 候选与集成 | 串行集成执行者；S5/S6、最新 dev D、冻结 T | 集成报告：D/T/M、候选验证收据、锁内结果、实际 dev | 按现行 --no-ff 候选与 --ff-only 入口；D/T/M 变化须重新准入 |
|
||||
| S8 运行与交付验收 | acceptance_check + acceptance_owner；受控制品、AC | 验收报告：实际制品、环境、用户流程、持久状态、逐项 AC 结论 | 所需运行/UI 验收通过；无运行影响写 not_required；失败不清理、不冒充完成 |
|
||||
| S9 归档与清理 | 主 Agent 固化证据，owner 退出后维护者执行清理 | 收口报告：提交/集成/部署/远端/cleanup 分离；归档证据、清理结果与遗留 owner | 满足现行普通 remove/-d 条件；拒绝保留 pending，登记触发和接管者 |
|
||||
|
||||
S5 与 S6 可以在同一不可变版本上并行；必要产物必须都回来才能进入 S7。测试产生构建目录/缓存/数据也算写副作用，先核对其环境和锁。code_review 阅读稳定 Git 快照，不在 Cursor 正在改写的工作树上宣布最终通过。
|
||||
|
||||
S7 候选需执行该范围的真实检查，不能用分支自测替代合并结果验证。S8 后新增的报告提交也需受控集成；分别记录被测业务 SHA 与报告 SHA，说明仅文档变化的复用依据。影响运行内容的后续变更使相关验收失效。
|
||||
|
||||
## 4. 角色和分工
|
||||
|
||||
角色是职责，不要求每阶段单独启动一个进程。精确 role_id、enabled、默认模型和升级链只维护在[模型配置](2026-09-24-subagent-model-config.md)，下表说明权限边界。
|
||||
|
||||
| 角色 | 职责 | 写权限和独立性 |
|
||||
|---|---|---|
|
||||
| Cursor / coordinator | 与用户对话、授权核对、任务图、派发、证据汇总、冲突处理、推进门禁和交接 | 唯一任务协调者；报告汇总不改变原作者/证据/结论；不能从子报告推导额外授权 |
|
||||
| research / planning / report / stage_notes | 需求影响、方案、资料和报告 | 默认只读；返回结构化报告，由主 Agent 落盘；若编制方案，另一个上下文审查方案 |
|
||||
| Cursor / implementation | 实施方案、修复问题、编写和修改测试源码 | 产品和测试源码的实施者；按认领/租约操作，PI 建议交回 Cursor 处理 |
|
||||
| requirements_review / plan_review / code_review / diagnosis | 独立评估、审查与复杂故障归因 | 新的只读上下文；不修改被审内容；发现问题返回 Cursor；复现交给获授权的 test_run |
|
||||
| test_run / acceptance_check | 按冻结 AC 和已批准计划执行验证，核对真实行为 | 仅写批准的测试产物/环境；不改源码、不代签最终验收，需要修复交回 Cursor |
|
||||
| integrator / maintainer | 候选验证、受控合并；owner 退出后的清理 | 串行短时角色，使用现有工具/权限；不能把长驻 worker 同时当作可删除的 worktree owner |
|
||||
|
||||
同模型的独立上下文可以提供独立检查，但不消除共同盲区；验证仍以源码、命令和用户流程证据为准。主 Agent 自审只能记录 self_review。要求独立审查的代码任务如无 subagent 能力，交给另一个独立会话/人员；该项完成前不自动放行。低风险纯文档可自检并记录理由。
|
||||
|
||||
## 5. 何时派发与如何并行
|
||||
|
||||
- 适合派发 PI：较长只读研究、独立审查、按批准计划验证、报告整理。代码实施和修复保留给 Cursor。
|
||||
- 主 Agent 直接处理：一次定位、简短文案、单一顺序操作；仍留下对应阶段记录。无需为了覆盖阶段机械启动九个 Agent。
|
||||
- 并发上限及递归委派规则以模型配置为准；资源不足串行。它是项目预算，不是平台上限；子 Agent 发现进一步分解需求先返回建议。
|
||||
- 先画依赖再并行；有先后依赖的任务等待前置证据。有相同文件、公共 lockfile、路由、迁移号或共享环境的写任务不能同时认领。
|
||||
- 同一任务 worktree 的源码写者为 Cursor，PI 只读任务读取冻结快照；只读报告由 Cursor 持锁保存。PI 验证涉及产物/环境写入必须在有效 agentctl supervisor 下运行；无法保证时停止执行并报告条件缺失。
|
||||
- 若另行开展多 Cursor 并行实施，仍须独立登记 worktree，各自从明确 dev SHA 创建；父子关系用 parent_task_id/subtask_id 关联。此条不授权 PI 实施代码。
|
||||
- 父任务汇总子任务成果，源码仍由 Cursor 实施。涉及测试产物写入的子任务登记独立操作 ID/路径；只读子审查复用父任务文档，不重复创建任务链。子分支结果通过现行候选集成流程交付；不能由 Cursor 的自动隔离/自动合并绕过本仓注册和准入。
|
||||
- 有后台任务时，主 Agent 可继续独立工作，但不得在结果未回收时发布依赖它的 PASS、合并或清理。各子任务的工具可用性不代表授权可用性。
|
||||
|
||||
## 6. 派发、回传与失败处理
|
||||
|
||||
每次派发至少包含：
|
||||
|
||||
1. parent_task_id、subtask_id、role_id、具体目标、输入版本（需求/方案/代码 SHA）；配置路径、config_revision、文件 SHA-256、解析后的 provider/model 和任务覆盖依据。
|
||||
2. 需要读的规范和证据、已有用户授权来源、明确的非目标。
|
||||
3. 工作目录、允许写路径、环境、mutex/租约执行方式；只读者明确只读。
|
||||
4. 完成条件、输出格式/报告路径、需要验证的 AC；子 Agent 不依赖未传入的主会话历史。
|
||||
5. 预算（时间或步骤）、进度回传点、失败/超时和副作用核对方式。
|
||||
|
||||
回传至少包括：执行身份/PI run_id、配置版本与指定/实际模型、实际输入版本、结果与证据、变更文件/提交、实际命令与环境、结论、缺项/风险、遗留进程/产物。主 Agent 校验路径、版本和证据后标记 accepted；子 Agent 自报 done 只表示执行结束。
|
||||
|
||||
- 分开记录 run_status（running/succeeded/failed/cancelled/unknown）与 verdict（pass/changes_required/blocked/not_applicable），不可把退出成功等同质量通过。
|
||||
- 超时/失联先检查进程、worktree、Git 和外部副作用；结果未知时保留 unknown，不同时重派同一写任务。纯只读且确认无副作用的失败可有限重试，并保留原记录。
|
||||
- 审查/验证角色有异议时，主 Agent 依据原需求和证据裁决。能修复则回 S4；需要业务取舍则向用户汇总一个关键问题，不以多数投票覆盖阻断证据。
|
||||
- 连续两轮修复仍未解决同类阻断时，停止机械重试，回 S2 重查机制/测试前提；授权内可继续研究。不得为放行删除失败用例或降低 AC。
|
||||
- 用户中断、客户端退出、上下文压缩时，先固化阶段、版本、未回收子任务、owner 和接管条件；恢复后从首个未满足门禁继续，不能整条流程重跑或直接跳到收口。
|
||||
|
||||
## 7. 文档与报告契约
|
||||
|
||||
“一步一记录”，无需“一步一文件”。现有文件优先复用，原始证据只存一处：
|
||||
|
||||
| 任务类型 | 最小文档集合 |
|
||||
|---|---|
|
||||
| 信息问答，无持久成果或运行副作用 | 对话答复 |
|
||||
| 小型规范/研究/低风险变更 | 一个 task 或分析主文档，含适用阶段、验证与交接 |
|
||||
| 标准功能/缺陷修复 | task + 方案 + 报告；评估/实施/审查/测试/验收可为清楚分段 |
|
||||
| 跨模块、迁移或部署 | task + 必要 plan + 分开的审查/测试/验收证据；handoff 仅在独立信息有价值时拆分 |
|
||||
|
||||
每份阶段记录包含 stage_id、输入版本、producer、reviewer/独立性、decision、证据链接、缺项和下一步。需求用 R-ID，验收用 AC-ID，测试用 T-ID；报告提供 R → AC → 改动 → 审查 → 测试 → 运行验收映射，避免仅列“文档已生成”。
|
||||
|
||||
路径沿用 .doc taxonomy：任务在 ops/short-term，研究/审查在 audit，方案在 remediation 或既有 ops 主文档，独立测试/验收在 test-reports，附件在其 assets。只读 subagent 由主 Agent 保存原始结论及必要摘录，标明“由主 Agent 转存”与 agent_id；不伪造子 Agent 已写文件。
|
||||
|
||||
任务 status 继续只有 planned/in_progress/blocked/done/cancelled；phase 与 review_state、integration_state、deployment、cleanup、remote_sync、acceptance 独立记录。done 取决于授权交付终点。清理待办不扩充任务状态，但必须有人接管。需求验收 pending 时，若验收属于授权交付终点，任务不能 done。
|
||||
|
||||
## 8. Cursor → 本机 PI 接入（任务分支已实现）
|
||||
|
||||
### 配置与能力边界
|
||||
|
||||
用户已明确选择 Cursor Auto 主协调和实施、gmktec 本机 PI 承担子任务；原 r1 的 Cursor 原生 .cursor/agents + inherit 方案废止，历史研究保留说明。当前[模型配置](2026-09-24-subagent-model-config.md)可人工调整，由执行器每次派发读取；不是 PI 原生配置格式，不改变 PI 全局模型设置。CLI/MCP 接入与限制见[运行说明](2026-09-24-pi-subagent-executor.md)，实际验证见[报告](../test-reports/2026-09-24-pi-executor-test-report.md)。
|
||||
|
||||
PI 模型和角色路由以配置文档为唯一来源。主 Agent 根据任务读取 role_id，显式传入 provider/model、独立会话、输入版本、工作目录与工具范围，收取结果后按本规范形成阶段记录。不能把主会话可用工具全部自动授予子任务。
|
||||
|
||||
- 只读研究/审查不需要 bash/edit/write；后续接入时显式限制工具，并核对扩展是否引入额外能力。
|
||||
- 测试角色需要执行批准的命令并产生缓存/产物，不能假称只读；将测试工作目录、数据和环境放在批准范围内，使用既有 agentctl 租约。
|
||||
- PI 报告由主 Agent 持锁落盘；PI 不修改业务代码或测试源码。将诊断建议交回 Cursor 实施。
|
||||
- 模型不可用、实际模型不符、配置缺失或未知结果遵循配置和 §6，不隐式换通道或降级。
|
||||
- 普通本机 PI 调度不复用 Herdr 自动审批/模型预算；产品 PI Runner 仍按目标环境批准配置独立验收。
|
||||
|
||||
### 后续接入步骤与验收
|
||||
|
||||
| 步骤 | 变更 | 必需证据 |
|
||||
|---|---|---|
|
||||
| A 文档配置 | 已确认分工，维护模型配置/派发模板；流程整体另按规范登记 | 默认值与用户选择一致；修改可追溯；未合入前不称全仓 active |
|
||||
| B 消除旧规则冲突 | 修订 Cursor 测试规则副本为验证契约指针 | 相关 ISSUE 单独修复验证；本次不改变 Runner |
|
||||
| C 实现派发入口 | 已实现 CLI + 项目 MCP；本地任务分支代码 69ffaa67 | 配置/租约/模型/快照/结果校验与异常回归已验证；dev 集成另记 |
|
||||
| D 实机试运行 | 小型文档任务和受控代码任务（代码由 Cursor 写） | Auto 不需手动切模型；PI 角色/模型/run_id/证据可追溯；不冒充真实产品 PI |
|
||||
| E 异常演练 | 同路径写冲突、PI 失联、必需测试缺项、dev 变化、验收失败、清理拒绝 | 正确暂停/升级；保留失败证据 |
|
||||
| F 工具门禁 | 据试运行决定是否增加阶段校验/hook | 实现和真实负例验收后才将相应能力标 enforced |
|
||||
|
||||
接入验收 V1–V10：V1 Cursor Auto 与配置指定 PI provider/model；V2 授权/需求上下文传递；V3 独立只读审查与报告转存；V4 租约内测试；V5 输入 SHA 变化后复核；V6 写冲突拒绝；V7 缺项不合并；V8 验收失败保留现场；V9 清理拒绝有 owner；V10 中断后恢复。新增 V11：修改配置只影响下一次派发、记录 hash；V12：M3 停用/越权路由及未知 alias 被拒绝。本轮执行器已完成 173 项工程回归与真实 Cursor CLI→MCP→PI 验证，覆盖及未覆盖项以测试报告为准；这不是宣称全部 S0–S9 审批、产品 UI/共享环境或清理已自动执行。
|
||||
|
||||
### 日常使用与调整
|
||||
|
||||
用户只需保持 Cursor Auto，说明任务目标与授权终点；主 Agent 读取本规范和模型配置，按需要派发 PI。修改默认分工只编辑模型配置文档；临时调整写入任务 override，不静默改全局默认。流程、模型配置和某任务授权是三个不同对象。
|
||||
|
||||
用户可以授权“按已确认方案执行到 local dev 集成与 dev 验收”；该授权不会自动包含 push 或晋升 test/main。验收后归档证据，当前 owner 退出后再由独立维护者复查清理。
|
||||
|
||||
回退：调度入口或权限不满足时暂停相应 PI 阶段，保留现场与证据，交回 Cursor 处理；不能以主 Agent 自审替代要求的独立审查。修复接入后再验证。
|
||||
+208
-124
@@ -1,148 +1,232 @@
|
||||
# 当前焦点
|
||||
|
||||
**更新**：2026-09-23（剩余 worktree 收口：go-agentx+FAV 合入 local_dev；注册 worktree 已清；FAV live 仍不放量）。此文件是协调快照；实际分支、进程、执行租约以机器核验为准。能力和发布结论分别见 [FEATURE-MATRIX](../status/FEATURE-MATRIX.md) / [gap-matrix](../remediation/gap-matrix.md)。
|
||||
|
||||
本机 macOS 已可用 `agentctl with`/`docs apply`/`validate`/`integrate`（W1-B 进程层）；共享文档写走 docs apply 收据。
|
||||
**更新**: 2026-09-20
|
||||
**production_ready**: yes（门禁 B1–B4 已签；dev/test schema 53，main schema 52。不把 fallback change report 写成完整 PI）
|
||||
|
||||
## 焦点
|
||||
|
||||
0. **全量未完成计划收口**：FEATURE-MATRIX「模块解耦批次 A–G」→ `done`；多意图 I1 / 语义摘要 S1 / 治理 W4 / rdev / 红线证据已登记残差；红线（FAV live / SWBOOT-10 / D7 物理删 / PI 叙事 flag）不放量。详见 [收口短文](./short-term/2026-09-22-unfinished-batch-closeout.md)。
|
||||
|
||||
1. **DOCREV UI 重跑已 PASS**：main 18 + post-restart UI-15；20 audit + 9 remediation `done`（`management-implementation-plan` 仍方案态）。schema 63；密封 [sealed-ledger-ui00-16-post-20260923T0400Z](../test-reports/assets/2026-09-22-docrev-ui-rerun/sealed-ledger-ui00-16-post-20260923T0400Z/)；证据 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)；worktree cleanup=pending。
|
||||
|
||||
2. **dev→test 已晋升**：`origin/dev@591ea601`（schema 61 门禁绿）；`origin/test@83c6a12a` + tag `rc-v1.1.0-beta.1`；test 环境 health schema=61、Runner `MiniMax-M3`。[报告](../test-reports/2026-09-22-dev-gate-and-test-promotion-test-report.md)。
|
||||
3. **本任务 cleanup=pending**：feature / integrate / promote-test worktrees 待独立维护者按门禁复查后清理；不强删。
|
||||
4. **Agent 规范与 L1 门禁**：R01–R10、共享 .locks 已启用；本机 macOS 租约路径可用（Darwin 进程层已落地），与 Linux 双平台 enforced。
|
||||
1. **2026-09-20 dev→test 晋升完成 (rc-v1.0.0-beta.5)**：已合入 fix/audit-remainder-closeout，完成全量深度测试（Go 短测 46 包全绿、Vite 前端构建/测试通过、治理 PG 集成通过、运行时端点/安全响应头通过）。已合入 test 分支并重建测试环境服务（端口 :8081，schema 53 healthy）。
|
||||
2. **2026-09-19 审计整改批 1–4 done**（合入 `844f757` / `08f4e0b` / `a2a49a6` / `d73bc79`）。dev 已 rebuild 到 schema 53。余项见 [long-term](./long-term/2026-09-19-audit-remainder.md)。
|
||||
3. **Control Center 已移出本仓库**：项目进度由独立统一管理系统承担；本仓库恢复为智能体系统。见 [任务](./short-term/2026-09-19-remove-control-center.md)
|
||||
4. **rdev 模板深度 / document-author-only**：已合入 `origin/dev` 及 `test`
|
||||
5. **红线**：禁止整支 merge FAV；不默认升 `MULTI_INTENT_PLAN_TIER=full`；`SEMANTIC_SUMMARY_REPLACE` 不随 W2 开启；FAV live 观察窗证据驱动；`FAV_DEGRADED_READ=false`；项目 143 只读；SWBOOT-10 保持 fail-closed stub；D7 待合规签字
|
||||
|
||||
## 并行认领
|
||||
|
||||
| owner | task | branch | worktree | mutex | status |
|
||||
|---|---|---|---|---|---|
|
||||
| Cursor | admin-settings-maint-b-2026-09-25 | feature/admin-env-settings-maintenance-2026-09-25 | .worktrees/admin-env-settings-maintenance-2026-09-25 | admin-settings-maintenance | done |
|
||||
| Cursor | dm-migration-2026-09-24-r2 | feature/dm-migration-2026-09-24 | .worktrees/dm-migration-2026-09-24 | dm-migration | done |
|
||||
| Cursor | governance-console-p1-impl-2026-09-24 | feature/governance-console-p1-impl-2026-09-24 | .worktrees/governance-console-p1-impl-2026-09-24 | agentctl-console | done |
|
||||
| Cursor | governance-console-p1-design-2026-09-24 | feature/governance-console-p1-design-2026-09-24 | .worktrees/governance-console-p1-design-2026-09-24 | agentctl-console-design | done |
|
||||
| Cursor | governance-visibility-p0-2026-09-24 | feature/governance-visibility-p0-2026-09-24 | .worktrees/governance-visibility-p0-2026-09-24 | agentctl-visibility | done |
|
||||
| Cursor | worktree-cleanup-closeout-2026-09-24 | feature/worktree-cleanup-closeout-2026-09-24 | .worktrees/worktree-cleanup-closeout-2026-09-24 | worktree-cleanup | in_progress |
|
||||
| Cursor | non-author-closeout-2026-09-24 | feature/non-author-closeout-2026-09-24 | .worktrees/non-author-closeout-2026-09-24 | docs+git:dev | done |
|
||||
| Cursor | integrate-non-author-docs-2026-09-24 | feature/integrate-non-author-docs-2026-09-24 | .worktrees/integrate-non-author-docs-2026-09-24 | git:dev | done |
|
||||
| Cursor | non-author-member-access-docs-2026-09-24 | feature/non-author-member-access-2026-09-24 | .worktrees/non-author-member-access-2026-09-24 | docs+matrix | done |
|
||||
| Cursor | non-author-member-access-2026-09-24 | feature/non-author-member-access-2026-09-24 | .worktrees/non-author-member-access-2026-09-24 | docgov+iam-authz+workflow-gov | done |
|
||||
| Cursor | integrate-free-collab-2026-09-24 | feature/integrate-free-collab-2026-09-24 | .worktrees/integrate-free-collab-2026-09-24 | integrate-dev | done |
|
||||
| Cursor | cursor-governance-hooks-2026-09-24 | feature/cursor-governance-hooks-2026-09-24 | .worktrees/cursor-governance-hooks-2026-09-24 | cursor-governance | done |
|
||||
| Cursor | governance-catalog-2026-09-24 | feature/governance-catalog-2026-09-24 | .worktrees/governance-catalog-2026-09-24 | agent-workflow-governance+catalog | done |
|
||||
| Codex | subagent-workflow-standard-2026-09-24-land | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | pi-subagent-integration | done |
|
||||
| Cursor/Codex | subagent-workflow-standard-2026-09-24-executor | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | pi-subagent-executor | done |
|
||||
| Codex | subagent-workflow-standard-2026-09-24-config-r2 | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | subagent-workflow-docs | done |
|
||||
| Codex | subagent-workflow-standard-2026-09-24 | feature/subagent-workflow-standard-2026-09-24 | .worktrees/subagent-workflow-standard-2026-09-24 | subagent-workflow-docs | done |
|
||||
| Cursor | integrate-gate-nightly-fixes-b-2026-09-24 | feature/integrate-gate-nightly-fixes-b-2026-09-24 | .worktrees/integrate-gate-nightly-fixes-b-2026-09-24 | git:dev | done |
|
||||
| Cursor | integrate-gate-nightly-fixes-2026-09-24 | feature/integrate-gate-nightly-fixes-2026-09-24 | .worktrees/integrate-gate-nightly-fixes-2026-09-24 | git:dev | done |
|
||||
| Cursor | integrate-docs-gate-promo-report-2026-09-24 | feature/integrate-docs-gate-promo-report-2026-09-24 | .worktrees/integrate-docs-gate-promo-report-2026-09-24 | git:dev | done |
|
||||
| Cursor | promote-rc-beta3-c-2026-09-24 | feature/promote-rc-beta3-c-2026-09-24 | .worktrees/promote-rc-beta3-c-2026-09-24 | git:test+env:test+docs | done |
|
||||
| Cursor | dev-full-gate-test-promo-2026-09-24 | feature/dev-full-gate-test-promo-2026-09-24 | .worktrees/dev-full-gate-test-promo-2026-09-24 | git:dev+env:dev+env:test+docs | done |
|
||||
| Cursor | gate-promo-current-close-2026-09-24 | feature/gate-promo-current-close-2026-09-24 | .worktrees/gate-promo-current-close-2026-09-24 | docs:admin+docs | done |
|
||||
| Cursor | docs-gate-promo-report-2026-09-24 | feature/docs-gate-promo-report-2026-09-24 | .worktrees/docs-gate-promo-report-2026-09-24 | docs+git:dev | done |
|
||||
| Cursor | admin-password-reset-2026-09-24 | feature/admin-password-reset-2026-09-24 | .worktrees/admin-password-reset-2026-09-24 | auth+env:test | done |
|
||||
| Cursor | fix-fav-staging-uuid-2026-09-24 | fix/fix-fav-staging-uuid-2026-09-24 | .worktrees/fix-fav-staging-uuid-2026-09-24 | artifactvault | done |
|
||||
| Cursor | gate-e1a-unique-project-name-2026-09-24 | fix/gate-e1a-unique-project-name-2026-09-24 | .worktrees/gate-e1a-unique-project-name-2026-09-24 | docnotify | done |
|
||||
| Cursor | gate-unhook-docquery-2026-09-24 | fix/gate-unhook-docquery-2026-09-24 | .worktrees/gate-unhook-docquery-2026-09-24 | server+docquery | done |
|
||||
| Cursor | integrate-jev-assist-land-2026-09-24 | feature/integrate-jev-assist-land-2026-09-24 | .worktrees/integrate-jev-assist-land-2026-09-24 | git:dev | done |
|
||||
| Cursor | integrate-codegraph-fixup2-2026-09-24 | feature/integrate-codegraph-fixup2-2026-09-24 | (removed) | git:dev | done |
|
||||
| Cursor | integrate-codegraph-governance-2026-09-24 | feature/integrate-codegraph-governance-2026-09-24 | (removed) | git:dev | done |
|
||||
| Cursor | codegraph-governance-r2-2026-09-24 | feature/codegraph-governance-2026-09-24 | .worktrees/codegraph-governance-2026-09-24 | agent-workflow-governance+codegraph | done |
|
||||
| Cursor | jev-dev-shadow-on-2026-09-24 | feature/jev-dev-shadow-on-2026-09-24 | .worktrees/jev-dev-shadow-on-2026-09-24 | env:dev+jevdecide | done |
|
||||
| Cursor | jev-product-closeout-2026-09-24 | feature/jev-product-closeout-2026-09-24 | .worktrees/jev-product-closeout-2026-09-24 | jevdecide+coordinator | done |
|
||||
| Cursor | jev-product-shadow-2026-09-24 | feature/jev-product-shadow-2026-09-24 | .worktrees/jev-product-shadow-2026-09-24 | jevdecide+coordinator | done |
|
||||
| Cursor | jev-mcp-docs-done-2026-09-24 | feature/jev-mcp-docs-done-2026-09-24 | .worktrees/jev-mcp-docs-done-2026-09-24 | jev-mcp+docs | done |
|
||||
| Cursor | jev-mcp-integration-2026-09-24 | feature/jev-mcp-integration-2026-09-24 | .worktrees/jev-mcp-integration-2026-09-24 | jev-mcp+docs | done |
|
||||
| Cursor | integrate-intent-plan-u9u12-land-2026-09-24 | feature/integrate-intent-plan-u9u12-land-2026-09-24 | .worktrees/integrate-intent-plan-u9u12-land-2026-09-24 | git:dev | done |
|
||||
| Cursor | integrate-pi-narrative-docs-2026-09-23 | feature/integrate-pi-narrative-docs-2026-09-23 | .worktrees/integrate-pi-narrative-final-closeout-b-2026-09-23 | git:dev | done |
|
||||
| Cursor | pi-narrative-final-closeout-b-2026-09-23 | feature/pi-narrative-final-closeout-b-2026-09-23 | .worktrees/pi-narrative-final-closeout-2026-09-23 | docgov | done |
|
||||
| Cursor | chat-semantic-d3-matrix-land-2026-09-23 | feature/chat-semantic-d3-matrix-land-2026-09-23 | .worktrees/chat-semantic-d3-matrix-land-2026-09-23 | chat | done |
|
||||
| Cursor | intent-plan-i2-rollout-b-2026-09-24 | feature/intent-plan-i2-rollout-2026-09-24 | .worktrees/intent-plan-i2-rollout-2026-09-24 | intent-plan | in_progress |
|
||||
| Cursor | intent-plan-i2-impl-2026-09-24 | feature/intent-plan-i2-shadow-allowlist-2026-09-24 | .worktrees/intent-plan-i2-shadow-allowlist-2026-09-24 | intent-plan | in_progress |
|
||||
| Cursor | closeout-claim-removed-2026-09-23 | feature/closeout-claim-removed-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
|
||||
| Cursor | module-batches-ag-status-fix-2026-09-23 | feature/module-batches-ag-status-fix-2026-09-23 | .worktrees/module-batches-ag-status-fix-2026-09-23 | module-decoupling-spec | done |
|
||||
| Cursor | fav-constraint-current-2026-09-23 | feature/fav-constraint-current-2026-09-23 | (removed) | git:dev+docs | done |
|
||||
| Cursor | closeout-worktree-cleanup-2026-09-23 | feature/closeout-worktree-cleanup-2026-09-23 | .worktrees/closeout-worktree-cleanup-2026-09-23 | git:dev+worktree-cleanup | done |
|
||||
| Cursor | remaining-worktrees-closeout-2026-09-23 | feature/remaining-worktrees-closeout-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
|
||||
| Cursor | worktree-closeout-cleanup-2026-09-23 | feature/worktree-closeout-cleanup-2026-09-23 | .worktrees/worktree-closeout-cleanup-2026-09-23 | git:dev+worktree-cleanup | done |
|
||||
| Cursor | worktree-closeout-batch-2026-09-23 | feature/worktree-closeout-batch-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
|
||||
| Cursor | agentctl-cursor-integration-close-2026-09-23 | feature/agentctl-cursor-integration-close-2026-09-23 | .worktrees/agentctl-cursor-integration-close-2026-09-23 | agentctl-cursor-integration-close | done |
|
||||
| Cursor | integrate-agentctl-cursor-integration-2026-09-23 | feature/integrate-agentctl-cursor-integration-2026-09-23 | .worktrees/integrate-agentctl-cursor-integration-2026-09-23 | git:dev | done |
|
||||
| Cursor | agentctl-cursor-integration-2026-09-23 | feature/agentctl-cursor-integration-2026-09-23 | .worktrees/agentctl-cursor-integration-2026-09-23 | agentctl-cursor-integration | done |
|
||||
| Cursor | agentctl-mgmt-go-live-close-2026-09-23 | feature/agentctl-mgmt-go-live-close-2026-09-23 | .worktrees/agentctl-mgmt-go-live-close-2026-09-23 | agentctl-mgmt-go-live-close | done |
|
||||
| Cursor | integrate-agentctl-mgmt-go-live-2026-09-23 | feature/integrate-agentctl-mgmt-go-live-2026-09-23 | .worktrees/integrate-agentctl-mgmt-go-live-2026-09-23 | git:dev | done |
|
||||
| Cursor | agentctl-mgmt-go-live-2026-09-23 | feature/agentctl-mgmt-go-live-2026-09-23 | .worktrees/agentctl-mgmt-go-live-2026-09-23 | agentctl-mgmt-go-live | done |
|
||||
| Cursor | w3-u6-current-fix-2026-09-23 | feature/w3-u6-current-fix-2026-09-23 | .worktrees/w3-u6-current-fix-2026-09-23 | w3-u6-current-fix | done |
|
||||
| Cursor | integrate-w3-u6-closeout-2026-09-23 | feature/integrate-w3-u6-closeout-2026-09-23 | .worktrees/integrate-w3-u6-closeout-2026-09-23 | git:dev | done |
|
||||
| Cursor | integrate-matrix-record-id-2026-09-23 | feature/integrate-matrix-record-id-2026-09-23 | .worktrees/integrate-matrix-record-id-2026-09-23 | git:dev | done |
|
||||
| Cursor | w3-u6-closeout-2026-09-23 | feature/w3-u6-closeout-2026-09-23 | .worktrees/w3-u6-closeout-2026-09-23 | w3-u6-closeout | done |
|
||||
| Cursor | matrix-record-id-2026-09-23 | feature/matrix-record-id-2026-09-23 | .worktrees/matrix-record-id-2026-09-23 | matrix-record-id | done |
|
||||
| Cursor | w2-closeout-2026-09-23 | feature/w2-closeout-2026-09-23 | .worktrees/w2-closeout-2026-09-23 | w2-closeout | done |
|
||||
| Cursor | current-projection-2026-09-23 | feature/current-projection-2026-09-23 | .worktrees/current-projection-2026-09-23 | current-projection | done |
|
||||
| Cursor | agentctl-daemon-2026-09-23 | feature/agentctl-daemon-2026-09-23 | .worktrees/agentctl-daemon-2026-09-23 | agentctl-daemon | done |
|
||||
| Cursor | agentctl-handoff-2026-09-23 | feature/agentctl-handoff-2026-09-23 | .worktrees/agentctl-handoff-2026-09-23 | agentctl-handoff | done |
|
||||
| Cursor | agentctl-claim-2026-09-23 | feature/agentctl-claim-2026-09-23 | .worktrees/agentctl-claim-2026-09-23 | agentctl-claim | done |
|
||||
| Cursor | agent-governance-config-2026-09-23 | feature/agent-governance-config-2026-09-23 | .worktrees/agent-governance-config-2026-09-23 | agent-governance-config | done |
|
||||
| Cursor | coordination-db-daemon-impl-plan-2026-09-23 | feature/coordination-db-daemon-impl-plan-2026-09-23 | .worktrees/coordination-db-daemon-impl-plan-2026-09-23 | coordination-db-daemon-impl-plan | done |
|
||||
| Cursor | coordination-db-daemon-2026-09-23 | feature/coordination-db-daemon-2026-09-23 | .worktrees/coordination-db-daemon-2026-09-23 | coordination-db-daemon | done |
|
||||
| Cursor | integrate-pi-runner-response-size-r2-2026-09-23 | feature/integrate-pi-runner-response-size-2026-09-23 | .worktrees/integrate-pi-runner-response-size-2026-09-23 | git:dev | done |
|
||||
| Cursor | modular-decouple-residual-b-2026-09-23 | feature/modular-decouple-residual-2026-09-23 | .worktrees/modular-decouple-residual-2026-09-23 | modular-decouple-residual | done |
|
||||
| Cursor | modular-refactor-impl-plan-2026-09-23 | feature/modular-refactor-impl-plan-2026-09-23 | .worktrees/modular-refactor-impl-plan-2026-09-23 | docs-remediation-modular-impl-plan | done |
|
||||
| Cursor | modular-refactor-review-2026-09-23 | feature/modular-refactor-review-2026-09-23 | .worktrees/modular-refactor-review-2026-09-23 | ops-audit-modular-refactor-review | done |
|
||||
| Cursor | 2026-09-22-status-reconcile | feature/status-reconcile-2026-09-22 | .worktrees/status-reconcile-2026-09-22 | ops-status-reconcile | done |
|
||||
| Cursor | 2026-09-22-dev-prod-ready-test-promotion | feature/dev-prod-ready-test-promotion-2026-09-22 | .worktrees/dev-prod-ready-test-promotion-2026-09-22 | dev-runtime-migration+release-gate+test-promotion | done |
|
||||
| Cursor | integrate-dev-prod-ready-test-promotion-2026-09-22 | feature/integrate-dev-prod-ready-test-promotion-2026-09-22 | .worktrees/integrate-dev-prod-ready-test-promotion-2026-09-22 | git:dev | done |
|
||||
| Cursor | promote-test-2026-09-22 | feature/promote-test-2026-09-22 | .worktrees/promote-test-2026-09-22 | git:test | done |
|
||||
| Codex | 2026-09-21-agent-workflow-governance-adoption | feature/agent-workflow-governance-plan | （本机 clone 后不存在） | agent-workflow-governance | done |
|
||||
| Codex | issue-learning-2026-09-23 | feature/issue-learning-2026-09-23 | .worktrees/issue-learning-2026-09-23 | issue-learning-docs | done |
|
||||
| Codex | systemic-issue-analysis-2026-09-23 | feature/systemic-issue-analysis-2026-09-23 | .worktrees/systemic-issue-analysis-2026-09-23 | systemic-issue-analysis-docs | done |
|
||||
| Codex | modular-contract-standard-2026-09-22 | feature/modular-contract-standard-2026-09-22 | .worktrees/modular-contract-standard-2026-09-22 | modular-contract-docs | done |
|
||||
| Codex | herdr-orchestration-v12 | feature/herdr-orchestration-v12 | .worktrees/herdr-orchestration-v12 | herdr-policy+scripts | done |
|
||||
| Codex | 2026-09-21-agent-governance-implementation | feature/agent-governance-implementation | .worktrees/agent-governance-implementation | agent-governance | done |
|
||||
| Cursor | 2026-09-21-force-material-chunk-index | feature/force-material-chunk-index-2026-09-21 | .worktrees/force-material-chunk-index-2026-09-21 | bizdev+materialindex | done |
|
||||
| Cursor | 2026-09-21-workflow-scope-weighting | feature/workflow-scope-weighting-2026-09-21 | .worktrees/workflow-scope-weighting-2026-09-21 | intent+web+docgov | done |
|
||||
| Cursor | 2026-09-21-upload-parse-ux-dedup | feature/upload-parse-ux-2026-09-21 | .worktrees/upload-parse-ux-2026-09-21 | server+web+storage | done |
|
||||
| Cursor | 2026-09-21-mineru-doc-parsing | feature/mineru-doc-parsing-2026-09-21 | .worktrees/mineru-doc-parsing-2026-09-21 | storage+bizdev+kb | done |
|
||||
| Cursor | 2026-09-21-intent-confirm-stage-aware | fix/intent-confirm-stage-aware-2026-09-21 | .worktrees/intent-confirm-stage-aware-2026-09-21 | intent+web+docgov | done |
|
||||
| Cursor | 2026-09-21-taskrun-status-card | feature/taskrun-status-card-2026-09-21 | .worktrees/feature-taskrun-status-card-2026-09-21 | chat+web+taskrun | done |
|
||||
| Codex | 2026-09-21-agent-workflow-governance-plan | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance-plan | done |
|
||||
| Cursor | 2026-09-21-workflow-doc-key-unification | fix/workflow-doc-key-unification-2026-09-21 | .worktrees/fix-workflow-doc-key-unification-2026-09-21 | docgov+web | done |
|
||||
| Cursor | 2026-09-21-dev-multiuser-four-issues | fix/dev-multiuser-four-issues-2026-09-21 | .worktrees/fix-dev-multiuser-four-issues | projectinstance+docgov | done |
|
||||
|-------|------|--------|----------|-------|--------|
|
||||
| Cursor-Auto | 2026-09-20-bug-hunt-permissions-uploads | fix/bug-hunt-2026-09-20-permissions-and-uploads | - | authz+web+projectworkflow | done |
|
||||
| Cursor | audit-b1-data-consistency | fix/audit-b1-data-consistency | - | docgov+workflow+chat | done |
|
||||
| Cursor | audit-b2-authz-hardening | fix/audit-b2-authz-hardening | - | authz | done |
|
||||
| Cursor | audit-b3-sse-events | fix/audit-b3-sse-events | - | chat+events | done |
|
||||
| Cursor | audit-b4-frontend | fix/audit-b4-frontend | - | web | done |
|
||||
| Cursor-Auto | 2026-09-19-audit-remainder-closeout | fix/audit-remainder-closeout | - | audit-remainder | done |
|
||||
| Antigravity | 2026-09-20-dev-deep-test-and-promotion | feature/dev-deep-test-and-promotion | - | integration | done |
|
||||
| Cursor-Auto | 2026-09-19-remove-control-center | fix/remove-control-center | - | controlcenter | done |
|
||||
| Cursor-Auto | 2026-09-17-control-center-server | feature/control-center-server | - | controlcenter | cancelled |
|
||||
| Kimi | 2026-09-18-user-manual | feature/user-manual | .worktrees/feature-user-manual | docs | done |
|
||||
| Cursor-Auto | 2026-09-18-wave7-roadmap-orchestration | docs/wave7-roadmap-orchestration | - | roadmap-orchestration | done |
|
||||
| Cursor-Auto | 2026-09-18-wave6-doc-drift | docs/wave6-doc-drift | - | doc-drift | done |
|
||||
| Cursor-Auto | 2026-09-18-wave5-deadcode-decisions | fix/wave5-deadcode-decisions | - | deadcode-cleanup | done |
|
||||
| Cursor-Auto | 2026-09-18-wave4-hardening-r1-r8 | fix/wave4-hardening-r1-r8 | - | hardening | done |
|
||||
| Cursor-Auto | 2026-09-18-wave3-test-debt-blindspots | fix/wave3-test-debt-blindspots | - | test-debt | done |
|
||||
| Cursor-Auto | 2026-09-18-wave2-config-flag-align | fix/wave2-config-flag-align | - | infra | done |
|
||||
| Cursor | 2026-09-18-wave1-main-env-fix | fix/wave1-main-env-fix | - | infra | done |
|
||||
| Cursor | 2026-09-18-wave0-p0-bug-fixes | fix/wave0-p0-sse-chat-cache-bugs | - | chat + web | done |
|
||||
| Kimi | 2026-09-17-system-health-check（只读审计，未实施） | - | - | audit | done |
|
||||
| Cursor | 2026-09-17-docgov-modification-proposal-http | feature/docgov-modification-proposal-http | - | docgov | done |
|
||||
| Cursor | 2026-09-17-document-author-only-closeout | feature/document-author-only-plan | - | document-duty-policy | done |
|
||||
| Cursor | 2026-09-17-rdev-template-depth-s1-continued | feature/rdev-template-depth-s1-continued | .worktrees/feature-rdev-template-depth-s1-continued | rdev-templates | done |
|
||||
| Cursor | 2026-09-17-rdev-workflow-integration | feature/rdev-core | - | workflow-def | done |
|
||||
| Cursor | 2026-09-17-rdev-template-depth | feature/rdev-template-depth | .worktrees/feature-rdev-template-depth | rdev-templates | done |
|
||||
| Codex | 2026-09-17-document-author-only-plan | feature/document-author-only-plan | - | document-duty-policy-plan | done |
|
||||
| Cursor | 2026-09-17-initial-load-perf-u2 | feature/initial-load-perf-u2 | - | web + static-delivery | done |
|
||||
| Codex | 2026-09-17-initial-load-performance-plan | feature/initial-load-performance-plan | .worktrees/feature-initial-load-performance-plan | loading-performance-audit | done |
|
||||
| Kimi | 2026-09-17-system-admin-console | feature/system-admin-console | - | web + sysadmin | done |
|
||||
| Cursor-Auto | 2026-09-17-engineering-dashboard | feature/engineering-dashboard | .worktrees/feature-engineering-dashboard | engineering-dashboard | done |
|
||||
| Cursor | 2026-09-17-promote-null-fk-to-test | feature/promote-null-fk-to-test | - | infra | done |
|
||||
| Cursor | 2026-09-17-docgov-optional-duty-null-fk | fix/docgov-optional-duty-null-fk | - | docgov | done |
|
||||
| Cursor | 2026-09-17-leftover-hygiene | chore/leftover-hygiene-2026-09-17 | - | ops | done |
|
||||
| Cursor | 2026-09-17-w2-semantic-summary-shadow | feature/w2-semantic-summary-shadow-live | - | chat | done |
|
||||
| Cursor | 2026-09-17-w3-pi-change-report-narrative | feature/w3-pi-change-report-narrative-live | - | docgov | done |
|
||||
| Cursor | 2026-09-17-w4-multi-intent-u9-u12 | feature/w4-u9-segment-live | - | intent-plan | done |
|
||||
| Cursor | 2026-09-17-w5a-software-bootstrap-ui | feature/w5a-software-bootstrap-ui-pi | - | workflow-design | done |
|
||||
| Cursor | 2026-09-17-w6-fav-subscriber-shadow | feature/w6-fav-subscriber-shadow | - | events | done |
|
||||
| Cursor | 2026-09-17-w7-d7-inventory | feature/w7-d7-data-inventory | - | chat | done |
|
||||
| Cursor | 2026-09-17-promote-dev-to-test | feature/promote-dev-to-test-2026-09-17 | - | infra | done |
|
||||
| Cursor | 2026-09-17-kb-host-auth-fix | fix/kb-host-auth-layered-load | - | infra | done |
|
||||
| Cursor | 2026-09-17-w1-ci-e2e-green-nightly | feature/w1-ci-e2e-green-nightly | - | ci | done |
|
||||
| Cline | 2026-09-16-partial-deferred-completion | docs/partial-deferred-completion-plan | - | architecture-docs | in_progress |
|
||||
| Cursor | dialogue-context-injection-2026-09-25 | feature/dialogue-context-injection-2026-09-25 | /home/weichen/projects/Agent-System/.worktrees/dialogue-context-injection-2026-09-25 | dialogue-ctx | in_progress |
|
||||
| Cursor | dialogue-context-injection-2026-09-25-r2 | feature/dialogue-context-injection-2026-09-25 | .worktrees/dialogue-context-injection-2026-09-25 | dialogue-ctx | done |
|
||||
| Cursor | 2026-09-16-intent-plan-playwright-dual-tab | feature/intent-plan-cards-playwright | .worktrees/feature-intent-plan-cards-playwright | web | done |
|
||||
| Cursor | 2026-09-16-full-backlog-override | docs/override-nogo-full-backlog | - | architecture-docs | done |
|
||||
| Cursor | 2026-09-16-gitea-nightly-docker-datadir | fix/gitea-nightly-docker-datadir | - | ci | done |
|
||||
| Cursor | 2026-09-16-gitea-nightly-host-tools | fix/gitea-nightly-host-tools | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave-leftovers | fix/wave-leftovers-n7-playwright-dod | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave3-pu6-pu8-go-no-go | feature/wave3-pu6-pu8-go-no-go | - | architecture-docs | done |
|
||||
| Cursor | 2026-09-16-wave2c-same-image-digest | feature/wave2c-same-image-digest | - | infra | done |
|
||||
| Cursor | 2026-09-16-wave2b-nightly-promotion-receipt | feature/wave2b-nightly-promotion-receipt | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave2-real-pi-evidence | feature/wave2-real-pi-evidence | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-wave1-race-tempdir-cleanup | fix/race-tempdir-cleanup | - | ci | done |
|
||||
| Cursor | 2026-09-16-wave1-iam-fail-closed | fix/iam-store-fail-closed | - | authz | done |
|
||||
| Cursor | 2026-09-16-feature-matrix-wave0-calibration | feature/feature-matrix-production-readiness-plan | .worktrees/feature-matrix-production-readiness-plan | architecture-docs | done |
|
||||
| Codex | 2026-09-16-feature-matrix-production-readiness-plan | feature/feature-matrix-production-readiness-plan | .worktrees/feature-matrix-production-readiness-plan | architecture-docs | done |
|
||||
| Cursor-Auto | 2026-09-16-matrix-deep-test-promote-test | feature/matrix-deep-test-promote-test | - | infra | done |
|
||||
| Cursor-Auto | 2026-09-16-production-ready-gates | docs/production-ready-flip | - | ci | done |
|
||||
| Cursor-Auto | 2026-09-16-demo-seed-pollution | fix/demo-data-pollution-web | - | web | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u8-task-generate | feature/multi-intent-u8-task-generate | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u7-auto-read | feature/multi-intent-u7-auto-read | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u6-web-cards | feature/multi-intent-u6-web-cards | - | web | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u5-decision-api | feature/multi-intent-u5-decision-api | - | intent-plan | done |
|
||||
| Cursor | 2026-09-16-multi-intent-u4-outbox-projection | feature/multi-intent-u4-outbox-projection | - | events | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u3-intentflow-pg | feature/multi-intent-u3-intentflow-pg | - | intent-plan | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u2-segmenter | feature/multi-intent-u2-segmenter | - | intent | done |
|
||||
| Cursor | 2026-09-15-multi-intent-u1-contracts | feature/multi-intent-u1-contracts | - | architecture-docs | done |
|
||||
| Cursor | app-composition-u11-u12 | feature/app-composition-u11-u12 | - | app | done |
|
||||
| Cursor | chatlog-contextasm-u10 | feature/chatlog-contextasm-u10 | - | chat | done |
|
||||
| Cursor | chat-history-refresh-remediation | fix/chat-history-refresh | - | chat | done |
|
||||
| Cursor | dataset-lifecycle-u9 | feature/dataset-lifecycle-u9 | - | dataset | done |
|
||||
| Cursor | taskrun-runmanifest-u8 | feature/taskrun-runmanifest | - | taskrun | done |
|
||||
| Cursor | document-reliability-m1-live-and-m2 | refactor/document-reliability-pilot | - | workspace | done |
|
||||
| Codex | module-decoupling-remediation-plan | feature/module-decoupling-remediation | - | architecture-docs | done |
|
||||
| Codex | module-decoupling-phase2-plan-review | docs/module-decoupling-ipc-assessment | - | architecture-docs | done |
|
||||
| Cursor | module-decoupling-phase2-docs | feature/module-decoupling-phase2-docs | - | architecture-docs | done |
|
||||
| verifier_antigravity | controlled-content-ui-acceptance | fix/controlled-content-ui-acceptance | - | document-content-ui-acceptance | done |
|
||||
| implementer_cursor | controlled-content-canonical-hash | fix/controlled-content-canonical-hash | - | docgov | done |
|
||||
| Codex | project143-controlled-content-404-diagnosis | fix/project143-controlled-content-404-diagnosis | - | docgov-content-diagnosis | done |
|
||||
| Codex | software-project-bootstrap-plan | feature/software-project-bootstrap-plan | - | workflow-design | done |
|
||||
| Codex | conversation-intent-runtime-state | fix/conversation-intent-state | - | intent | done |
|
||||
| Cursor | conversation-intent-runtime-state | docs/conversation-intent-dual-tab | - | intent | done |
|
||||
| Cursor | document-revision-wave1-6-implementation | feature/document-revision-management | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-runtime-ui03 | fix/document-revision-runtime-ui03 | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-sse-idempotency | fix/document-revision-sse-idempotency | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-active-doc-routing | fix/document-revision-active-doc-routing | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-quality-context | fix/document-revision-quality-context | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-e2e-pending-flow | fix/document-revision-e2e-pending-flow | - | pending-report-ui | done |
|
||||
| Cursor-Auto | document-revision-e2e-reject-routing | fix/document-revision-e2e-reject-routing | - | document-revision-runtime-ui | done |
|
||||
| Cursor-Auto | document-revision-e2e-block-selector | fix/document-revision-e2e-block-selector | - | document-revision-block-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-save-selector | fix/document-revision-e2e-save-selector | - | document-revision-save-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-overlay-selector | fix/document-revision-e2e-overlay-selector | - | document-revision-overlay-selector | done |
|
||||
| Cursor-Auto | document-revision-e2e-overlay-transition | fix/document-revision-e2e-overlay-transition | - | document-revision-overlay-transition | done |
|
||||
| Cursor-Auto | document-revision-second-doc-routing-lease | fix/document-revision-second-doc-routing-lease | - | document-revision-second-doc-routing-lease | done |
|
||||
| Cursor-Auto | document-revision-prelim-output | fix/document-revision-pi-runner-module | - | document-revision-prelim-output | done |
|
||||
| Cursor-Auto | document-revision-editor-hydration-race | fix/document-revision-editor-hydration-race | - | document-revision-editor-hydration-race | done |
|
||||
| Cursor-Auto | document-revision-quality-repair-workspace-contract | fix/document-revision-quality-repair-workspace-contract | - | document-revision-quality-repair-workspace-contract | done |
|
||||
| Cursor-Auto | document-revision-fast-completion-observation | fix/document-revision-fast-completion-observation | - | document-revision-fast-completion-observation | done |
|
||||
| Cursor-Auto | document-revision-workflow-category-navigation | fix/document-revision-workflow-category-navigation | - | document-revision-workflow-category-navigation | done |
|
||||
| Cursor-Auto | document-revision-duty-cell-assertion | fix/document-revision-duty-cell-assertion | - | document-revision-duty-cell-assertion | done |
|
||||
| Cursor-Auto | document-revision-reviewer-duty-sync | fix/document-revision-reviewer-duty-sync | - | document-revision-reviewer-duty-sync | done |
|
||||
| Cursor-Auto | document-revision-post-restart-selector | fix/document-revision-post-restart-selector | - | document-revision-post-restart-selector | done |
|
||||
| Cursor-Auto | document-revision-post-restart-final-snippet | fix/document-revision-post-restart-final-snippet | - | document-revision-post-restart-final-snippet | done |
|
||||
| Cursor-Auto | document-revision-pg-id-remap | fix/document-revision-pg-id-remap | - | document-revision | done |
|
||||
| Cursor-Auto | document-revision-runtime | fix/document-revision-runtime-ui03 | - | docgov | done |
|
||||
| Cursor-Auto | document-revision-runtime-ui-final-report | feature/document-revision-runtime-ui-final-report | - | document-revision-runtime-ui | done |
|
||||
| Cursor-Auto | document-revision-evidence-count | fix/document-revision-evidence-count | - | document-revision-evidence-count | done |
|
||||
| Cursor-Auto | document-revision-session-close | feature/document-revision-session-close | - | document-revision-session-close | done |
|
||||
| Cursor-Auto | vite-frp-allowed-hosts | fix/vite-frp-allowed-hosts | - | web-devserver | done |
|
||||
| implementer_cursor | workflow-plan-409-frozen-and-optional-duties | fix/workflow-plan-409-frozen-and-optional-duties | - | workflow | done |
|
||||
| implementer_cursor | governance-action-level-authz | fix/governance-action-level-authz | - | workflow | done |
|
||||
| Cursor | leftover-branch-cleanup | chore/leftover-branch-cleanup | - | ops | done |
|
||||
| Cursor | event-e0a-production-scope-contract | fix/event-production-scope-contract | - | events | done |
|
||||
| Cursor | event-e0b-dispatcher-pg | feature/events-dispatcher-pg | - | events | done |
|
||||
| Cursor | event-e1a-notify-cutover | fix/event-notify-cutover | - | events | done |
|
||||
| Cursor | event-e1b-workflow-advance | fix/event-workflow-advance | - | events | done |
|
||||
| Cursor | event-e1c-projection-cutover | fix/event-projection-cutover | - | events | done |
|
||||
| Cursor | event-e2-hook-guard | fix/event-e2-hook-guard | - | events | done |
|
||||
| Cursor | doccontent-canonical-boundary | fix/doccontent-canonical-boundary | - | docgov | done |
|
||||
| Cursor | intent-bizdev-boundary | fix/intent-bizdev-boundary | - | intent | done |
|
||||
| Cursor | stageflow-type-ownership | fix/stageflow-type-ownership | - | stageflow | done |
|
||||
| Cursor | bizdev-locator-removal | fix/bizdev-locator-removal | - | bizdev | done |
|
||||
| Cursor | chatflow-orchestration-boundary | fix/chatflow-orchestration-boundary | - | chat | done |
|
||||
| Cursor | phase2-closeout-inventories | feature/phase2-closeout-inventories | - | architecture-docs | done |
|
||||
| Cursor | event-shared-live-cutover | feature/event-shared-live-cutover | - | events | done |
|
||||
| Cursor | pi-typed-result | feature/pi-typed-result | - | pi-agent | done |
|
||||
| Cursor | promote-dev-to-test-2026-09-15 | feature/promote-dev-to-test-2026-09-15 | - | infra | done |
|
||||
|
||||
## 清理接管与遗留现场
|
||||
> 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。
|
||||
|
||||
| 路径/事项 | 分类与保留原因 | cleanup_owner | 复查触发 |
|
||||
|---|---|---|---|
|
||||
| `.worktrees/docrev-ui-rerun-2026-09-22` / `freeform-project-id-bigint` | 已清理 / 目录不存在（2026-09-23 核对） | Cursor | 无 |
|
||||
| `.worktrees/dev-prod-ready-test-promotion-2026-09-22` 等本轮三个 worktree | 已清理 / 目录不存在（2026-09-23 核对） | Cursor | 无 |
|
||||
| Cline `2026-09-16-partial-deferred-completion` | 仍 in_progress；W5–W7 未关闭 | Cline owner / 维护者 | 单独授权实施或交接 |
|
||||
| 保护分支 / FAV 相关 | 已合入 local_dev（例外授权 2026-09-23）；live 未放量；分支/worktree 已删 | Cursor | 无；见 integrate-fav-final 例外登记 |
|
||||
| embedding 401（dmxapi） | 非 blocker 运维债；不挡 PI | 运维 | 换钥后重跑 chunk index |
|
||||
> workflow-plan 409 与治理鉴权 G1–G5 已收口（见 [test-report](../test-reports/2026-09-14-governance-action-level-authz-test-report.md)）。禁止终止或改写项目 143。
|
||||
> `document-reliability-pilot` U11–U12 已合入 `dev@bf59cce` 并 rebuild。`CHAT-INTENT-STATE` 双标签 busy 已 PASS（项目 6275）。禁止 worktree 内 `env-service`。项目 143 只读，禁止终止。
|
||||
> 2026-09-17 leftover 二次收口：[报告](../test-reports/2026-09-17-leftover-hygiene-test-report.md)。已合入 leftover worktree/旁支再拆一轮；`feature/software-project-bootstrap` L1 已在 `dev`（残留关闭 commit 已丢弃）。`fix/clean-test-env-baseline` **不 merge**（前端 demo 清理已放弃；仅保留已挑拣的 `SEED_DEMO_USERS=false`）。extra worktree 仅余 `.worktrees/fix-dev-runtime-data-root-guard`（目录名是 guard，检出的是 `feature/final-artifact-vault`）。**故意不合入、不删**：`feature/final-artifact-vault`、`feature/remove-herdr-agent-settings`、`fix/project143-controlled-content-404-diagnosis`、`fix/dev-runtime-data-root-guard`、`dev-old-linear`。不删 `origin/*`。不整支 merge FAV；不启用 `FAV_DEGRADED_READ`。
|
||||
|
||||
## 集成槽位
|
||||
|
||||
| holder | phase | since | scope | queue |
|
||||
|--------|-------|-------|-------|-------|
|
||||
| - | idle | 2026-09-21 | force-material-chunk-index 已合入 dev 并从主目录 rebuild；项目 6579 候选 535 已确认；schema=61 | - |
|
||||
| - | idle | 2026-09-20 | dev 深度测试全绿；已晋升 test (rc-v1.0.0-beta.5) 并重建测试环境；test 与 dev 均为 schema 53 healthy | - |
|
||||
|
||||
**phase**: `idle` | `merging` | `smoke` | `e2e`
|
||||
|
||||
> 合入 `dev` + 共享容器验证必须串行。实际机器锁/进程优先；详见 [操作规范](./2026-09-21-agent-worktree-workflow.md)。
|
||||
> 合入 `dev` + 共享容器验证必须串行。详见 [AGENTS.md](../../AGENTS.md) §6.3。
|
||||
|
||||
## 受控约束
|
||||
## 环境快照
|
||||
|
||||
- FAV live 仍不放量；`FAV_DEGRADED_READ` 默认 false；不删 `origin/*`（本轮仅前进 local `dev`，不 push）。
|
||||
- 不默认升 `MULTI_INTENT_PLAN_TIER=full`；`SEED_DEMO_USERS=false` 在 test 保持。
|
||||
- D7 对话 ADR 仍待合规签字；追踪表类别 `record` 不授权物理删除。
|
||||
- main 未在本轮晋升。
|
||||
| 环境 | 端口 | schema | 状态 |
|
||||
|------|------|--------|------|
|
||||
| dev | 8080 | **53** | healthy（2026-09-19 `fix/audit-remainder-closeout` rebuild；goose `00053` `document_content_projections`；入口 `index-DOO0-Yh7.js`；`pi-agent`；events `:8088`） |
|
||||
| test | 8081 | **53** | healthy（2026-09-20 `rc-v1.0.0-beta.5` rebuild；goose `00053`；入口 `index-C5YTF8ik.js`；pi-agent `:18866`；events `:8089`） |
|
||||
| main | 8000 | **52** | healthy（`env=main` app+events 对齐；events 先 healthy 后启 app；consumer modes 全 off；Wave 1 已验证） |
|
||||
|
||||
## 活跃入口
|
||||
## SSOT
|
||||
|
||||
- [操作规范](./2026-09-21-agent-worktree-workflow.md) · [规则来源/生效](./2026-09-21-policy-registry.md) · [验证契约](./2026-09-21-validation-contract.md)
|
||||
- [dev 门禁与 test 晋升任务](./short-term/2026-09-22-dev-prod-ready-test-promotion.md) · [报告](../test-reports/2026-09-22-dev-gate-and-test-promotion-test-report.md)
|
||||
- [gap-matrix](../remediation/gap-matrix.md) · [partial-deferred 主任务](./short-term/2026-09-16-partial-deferred-completion.md)
|
||||
| 类型 | 路径 |
|
||||
|------|------|
|
||||
| 文档总地图 | [../README.md](../README.md) |
|
||||
| 模块完成度 | [FEATURE-MATRIX](../status/FEATURE-MATRIX.md)（Wave 0 已校准契约与冻结边界） |
|
||||
| 发布缺口 | [gap-matrix](../remediation/gap-matrix.md)（`production_ready=yes`；Wave 0 IAM 只读未发现旁路） |
|
||||
| 连续性审计/计划 | [audit](../audit/2026-09-16-feature-matrix-production-readiness-audit.md) · [remediation](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md) · [Wave 0 任务](./short-term/2026-09-16-feature-matrix-wave0-calibration.md) |
|
||||
| 测试报告 | [test-reports/](../test-reports/) |
|
||||
| dev→test 晋升前复核 | [research](./research/2026-09-19-pre-test-promotion-review.md)（2026-09-19 只读；静态门禁过，容器未 rebuild，暂不合并） |
|
||||
| D7 盘点（W7） | [audit](../audit/2026-09-17-d7-data-inventory.md) · [报告](../test-reports/2026-09-17-w7-d7-inventory-test-report.md) · ADR 仍 `pending-compliance-signoff` |
|
||||
| Wave 7 编排确认 | [决策记录](./short-term/2026-09-18-wave7-roadmap-orchestration.md) |
|
||||
| Agent 手册 | [AGENTS.md](../../AGENTS.md) |
|
||||
| 意图双标签 busy 交接 | [./handoffs/2026-09-15-conversation-intent-dual-tab.md](./handoffs/2026-09-15-conversation-intent-dual-tab.md) |
|
||||
| 受控正文 hash 漂移 W1–W6 | [../ops/handoffs/2026-09-14-controlled-content-canonical-hash.md](../ops/handoffs/2026-09-14-controlled-content-canonical-hash.md) |
|
||||
| DOCREV ADR | [../adr/2026-09-13-document-version-boundary.md](../adr/2026-09-13-document-version-boundary.md) |
|
||||
| DOCREV 管理测试 | [../test-reports/2026-09-13-document-revision-management-test-report.md](../test-reports/2026-09-13-document-revision-management-test-report.md) |
|
||||
| DOCREV 运行时 UI Round20 | [../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) |
|
||||
| 纯软件项目自举设计 | [../system-design/2026-09-14-software-project-bootstrap-workflow.md](../system-design/2026-09-14-software-project-bootstrap-workflow.md) |
|
||||
| 模块化单体解耦架构 | [../system-design/2026-09-14-module-decoupling-architecture.md](../system-design/2026-09-14-module-decoupling-architecture.md) |
|
||||
| 模块解耦整改计划 | [../remediation/2026-09-14-module-decoupling-refactor-plan.md](../remediation/2026-09-14-module-decoupling-refactor-plan.md) |
|
||||
| Phase 2 方案审阅 | [../audit/2026-09-15-module-decoupling-phase2-plan-review.md](../audit/2026-09-15-module-decoupling-phase2-plan-review.md) |
|
||||
| Phase 2 修订计划 | [../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md) |
|
||||
| 多意图 HITL 复核方案 | [../system-design/2026-09-15-multi-intent-hitl-plan.md](../system-design/2026-09-15-multi-intent-hitl-plan.md) |
|
||||
| 多意图 HITL U1 契约 | [../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md) |
|
||||
| 多意图 HITL U2 分段 | [../test-reports/2026-09-15-multi-intent-u2-segmenter-test-report.md](../test-reports/2026-09-15-multi-intent-u2-segmenter-test-report.md) |
|
||||
| 多意图 HITL U3 PG | [../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md](../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) |
|
||||
| 多意图 HITL U4 投影 | [../test-reports/2026-09-16-multi-intent-u4-outbox-projection-test-report.md](../test-reports/2026-09-16-multi-intent-u4-outbox-projection-test-report.md) |
|
||||
| 多意图 HITL U5 API | [../test-reports/2026-09-16-multi-intent-u5-decision-api-test-report.md](../test-reports/2026-09-16-multi-intent-u5-decision-api-test-report.md) |
|
||||
| 多意图 HITL U6 Web | [../test-reports/2026-09-16-multi-intent-u6-web-cards-test-report.md](../test-reports/2026-09-16-multi-intent-u6-web-cards-test-report.md) |
|
||||
| 多意图 HITL U8 generate | [../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md](../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md) |
|
||||
| 多意图 HITL U7 只读 | [../test-reports/2026-09-16-multi-intent-u7-auto-read-test-report.md](../test-reports/2026-09-16-multi-intent-u7-auto-read-test-report.md) |
|
||||
| 文档可靠性 M1 报告 | [../test-reports/2026-09-14-document-reliability-pilot-test-report.md](../test-reports/2026-09-14-document-reliability-pilot-test-report.md) |
|
||||
| 文档可靠性 M1 活验 | [../test-reports/2026-09-14-document-reliability-pilot-live-test-report.md](../test-reports/2026-09-14-document-reliability-pilot-live-test-report.md) |
|
||||
| 文档可靠性 M2 | [../test-reports/2026-09-14-document-reliability-m2-test-report.md](../test-reports/2026-09-14-document-reliability-m2-test-report.md) |
|
||||
| 文档可靠性 M3 U8 | [../test-reports/2026-09-15-taskrun-runmanifest-u8-test-report.md](../test-reports/2026-09-15-taskrun-runmanifest-u8-test-report.md) |
|
||||
| 文档可靠性 M3 U9 | [../test-reports/2026-09-15-dataset-lifecycle-u9-test-report.md](../test-reports/2026-09-15-dataset-lifecycle-u9-test-report.md) |
|
||||
| 文档可靠性 M4 U10 | [../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md](../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md) |
|
||||
| 文档可靠性 M5/M6 U11–U12 | [../test-reports/2026-09-15-app-composition-u11-u12-test-report.md](../test-reports/2026-09-15-app-composition-u11-u12-test-report.md) |
|
||||
| Track E E2 闭包守卫 | [../test-reports/2026-09-15-event-e2-hook-guard-test-report.md](../test-reports/2026-09-15-event-e2-hook-guard-test-report.md) |
|
||||
| Track E 复盘 | [./research/2026-09-15-track-e-retrospective.md](./research/2026-09-15-track-e-retrospective.md) |
|
||||
| 旁支清点收口 | [../test-reports/2026-09-15-leftover-branch-cleanup-test-report.md](../test-reports/2026-09-15-leftover-branch-cleanup-test-report.md) · [二次收口](../test-reports/2026-09-17-leftover-hygiene-test-report.md) |
|
||||
| SSE/幂等审计 | [../audit/2026-09-13-document-revision-sse-idempotency.md](../audit/2026-09-13-document-revision-sse-idempotency.md) |
|
||||
| 质量门禁自污染审计 | [../audit/2026-09-13-document-revision-quality-gate-self-pollution.md](../audit/2026-09-13-document-revision-quality-gate-self-pollution.md) |
|
||||
| 当前文档路由审计 | [../audit/2026-09-13-document-revision-active-doc-routing.md](../audit/2026-09-13-document-revision-active-doc-routing.md) |
|
||||
| 行动表状态假阳性审计 | [../audit/2026-09-13-document-revision-quality-status-false-positive.md](../audit/2026-09-13-document-revision-quality-status-false-positive.md) |
|
||||
| 待确认报告选择失败审计 | [../audit/2026-09-13-document-revision-pending-report-selection.md](../audit/2026-09-13-document-revision-pending-report-selection.md) |
|
||||
| UI-05b 拒绝路由失败审计 | [../audit/2026-09-13-document-revision-e2e-reject-routing.md](../audit/2026-09-13-document-revision-e2e-reject-routing.md) |
|
||||
| 职责伪造与 ETag 覆盖审计 | [../audit/2026-09-13-document-revision-duty-etag-overwrite.md](../audit/2026-09-13-document-revision-duty-etag-overwrite.md) |
|
||||
| UI-06 块选择器失败审计 | [../audit/2026-09-13-document-revision-block-selector.md](../audit/2026-09-13-document-revision-block-selector.md) |
|
||||
| UI-06 保存选择器失败审计 | [../audit/2026-09-13-document-revision-save-selector.md](../audit/2026-09-13-document-revision-save-selector.md) |
|
||||
| UI-07 纯净阅读取样失败审计 | [../audit/2026-09-13-document-revision-overlay-selector.md](../audit/2026-09-13-document-revision-overlay-selector.md) |
|
||||
| UI-07 transition 中间帧取样审计 | [../audit/2026-09-13-document-revision-overlay-transition.md](../audit/2026-09-13-document-revision-overlay-transition.md) |
|
||||
| UI-11 第二份文档路由与 lease 审计 | [../audit/2026-09-13-document-revision-second-doc-routing-lease.md](../audit/2026-09-13-document-revision-second-doc-routing-lease.md) |
|
||||
| UI-11 prelim_design 缺 output.md 审计 | [../audit/2026-09-13-document-revision-prelim-output.md](../audit/2026-09-13-document-revision-prelim-output.md) |
|
||||
| UI-06 编辑弹窗 hydration 竞态审计 | [../audit/2026-09-13-document-revision-editor-hydration-race.md](../audit/2026-09-13-document-revision-editor-hydration-race.md) |
|
||||
| UI-03 质量修复子工作区契约审计 | [../audit/2026-09-13-document-revision-quality-repair-workspace-contract.md](../audit/2026-09-13-document-revision-quality-repair-workspace-contract.md) |
|
||||
| UI-11 快速完成观测误判审计 | [../audit/2026-09-13-document-revision-fast-completion-observation.md](../audit/2026-09-13-document-revision-fast-completion-observation.md) |
|
||||
| UI-13a 私密分类导航失败审计 | [../audit/2026-09-13-document-revision-workflow-category-navigation.md](../audit/2026-09-13-document-revision-workflow-category-navigation.md) |
|
||||
| UI-13a 职责单元格误判审计 | [../audit/2026-09-13-document-revision-duty-cell-assertion.md](../audit/2026-09-13-document-revision-duty-cell-assertion.md) |
|
||||
| UI-13a reviewer 职责未同步审计 | [../audit/2026-09-13-document-revision-reviewer-duty-sync.md](../audit/2026-09-13-document-revision-reviewer-duty-sync.md) |
|
||||
| UI-03 首次生成 PG ID 误删 baseline | [../audit/2026-09-13-document-revision-pg-id-remap.md](../audit/2026-09-13-document-revision-pg-id-remap.md) |
|
||||
| UI-06 刷新后缓存竞争死锁审计 | [../audit/2026-09-14-document-revision-refresh-cache-race.md](../audit/2026-09-14-document-revision-refresh-cache-race.md) |
|
||||
| 受控正文真实 UI 验收报告 | [../test-reports/2026-09-14-controlled-content-ui-acceptance.md](../test-reports/2026-09-14-controlled-content-ui-acceptance.md) |
|
||||
|
||||
@@ -1,74 +1,72 @@
|
||||
---
|
||||
title: "纯软件项目自举工作流验收清单"
|
||||
status: in_progress
|
||||
status: planned
|
||||
created: 2026-09-14
|
||||
updated: 2026-09-22
|
||||
updated: 2026-09-14
|
||||
related_task: "ops/long-term/2026-09-14-software-project-bootstrap-implementation.md"
|
||||
redline_evidence: "ops/short-term/2026-09-22-redline-evidence.md"
|
||||
---
|
||||
|
||||
# 纯软件项目自举工作流验收清单
|
||||
|
||||
> 不得把设计评审、stub、接口注入或静态 JSON 写成真实功能 / 真实 PI / UI PASS。
|
||||
> **2026-09-22 红线证据批次**（SHA `364ed7f1`）：仅复验无需真实仓写的 L1–L4 子集；L5/L6 **pending auth**。报告：[../../test-reports/2026-09-22-redline-evidence-swboot-test-report.md](../../test-reports/2026-09-22-redline-evidence-swboot-test-report.md)。SWBOOT-10 仍为 fail-closed stub。
|
||||
> 本文件是未来实施验收计划，当前全部用例均为 `NOT RUN`。不得把设计评审、stub、接口注入或静态 JSON 写成真实功能 PASS。
|
||||
|
||||
## 0. 验收分层
|
||||
|
||||
| 层 | 范围 | 可否代替真实 UI | 2026-09-22 红线证据 |
|
||||
|----|------|-----------------|---------------------|
|
||||
| L1 | manifest、profile、模板、quality gate 单元测试 | 否 | 子集 PASS（见 §1） |
|
||||
| L2 | PostgreSQL 迁移、领域服务、API、鉴权、并发 | 否 | 领域 short PASS；PG **NOT RUN**（无 `TEST_DATABASE_URL`） |
|
||||
| L3 | 前端组件、类型、build | 否 | **NOT RUN**（本机缺 `tsc`/`tsx`） |
|
||||
| L4 | stub 小队和固定输出工程测试 | 否 | stub PASS；live PI SKIP |
|
||||
| L5 | 真实 PI Agent Runner | 否，仍需页面验证 | **pending auth** |
|
||||
| L6 | Ubuntu Server 无头浏览器真实页面操作 | 是，最终验收 | **pending auth** |
|
||||
| 层 | 范围 | 可否代替真实 UI |
|
||||
|----|------|-----------------|
|
||||
| L1 | manifest、profile、模板、quality gate 单元测试 | 否 |
|
||||
| L2 | PostgreSQL 迁移、领域服务、API、鉴权、并发 | 否 |
|
||||
| L3 | 前端组件、类型、build | 否 |
|
||||
| L4 | stub 小队和固定输出工程测试 | 否 |
|
||||
| L5 | 真实 PI Agent Runner | 否，仍需页面验证 |
|
||||
| L6 | Ubuntu Server 无头浏览器真实页面操作 | 是，最终验收 |
|
||||
|
||||
## 1. 工程门禁
|
||||
|
||||
### Manifest 与目录
|
||||
|
||||
- [x] `software_bootstrap` 和 `software_delivery` 均可校验（发布/退役全路径未本轮覆盖） — 证据：L1 `TestValidateDefinitionV2_SoftwareManifests` PASS（2026-09-22）
|
||||
- [x] 不兼容 domain 的工作流被过滤 — 证据：`TestCompatibleWithProductDomain` PASS（2026-09-22）
|
||||
- [ ] 新版本不会改变已激活实例的 manifest/template/profile hash — 证据：NOT RUN（需 PG 激活实例）
|
||||
- [x] 医疗正式 key 仍在官方集合且软件 key 并存（非全量黄金回归） — 证据：`TestOfficialWorkflowKeys` PASS（2026-09-22）
|
||||
- [x] 不再依赖“仅三正式 key”硬编码 — 证据：同上 + `TestCreateSoftwareProject_NoMedicalDefaults` PASS
|
||||
- [ ] `software_bootstrap` 和 `software_delivery` 均可校验、发布和退役 — 证据：NOT RUN
|
||||
- [ ] 非 published / 非 selectable / 不兼容 domain 的工作流不出现在项目目录 — 证据：NOT RUN
|
||||
- [ ] 新版本不会改变已激活实例的 manifest/template/profile hash — 证据：NOT RUN
|
||||
- [ ] 医疗现有三工作流及黄金用例无回归 — 证据：NOT RUN
|
||||
- [ ] 不再依赖“三正式 key”或固定文档数量硬编码 — 证据：NOT RUN
|
||||
|
||||
### 数据与迁移
|
||||
|
||||
- [ ] 空数据库从 schema 1 升级并创建项目类型、profile、source binding — 证据：NOT RUN（无 `TEST_DATABASE_URL`）
|
||||
- [ ] 空数据库从 schema 1 升级并创建项目类型、profile、source binding — 证据：NOT RUN
|
||||
- [ ] 旧数据库升级不误分类既有项目 — 证据：NOT RUN
|
||||
- [ ] secret 只存引用，数据库、文档、日志和 prompt 无明文 — 证据：NOT RUN（本批未做 secret 扫描）
|
||||
- [ ] 项目、成员、planning instance、模板账本创建具备幂等事务语义 — 证据：NOT RUN（PG）
|
||||
- [ ] secret 只存引用，数据库、文档、日志和 prompt 无明文 — 证据：NOT RUN
|
||||
- [ ] 项目、成员、planning instance、模板账本创建具备幂等事务语义 — 证据：NOT RUN
|
||||
- [ ] 应用重启后项目、来源、plan、阶段和文档版本可恢复 — 证据：NOT RUN
|
||||
|
||||
### 授权与治理
|
||||
|
||||
- [ ] 非成员无法列出项目、对话、来源、文档、SSE、RAG 或 Agent 结果 — 证据：NOT RUN（需 API/UI）
|
||||
- [ ] 非成员无法列出项目、对话、来源、文档、SSE、RAG 或 Agent 结果 — 证据：NOT RUN
|
||||
- [ ] 非创建者无法激活、推进、选择下一流程或终止 — 证据：NOT RUN
|
||||
- [ ] 客户端伪造 task/stage/duty/repo path 被服务端拒绝 — 证据：NOT RUN（完整 API）；repo path stub 见 §4
|
||||
- [x] collaborative / solo / controlled 预览规则（领域层） — 证据：`TestBuildCreationPreview_*` PASS（solo acknowledgement；privacy+solo 与 controlled_patch 拒绝）
|
||||
- [ ] solo 页面显示“未独立评审” — 证据：NOT RUN（L3/L6）
|
||||
- [x] controlled profile / controlled_patch 禁止未授权执行 — 证据：creation preview + SWBOOT-10 stub PASS
|
||||
- [ ] 激活后 workflow/template/profile/duty 不能直接修改 — 证据：NOT RUN（需激活实例）
|
||||
- [ ] 客户端伪造 task/stage/duty/repo path 被服务端拒绝 — 证据：NOT RUN
|
||||
- [ ] collaborative 模式三权必须不同人 — 证据：NOT RUN
|
||||
- [ ] solo 只允许 creator acknowledgement 且页面显示“未独立评审” — 证据：NOT RUN
|
||||
- [ ] controlled profile 禁止 solo — 证据：NOT RUN
|
||||
- [ ] 激活后 workflow/template/profile/duty 不能直接修改 — 证据：NOT RUN
|
||||
|
||||
### 小队与文档
|
||||
|
||||
- [ ] 每个 executor/template/quality gate/profile 均注册且可解析 — 证据：NOT RUN（全量 registry 未本轮枚举）
|
||||
- [ ] 每个 executor/template/quality gate/profile 均注册且可解析 — 证据：NOT RUN
|
||||
- [ ] 正式任务只能从冻结 doc_task_instance 启动 — 证据：NOT RUN
|
||||
- [ ] 步骤预算、timeout、工作区边界和 manifest 生效 — 证据：NOT RUN
|
||||
- [x] 失败/stub 不改写成真实 PASS — 证据：本报告区分 stub PASS vs L5 pending；LiveMiniMax SKIP
|
||||
- [x] 纯软件项目类型目录无医疗默认术语污染 — 证据：`TestProjectTypesCatalog` / `CreateSoftwareProject_NoMedicalDefaults` PASS
|
||||
- [x] 软件创建默认走 `software_bootstrap` 且无医疗 device 字段 — 证据：同上
|
||||
- [ ] 失败、跳过、fallback、未验证项不会被改写成 PASS — 证据：NOT RUN
|
||||
- [ ] 非医疗默认小队不包含 regulatory — 证据：NOT RUN
|
||||
- [ ] 纯软件模板和回复无医疗默认术语污染 — 证据：NOT RUN
|
||||
|
||||
## 2. Ubuntu Server 真实 UI 前置（L5/L6 — pending auth）
|
||||
## 2. Ubuntu Server 真实 UI 前置
|
||||
|
||||
- [ ] 占用 CURRENT 集成槽位 — 证据：pending auth
|
||||
- [ ] `go vet ./...`、`go test -short ./...`、前端测试/build 通过 — 证据：本批仅跑范围子集 + arch-check；全量 short/前端 pending
|
||||
- [ ] PostgreSQL、app、真实 PI Runner、MiniMax 均 ready — 证据：pending auth
|
||||
- [ ] 明确记录 commit、schema、镜像、模型、BASE_URL 和开始时间 — 证据：pending auth
|
||||
- [ ] 使用官方 Playwright Chromium 容器；宿主无需安装浏览器 — 证据：pending auth
|
||||
- [ ] 若容器不可用，才执行 `npx playwright install --with-deps chromium` — 证据：pending auth
|
||||
- [ ] 禁止 `page.route`、mock/stub、直接写数据库或伪造 API 输出 — 证据：pending auth
|
||||
- [ ] 占用 CURRENT 集成槽位 — 证据：NOT RUN
|
||||
- [ ] `go vet ./...`、`go test -short ./...`、前端测试/build 通过 — 证据：NOT RUN
|
||||
- [ ] PostgreSQL、app、真实 PI Runner、MiniMax 均 ready — 证据：NOT RUN
|
||||
- [ ] 明确记录 commit、schema、镜像、模型、BASE_URL 和开始时间 — 证据：NOT RUN
|
||||
- [ ] 使用官方 Playwright Chromium 容器；宿主无需安装浏览器 — 证据：NOT RUN
|
||||
- [ ] 若容器不可用，才执行 `npx playwright install --with-deps chromium` — 证据：NOT RUN
|
||||
- [ ] 禁止 `page.route`、mock/stub、直接写数据库或伪造 API 输出 — 证据：NOT RUN
|
||||
|
||||
推荐运行形态：
|
||||
|
||||
@@ -187,26 +185,23 @@ docker run --rm --network host --ipc host \
|
||||
- **Evidence**：完整对话、全部文档、版本、trace/video、来源 hash。
|
||||
- **Status**：NOT RUN。
|
||||
|
||||
## 4. 未来 controlled patch 负例（SWBOOT-10 stub — 无真实仓写）
|
||||
## 4. 未来 controlled patch 负例
|
||||
|
||||
> 真实 allowlist DB / patch / merge 执行器未实现。下列勾选仅表示 **stub fail-closed**；不得当作 SWBOOT-10 已交付。
|
||||
|
||||
- [x] repo / 路径未在 stub allowlist 不能读 — 证据：`TestRepoAllowlistStub` → `ERR_REPO_PATH_NOT_ALLOWLISTED`（2026-09-22）
|
||||
- [x] 非 allowlist 路径被拒绝 — 证据：同上
|
||||
- [ ] `.env`、secret、生产 dump 排除有效 — 证据：NOT RUN（需真实执行器）
|
||||
- [ ] 只在 feature worktree 写入 — 证据：NOT RUN（执行器未实现；本批证据写在任务 worktree）
|
||||
- [ ] repo 未绑定不能执行 — 证据：NOT RUN
|
||||
- [ ] 非 allowlist 路径被拒绝 — 证据：NOT RUN
|
||||
- [ ] `.env`、secret、生产 dump 排除有效 — 证据：NOT RUN
|
||||
- [ ] 只在 feature worktree 写入 — 证据：NOT RUN
|
||||
- [ ] 超出批准文件范围立即停止 — 证据：NOT RUN
|
||||
- [x] 测试失败不自动 merge（ApproveMerge stub） — 证据：`ApproveMerge` → `ERR_SWBOOT10_STUB_ONLY`
|
||||
- [x] 批准执行不等于批准 merge/push/deploy — 证据：同上 + `ExecuteControlledPatch` stub
|
||||
- [x] `controlled_patch` 创建/顾问路径被拒绝 — 证据：preview + `TestPiSoftwareBootstrapAdvisor_RejectsControlledPatch`
|
||||
- [ ] 保护分支直接 commit、force push、破坏性命令均被拒绝 — 证据：NOT RUN（需真实执行器策略）
|
||||
- [ ] 测试失败不自动 merge — 证据：NOT RUN
|
||||
- [ ] 批准执行不等于批准 merge/push/deploy — 证据：NOT RUN
|
||||
- [ ] 保护分支直接 commit、force push、破坏性命令均被拒绝 — 证据：NOT RUN
|
||||
|
||||
## 5. 完成定义
|
||||
|
||||
- [ ] L1–L5 工程门禁分别记录真实结果 — 2026-09-22：L1 子集 + L4 stub 已记；L2 PG / L3 / L5 未完成
|
||||
- [ ] UI-SW-00–14 全部由真实页面操作执行并留证 — L6 pending auth
|
||||
- [ ] 真实 PI 回复、小队进度和所有交付文档均可在 UI 看到 — L5/L6 pending auth
|
||||
- [ ] 医疗与软件两套黄金项目均无回归 — NOT RUN
|
||||
- [ ] 刷新、重登、重启、并发和权限负例通过 — NOT RUN
|
||||
- [x] test-report 逐项包含 Input/Expected/Actual/Verdict/Duration — 红线 SWBOOT 报告已遵循
|
||||
- [x] 任何 NOT RUN、fallback、失败和开放风险均如实保留 — 见 2026-09-22 报告
|
||||
- [ ] L1–L5 工程门禁分别记录真实结果
|
||||
- [ ] UI-SW-00–14 全部由真实页面操作执行并留证
|
||||
- [ ] 真实 PI 回复、小队进度和所有交付文档均可在 UI 看到
|
||||
- [ ] 医疗与软件两套黄金项目均无回归
|
||||
- [ ] 刷新、重登、重启、并发和权限负例通过
|
||||
- [ ] test-report 逐项包含 Input/Expected/Actual/Verdict/Duration
|
||||
- [ ] 任何 NOT RUN、fallback、失败和开放风险均如实保留
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: "D7 Track E ID-only 合规清单（红线证据）"
|
||||
status: done
|
||||
created: 2026-09-22
|
||||
updated: 2026-09-22
|
||||
related_task: "ops/short-term/2026-09-22-redline-evidence.md"
|
||||
related_adr: "adr/2026-09-17-d7-chat-data-retention.md"
|
||||
compliance: pending-compliance-signoff
|
||||
---
|
||||
|
||||
# D7 Track E ID-only 合规清单
|
||||
|
||||
> 本清单只做静态/契约复验。ADR 数字仍 `pending-compliance-signoff`。**禁止**物理删除、备份清除或把 stub/SKIP 写成 retention PASS。
|
||||
|
||||
## 范围
|
||||
|
||||
| 表面 | 允许 | 禁止 |
|
||||
|------|------|------|
|
||||
| 事件 envelope / DLQ / reconciliation | ID、digest、typed error code、allowlist 摘要（含 `summary_ref`） | 聊天正文、prompt、markdown、原始 payload dump |
|
||||
| 应用日志 | 脱敏 DSN、run/plan/doc ID | 消息 `content` |
|
||||
| 备份 | 整库 dump 作为运维能力存在 | 本轮执行 dump / 按 365 天清备份 |
|
||||
| 热库 chat_* | 只读盘点 / 内容编辑 UPDATE | `DELETE FROM chat_*`、retention `SET deleted_at` |
|
||||
|
||||
## 勾选（2026-09-22 / SHA `364ed7f1`）
|
||||
|
||||
### A. StaticContracts payload
|
||||
|
||||
- [x] 全部事件 `PayloadFields` 已枚举 — 证据：`assets/2026-09-22-redline-evidence/d7-track-e-payload-fields.txt`
|
||||
- [x] 无 `content` / `body` / `message` / `prompt` / `text` / `markdown` — `forbidden_hits=NONE`
|
||||
- [x] intent.plan.* 含 `summary_ref` 而非正文 — `TestIntentPlanContractsOmitSensitivePayload` PASS
|
||||
- [x] YAML ↔ `StaticContracts` 对等 — `TestRegistryParityWithYAML` PASS
|
||||
- [x] `SanitizeSummary` 丢弃非 allowlist 键 — `TestSanitizeSummaryDropsPayload` PASS
|
||||
|
||||
### B. 热库 / 删除路径
|
||||
|
||||
- [x] Go 检索无 `DELETE FROM chat_*` — `d7-no-physical-delete.txt`
|
||||
- [x] Go 检索无 chat retention `SET deleted_at` — 同上
|
||||
- [x] 存在的 `UPDATE chat_messages` 为内容编辑路径，非 soft-delete 作业 — 已注明
|
||||
- [x] 本轮未对共享/本地业务库执行 DELETE/UPDATE retention — 操作边界
|
||||
|
||||
### C. 备份 / 日志 / workspace
|
||||
|
||||
- [x] `scripts/backup-system-db.sh` 使用 `pg_dump -Fc` 整库（含 chat 明文）— 静态阅读
|
||||
- [x] 本轮**未**执行 dump、**未**清除备份目录
|
||||
- [x] Agent workspace 30 天清理作业仍未实现（待 ADR 签字）— 记为缺口非违规
|
||||
- [x] FAV `final_artifacts.retention_class` 与聊天口径解耦；consumer off
|
||||
|
||||
### D. ADR / 矩阵边界
|
||||
|
||||
- [x] ADR `compliance: pending-compliance-signoff` 未改
|
||||
- [x] FEATURE-MATRIX D7 保持 `deferred`（本批不升）
|
||||
- [x] 未发现已确认安全/合规基线违反 → **不写** gap-matrix blocker
|
||||
- [x] 报告：[../../test-reports/2026-09-22-redline-evidence-d7-test-report.md](../../test-reports/2026-09-22-redline-evidence-d7-test-report.md)
|
||||
|
||||
## 未做（明确排除）
|
||||
|
||||
- 共享 PG 实时 COUNT（无本轮 DB 只读授权会话；沿用 2026-09-17 W7 计数作历史参考）
|
||||
- 按 365/180/30 物理删除或备份二次清除
|
||||
- soft-delete 写路径实现
|
||||
|
||||
## 下一步（需另授权）
|
||||
|
||||
1. 合规签字或改数 → ADR `accepted`/`signed`
|
||||
2. soft-delete 写路径 → 观察窗 → 物理清理
|
||||
3. 备份清除：二次批准 + delete manifest（R22）
|
||||
@@ -1,6 +0,0 @@
|
||||
OK status -> allow
|
||||
OK push -> ask
|
||||
OK reset -> ask
|
||||
OK clean -> ask
|
||||
OK force-wt -> ask
|
||||
hooks OK
|
||||
@@ -1,20 +0,0 @@
|
||||
{
|
||||
"initialize": {
|
||||
"name": "agentctl",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"tools": [
|
||||
"status",
|
||||
"task_register",
|
||||
"task_close",
|
||||
"lease_run",
|
||||
"docs_snapshot",
|
||||
"docs_apply",
|
||||
"validate",
|
||||
"queue_enqueue",
|
||||
"quarantine_status"
|
||||
],
|
||||
"status_ok": true,
|
||||
"daemon_ok": true,
|
||||
"daemon_held": true
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
queue retry after parking untracked promotion receipts (DIRTY_TREE) at /tmp/ci-hold-receipts
|
||||
@@ -1,5 +0,0 @@
|
||||
OK agentctl-session-start lines 30
|
||||
OK agentctl-worktree-setup lines 48
|
||||
OK agentctl-lease-write lines 45
|
||||
OK agentctl-integrate-closeout lines 53
|
||||
skills OK
|
||||
@@ -1,2 +0,0 @@
|
||||
146:Ran 134 tests in 122.988s
|
||||
148:OK (skipped=3)
|
||||
@@ -1 +0,0 @@
|
||||
bootstrap: ok
|
||||
@@ -1,5 +0,0 @@
|
||||
{"interval": 1.0, "max_cycles": 3, "pid": 63316, "status": "daemon_started"}
|
||||
{"processed": 0, "results": [], "status": "ok"}
|
||||
{"processed": 0, "results": [], "status": "ok"}
|
||||
{"processed": 0, "results": [], "status": "ok"}
|
||||
{"cycles": 3, "pid": 63316, "reason": "max_cycles", "status": "daemon_stopped"}
|
||||
@@ -1 +0,0 @@
|
||||
{"epoch": "7fa35ad9-518f-4a0d-a446-49baf12c666c", "heartbeat": {"cycle": 99, "pid": 63557, "updated": 1790158027.962433}, "heartbeat_age_seconds": 0.2736787796020508, "lock_root": "/private/tmp/Agent-System/.locks", "manager_lock": {"held": true, "holder_pid": 63557, "path": "/private/tmp/Agent-System/.locks/os/manager.lock"}, "queue": {"claimed": 0, "pending": 0}, "status": "ok"}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user