@chenmk/superflow 0.5.12 → 0.5.14

package/assets/scripts/superflow-sql-sync-hook.py

@@ -64,6 +64,7 @@ per finding for the developer to apply):
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 from pathlib import Path
@@ -75,6 +76,15 @@ if not (os.path.isdir('openspec') or os.path.isdir('.sdd') or os.path.isfile('.s
 
 
 DB_CODE_FILE = re.compile(r"\.(java|xml)$", re.I)
+MYBATIS_SAFE_EXPRESSIONS = frozenset({
+    "ew.sqlSegment", "ew.customSqlSegment", "ew.sqlSet", "ew.sqlComment",
+})
+MYBATIS_INTERPOLATION = re.compile(r"\$\{([^}]+)\}")
+SECRET_PATTERNS = (
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"\b(?:api[_-]?key|api[_-]?secret)\s*[:=]\s*['\"][^'\"]{8,}", re.I),
+    re.compile(r"\b[a-z_][a-z0-9_]*_(?:secret|token)\s*[:=]\s*['\"][^'\"]{16,}['\"]", re.I),
+)
 SQL_SUMMARY_FILE = re.compile(r"(^|/)sql/.*\.sql$", re.I)
 NO_SQL_ACK_FILE = re.compile(
     r"(^|/)(openspec/.*\.(md|yaml|yml)|ReleaseNotes\.md)$",
@@ -514,10 +524,113 @@ def warn(message, block=False):
     print(f"[SDD SQL 收口{prefix}] {message}", file=sys.stderr)
 
 
+def mapper_interpolations(file_path, content):
+    normalized = file_path.replace("\\", "/")
+    if not normalized.lower().endswith(".xml"):
+        return []
+    mapper_path = re.search(r"(?:^|/)(?:mapper|dao)/", normalized, re.I)
+    mapper_name = re.search(r"(?:Mapper|Dao)\.xml$", normalized)
+    mapper_body = re.search(r"<mapper\b|<!DOCTYPE\s+mapper", content, re.I)
+    if not (mapper_path or mapper_name or mapper_body):
+        return []
+    return [match.group(1).strip() for match in MYBATIS_INTERPOLATION.finditer(content)
+            if match.group(1).strip() not in MYBATIS_SAFE_EXPRESSIONS]
+
+
+def git_segment_args(segment):
+    tokens = shlex.split(segment)
+    git_at = next((i for i, token in enumerate(tokens)
+                   if token == "git" or token.endswith("/git")), -1)
+    if git_at < 0:
+        return None
+    return tokens[:git_at], tokens[git_at + 1:]
+
+
+def git_subcommand_index(args):
+    index = 0
+    while index < len(args) and args[index].startswith("-"):
+        index += 2 if args[index] in ("-c", "-C") else 1
+    return index
+
+
+def check_git_bypass(command):
+    for segment in re.split(r"\|\||&&|[;|\n]", command):
+        try:
+            parsed = git_segment_args(segment)
+        except ValueError:
+            if "git" in segment and ("--no-verify" in segment or "core.hooksPath" in segment):
+                return "Git 命令无法解析且包含 Hook 绕过参数"
+            continue
+        if parsed is None:
+            continue
+        prefix, args = parsed
+        config_override = any(
+            arg.startswith("core.hooksPath=") for arg in args
+        ) or any(token.startswith("GIT_CONFIG_") and "core.hooksPath" in token
+                 for token in prefix)
+        if config_override or "--no-verify" in args:
+            return "禁止使用 --no-verify 或 core.hooksPath 绕过 Git Hook"
+        index = git_subcommand_index(args)
+        if index < len(args) and args[index] == "commit":
+            flags = []
+            skip_value = False
+            for arg in args[index + 1:]:
+                if skip_value:
+                    skip_value = False
+                    continue
+                if arg in ("-m", "--message", "-F", "--file"):
+                    skip_value = True
+                    continue
+                flags.append(arg)
+            if any(re.fullmatch(r"-[a-zA-Z]*n[a-zA-Z]*", arg)
+                   for arg in flags):
+                return "禁止使用 git commit -n 绕过 Git Hook"
+    return None
+
+
+def is_git_commit(command):
+    for segment in re.split(r"\|\||&&|[;|\n]", command):
+        try:
+            parsed = git_segment_args(segment)
+        except ValueError:
+            continue
+        if parsed is None:
+            continue
+        _, args = parsed
+        index = git_subcommand_index(args)
+        if index < len(args) and args[index] == "commit":
+            return True
+    return False
+
+
+def check_staged_secrets(root):
+    result = run(["git", "diff", "--cached", "--unified=0", "--no-ext-diff"], cwd=root)
+    if result.returncode != 0:
+        return []
+    findings = []
+    current_path = ""
+    for line in result.stdout.splitlines():
+        if line.startswith("+++ b/"):
+            current_path = line[6:]
+        elif line.startswith("+") and not line.startswith("+++"):
+            if any(pattern.search(line[1:]) for pattern in SECRET_PATTERNS):
+                findings.append(current_path)
+    return sorted(set(findings))
+
+
 def handle_commit(command, root):
-    if not re.search(r"\bgit\s+commit\b", command):
+    bypass = check_git_bypass(command)
+    if bypass:
+        warn(bypass, block=True)
+        return 2
+    if not is_git_commit(command):
         return 0
 
+    secrets = check_staged_secrets(root)
+    if secrets:
+        warn("暂存差异包含疑似硬编码密钥：" + ", ".join(secrets), block=True)
+        return 2
+
     files = staged_files(root)
     if not files:
         return 0
@@ -595,6 +708,11 @@ def handle_commit(command, root):
 def handle_edit(file_path, edit_content):
     if not file_path:
         return 0
+    unsafe = mapper_interpolations(file_path, edit_content)
+    if unsafe:
+        warn("Mapper XML 使用危险 ${} 插值：" + ", ".join(unsafe[:3])
+             + "；请使用 #{}，动态标识符须在 Java 侧白名单校验。", block=True)
+        return 2
     if SQL_SUMMARY_FILE.search(file_path):
         sql_style_issues = lint_sql_style(file_path, edit_content)
         if sql_style_issues:
@@ -944,7 +1062,9 @@ def main():
 
     start = Path.cwd()
     if file_path:
-        start = Path(file_path).expanduser().resolve().parent
+        candidate = Path(file_path).expanduser().resolve().parent
+        if candidate.exists():
+            start = candidate
     root = repo_root(start)
     if root is None:
         return 0
@@ -952,7 +1072,25 @@ def main():
     if command:
         return handle_commit(command, root)
 
-    edit_content = tool_input.get("new_string") or tool_input.get("content") or ""
+    patch = tool_input.get("patch") or ""
+    if patch:
+        sections = re.split(r"(?=^\*\*\* (?:Add|Update) File: )", patch, flags=re.M)
+        for section in sections:
+            target = re.search(r"^\*\*\* (?:Add|Update) File: (.+)$", section, re.M)
+            if not target:
+                continue
+            added = "\n".join(line[1:] for line in section.splitlines()
+                              if line.startswith("+") and not line.startswith("+++"))
+            if handle_edit(target.group(1), added) == 2:
+                return 2
+        return 0
+
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        edit_content = "\n".join(str(edit.get("new_string") or "")
+                                 for edit in edits if isinstance(edit, dict))
+    else:
+        edit_content = tool_input.get("new_string") or tool_input.get("content") or ""
     return handle_edit(file_path, edit_content)
 
 

package/assets/scripts/superflow-test-report-lint.py

@@ -14,6 +14,7 @@ mechanically:
 from __future__ import annotations
 
 import argparse
+import json
 import re
 import subprocess
 import sys
@@ -99,6 +100,13 @@ EXTERNAL_EVIDENCE_RE = re.compile(
     re.I,
 )
 CASE_ID_RE = re.compile(r"\bT\d+(?:\.\d+)+\b")
+CASE_EVIDENCE_HEADER = re.compile(
+    r"^\|\s*(?:用例\s*ID|Case\s*ID)\s*\|\s*(?:入口\s*ID|Entry\s*ID)\s*\|"
+    r"\s*(?:验收级别|Acceptance\s*level)\s*\|\s*(?:结果|Result)\s*\|"
+    r"\s*(?:证据|Evidence)(?:路径|\s*path)?\s*\|$",
+    re.I,
+)
+CASE_RESULTS = {"PASS", "FAIL", "BLOCKED", "PARTIAL"}
 OLD_PHRASES = (
     "不会按周期边界拆分子切片",
     "1 秒空窗落入下一周期对账无实质影响",
@@ -253,6 +261,69 @@ def lint_against_tests_contract(report_path: Path, report_text: str, tests_path:
     return issues
 
 
+def lint_case_evidence(report_path: Path, report_text: str, review_path: Path) -> list[Issue]:
+    """Check the frozen R/E/C index against per-case execution receipts."""
+    issues: list[Issue] = []
+    try:
+        review = json.loads(review_path.read_text(encoding="utf-8"))
+        coverage = review["coverage"]
+        if coverage["schemaVersion"] != "superflow.review-coverage.v1":
+            raise ValueError("unsupported coverage schema")
+        cases = {case["id"]: case for case in coverage["cases"]}
+        decisions = coverage["decisions"]
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        return [Issue("FAIL", report_path, 0, f"入口评审凭证无法读取：{error}")]
+
+    required = {
+        case_id
+        for decision in decisions
+        if decision.get("disposition") != "EXCLUDED"
+        for case_id in decision.get("caseIds", [])
+    }
+    lines = report_text.splitlines()
+    header_at = next(
+        (i for i, line in enumerate(lines) if CASE_EVIDENCE_HEADER.fullmatch(line.strip())),
+        None,
+    )
+    if header_at is None:
+        return [Issue("FAIL", report_path, 0, "缺少逐用例执行证据表；不能用汇总通过数代替 R/E/C 回填")]
+
+    receipts: dict[str, tuple[str, str, str, str]] = {}
+    for index, line in enumerate(lines[header_at + 2 :], start=header_at + 3):
+        if not line.startswith("|"):
+            break
+        columns = [column.strip() for column in line.strip().strip("|").split("|")]
+        if len(columns) != 5:
+            issues.append(Issue("FAIL", report_path, index, "逐用例执行证据表必须有五列"))
+            continue
+        case_id, entry_id, level, result, evidence = columns
+        if case_id in receipts:
+            issues.append(Issue("FAIL", report_path, index, f"用例 {case_id} 重复回填"))
+        receipts[case_id] = (entry_id, level, result.upper(), evidence)
+
+    for case_id in sorted(required):
+        if case_id not in receipts:
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 缺少逐项执行结果"))
+            continue
+        entry_id, level, result, evidence = receipts[case_id]
+        case = cases.get(case_id)
+        if case is None or entry_id != case.get("entryId") or level != case.get("level"):
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的入口或验收级别与冻结合同不一致"))
+        if result not in CASE_RESULTS or not evidence or evidence.lower() in {"pending", "todo", "待补"}:
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 缺少有效结果或证据位置"))
+        elif result == "PASS" and not re.match(r"^https?://", evidence, re.I):
+            evidence_file = Path(evidence.split("#", 1)[0])
+            if not evidence_file.is_absolute():
+                evidence_file = report_path.parent / evidence_file
+            if not evidence_file.is_file():
+                issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的通过证据文件不存在：{evidence}"))
+        if result != "PASS" and re.search(r"验证结果\s*[:：]\s*PASS|Verification Result\s*[:：]\s*PASS", report_text, re.I):
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 为 {result}，报告不能声明整体验证 PASS"))
+    for case_id in receipts.keys() - required:
+        issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 未在冻结入口评审中要求执行"))
+    return issues
+
+
 def infer_tests_path(report: Path) -> Path | None:
     direct = report.parent / "tests.md"
     if direct.exists():
@@ -268,7 +339,8 @@ def infer_tests_path(report: Path) -> Path | None:
     return None
 
 
-def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None) -> list[Issue]:
+def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None,
+                review_path: Path | None = None) -> list[Issue]:
     issues: list[Issue] = []
     text = path.read_text(encoding="utf-8", errors="replace")
     lines = text.splitlines()
@@ -278,6 +350,8 @@ def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None) -
     blocked = bool(BLOCKED_RE.search(text))
     passed_or_partial = bool(PASS_WORDS.search(text) or re.search(r"Partially verified|部分验证", text, re.I))
     issues.extend(lint_against_tests_contract(path, text, tests_path or infer_tests_path(path)))
+    if review_path is not None:
+        issues.extend(lint_case_evidence(path, text, review_path))
 
     if db_backed and passed_or_partial and not blocked:
         if not TABLE_REVERSE_HEADER_RE.search(text):
@@ -395,6 +469,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="Lint SuperBridge Flow test-report evidence")
     parser.add_argument("reports", nargs="+")
     parser.add_argument("--tests", default="")
+    parser.add_argument("--review", default="")
     parser.add_argument("--repo-root", default="")
     parser.add_argument("--warn-only", action="store_true")
     args = parser.parse_args()
@@ -407,7 +482,10 @@ def main() -> int:
             continue
         repo = Path(args.repo_root).resolve() if args.repo_root else repo_root_for(path)
         tests_path = Path(args.tests).resolve() if args.tests else None
-        all_issues.extend(lint_report(path, repo, tests_path))
+        if tests_path is not None and not tests_path.exists():
+            all_issues.append(Issue("FAIL", path, 0, f"显式指定的 tests.md 不存在：{tests_path}"))
+        review_path = Path(args.review).resolve() if args.review else None
+        all_issues.extend(lint_report(path, repo, tests_path, review_path))
 
     printable = []
     for issue in all_issues:

package/assets/skill-registry.json

@@ -0,0 +1,229 @@
+{
+  "version": "1.0.0",
+  "contracts": [
+    {
+      "name": "openspec-apply-change",
+      "owner": "implement",
+      "triggers": [
+        "implement approved change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "tasks.md progress"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "openspec-archive-change",
+      "owner": "archive",
+      "triggers": [
+        "archive completed change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "archive result"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "openspec-explore",
+      "owner": "explore",
+      "triggers": [
+        "explore requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "alignment.md"
+      ],
+      "neighbors": [
+        "openspec-propose"
+      ]
+    },
+    {
+      "name": "openspec-propose",
+      "owner": "propose",
+      "triggers": [
+        "generate OpenSpec proposal"
+      ],
+      "excludes": [],
+      "outputs": [
+        "proposal.md specs design.md tasks.md"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-design",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-archive",
+      "owner": "archive",
+      "triggers": [
+        "archive SDD change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "archive report"
+      ],
+      "neighbors": [
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-clarify",
+      "owner": "clarify",
+      "triggers": [
+        "clarify requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "source-code-audit.md feature-gates.md brainstorm-summary.md"
+      ],
+      "neighbors": [
+        "openspec-propose",
+        "superflow-docs"
+      ]
+    },
+    {
+      "name": "superflow-design",
+      "owner": "design",
+      "triggers": [
+        "technical design"
+      ],
+      "excludes": [],
+      "outputs": [
+        "technical_design"
+      ],
+      "neighbors": [
+        "superflow-docs",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-docs",
+      "owner": "docs",
+      "triggers": [
+        "SDD contract documents"
+      ],
+      "excludes": [],
+      "outputs": [
+        "api.md tests.md sdd-quality-gate.md"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-design",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-hotfix",
+      "owner": "pipeline",
+      "triggers": [
+        "urgent small fix"
+      ],
+      "excludes": [],
+      "outputs": [
+        "bug-fix-plan.md"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-implement",
+      "owner": "implement",
+      "triggers": [
+        "generate implementation prompts"
+      ],
+      "excludes": [],
+      "outputs": [
+        "prompt/ test-report.md"
+      ],
+      "neighbors": [
+        "superflow-design",
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-pipeline",
+      "owner": "pipeline",
+      "triggers": [
+        "Superflow SDD pipeline"
+      ],
+      "excludes": [],
+      "outputs": [
+        "state.yaml handoff"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-requirement-review",
+      "owner": "review",
+      "triggers": [
+        "review requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "requirement-review.md"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-table-impact-analysis",
+      "owner": "docs",
+      "triggers": [
+        "table impact analysis"
+      ],
+      "excludes": [],
+      "outputs": [
+        "impact analysis"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-tweak",
+      "owner": "pipeline",
+      "triggers": [
+        "small wording tweak"
+      ],
+      "excludes": [],
+      "outputs": [
+        "tweak result"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-quick-dev",
+      "owner": "quick",
+      "triggers": [
+        "small code task",
+        "quick development"
+      ],
+      "excludes": [
+        "public API or database change",
+        "cross-module change"
+      ],
+      "outputs": [
+        ".sdd/tasks/<date>-<slug>/spec.md",
+        "quick evidence"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-verify",
+      "owner": "verify",
+      "triggers": [
+        "verify implementation"
+      ],
+      "excludes": [],
+      "outputs": [
+        "verification report"
+      ],
+      "neighbors": [
+        "superflow-implement",
+        "superflow-archive"
+      ]
+    }
+  ]
+}

package/assets/skills/openspec-propose/SKILL.md

@@ -22,6 +22,14 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+When this skill follows `superflow-clarify`, read the confirmed change-level
+Consensus Summary and its source evidence before creating artifacts. Put the
+goal, scope, material owner decisions, rejected alternatives, migration risks,
+and non-blocking reopen triggers in canonical `proposal.md`; cite the existing
+source audit rather than copying it. A pending owner decision that changes the
+solution blocks downstream spec/design/tasks. An explicit decision in the
+user's original request needs no second confirmation.
+
 ### OpenSpec canonical change 目录（阻塞级）
 
 - change 必须只有一个实体目录：`openspec/changes/<name>/`。
@@ -108,6 +116,12 @@ After completing all artifacts, summarize:
 - Follow the `instruction` field from `openspec instructions` for each artifact type
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
+- For a Superflow change, keep ordinary OpenSpec checkbox task syntax. For each
+  independently verifiable task, state its observable delivery and acceptance
+  signal; record real predecessor task IDs as `Blocked by` and link the relevant
+  requirement/scenario or traceability row. A free-text blocker does not change
+  Superflow's `[local_required]` / `[environment_required]` /
+  `[release_required]` machine classification. Do not invent dependencies.
 - Use `template` as the structure for your output file - fill in its sections
 - **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
   - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact

package/assets/skills/superflow-clarify/SKILL.md

@@ -13,7 +13,7 @@ any full SDD document or implementation prompt is generated.
 
 - Before freezing any new requirement or bug fix, perform platform-level impact
   discovery. Prefer understand-anything artifacts when present, such as
-  `.understand-anything/`, `understand-anything.md`, `understand anything.md`,
+  `.ua/`, `.understand-anything/`, `understand-anything.md`, `understand anything.md`,
   or the project-specific graph output, but treat them only as locator evidence.
   If artifacts are missing, stale, incomplete, or unavailable, degrade to `rg`,
   source reading, Mapper/XML, configuration, database table names, log
@@ -171,6 +171,28 @@ Use the detailed workflow in:
     indexed feature. Do not batch-confirm multiple features from memory or a
     compressed chat summary.
 
+### Change-level alignment before OpenSpec artifacts
+
+After all in-scope features are frozen, present one concise change-level
+`Consensus Summary` covering the goal, in/out scope, verified source facts,
+owner decisions with rejected alternatives, production and migration risks,
+and remaining non-blocking questions with owner and reopen trigger. Derive it
+from `source-code-audit.md`, `feature-gates.md`, and the confirmed decisions in
+`.sdd/handoff/brainstorm-summary.md`; the summary is a handoff view, not a
+second source of requirements. Record unresolved decisions as blockers and
+ask only the next owner decision. Do not ask the user to reconfirm facts or
+choices already explicit in the original request.
+
+When a material owner choice was made during clarification, show the current
+summary before generating OpenSpec artifacts. Reuse an explicit confirmation
+already given for that exact choice and summary; ask once only if the summary
+introduces a new choice or changes its consequence. The later `proposal.md`
+must carry the confirmed change-level
+decisions and cite their evidence. If a later finding changes a confirmed
+choice, return to that decision, update affected canonical documents, refresh
+the handoff hash and repeat document review and Coding Ready. Task checkbox
+progress alone does not change the agreed contract.
+
 ## Handoff
 
 When the feature is frozen, tell the user to continue with `$openspec-propose`

package/assets/skills/superflow-design/SKILL.md

@@ -64,7 +64,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 5. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-6. Complete `复杂度减法评审` before expanding source-level HOW. For every new
+6. For each new or changed module interface, add a `Design-It-Twice` card to
+   the technical design: two materially different interfaces, seam and adapter
+   ownership, the real test surface, reuse evidence, caller consequences, and
+   an explicit choice. Renaming the same interface does not count as two
+   options; revisit it. This card is advisory and does not add a state gate.
+7. Complete `复杂度减法评审` before expanding source-level HOW. For every new
    table, field, API, Service/component, abstraction, cache, async/MQ/event
    flow, scheduled job, or compatibility layer, prove existing reuse options,
    necessity, and why the simplest direct implementation is insufficient.

package/assets/skills/superflow-docs/SKILL.md

@@ -37,6 +37,12 @@ Do not invent new fields or requirements.
 
 For complex requirements, verify these before writing docs:
 
+- `proposal.md` carries the confirmed change-level Consensus Summary from
+  clarification: goal, scope, owner choices and rejected alternatives,
+  production/migration risks, and non-blocking reopen triggers. Check it
+  against original sources and `source-code-audit.md`; do not treat the
+  handoff summary as a second authority. If a material choice remains open,
+  return to `$superflow-clarify` before finalizing design or tasks.
 - `source-ingestion.md`, `feature-inventory.md`, and `feature-gates.md` prove
   that the original PRD/Lark/Feishu/screenshots were processed section by
   section, not summarized into tasks in one whole-document pass. Each feature
@@ -240,6 +246,12 @@ applicable:
 - `tasks.md` 每个 checkbox 必须带且只带一个机器分类：`[local_required]`、
   `[environment_required]` 或 `[release_required]`。能够在本地完成的编码、测试、启动和浏览器
   验证必须是 local_required；不得用自由文本 Blocker/owner 代替分类。
+- For each implementation task, review observable delivery, acceptance signal,
+  requirement/scenario coverage, and actual predecessors. Show the currently
+  executable tasks whose predecessors are complete. Reuse
+  `traceability-matrix.md` for detailed coverage; do not create another task
+  state file. `Blocked by` expresses execution order and never changes the
+  machine task classification above.
 - `tests.md`
 - `test-report.md` skeleton
 - `sdd-quality-gate.md`
@@ -368,6 +380,18 @@ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
   `用例ID | 需求/Scenario | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 |
   自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
   test-report证据位置`.
+- For cross-page management or database-backed display changes, reconcile the
+  frontend action/list inventory with real Controller, Service, exact Mapper
+  statement and table anchors before freezing tasks. Put the confirmed chain
+  and entry ID in `source-code-audit.md` and reuse it in `design.md`, `tasks.md`
+  and `tests.md`. A similarly named query is not evidence for the page route.
+  Include every visible mutation button, such as enable/disable, as an entry
+  even when the original task list omitted it.
+- For a returned persisted field, `tests.md` must freeze at least one non-null
+  fixture and an allowed historical-NULL fixture separately. Assert API and DB
+  values for the same record ID, then browser rendering where a page is in
+  scope. Key-presence, HTTP 200, empty-page and NULL-only assertions cannot
+  close the non-null data path. Name the exact query/command and evidence file.
 - 对 L3/L4 的输入校验、协议拒绝或异常分支，`tests.md` 还必须冻结真实注入载荷及其到达
   目标解析/校验分支的证据；仅断言同一个 HTTP 状态码不算覆盖。原始畸形 JSON、错误
   Content-Type、越权身份或非法字段必须按真实线协议发送，并同时断言无副作用。