cowork-flow 0.0.31 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.codex/agents/cowork-check.toml

@@ -38,6 +38,13 @@ Rules:
 - MUST NOT commit, archive, or mutate cowork-flow task state.
 - Report findings, changed files, and exact verification commands.
 - Include test intent findings that map tests back to PRD acceptance or regression behavior.
+- BEFORE declaring PRD acceptance passed, run the spec-driven coding gate and
+  treat a nonzero exit as a hard blocker:
+  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standaries.py --validate --repo-root .
+  This naturally enforces every rule the user added to
+  .cowork-flow/spec/backend/*.md and spec/frontend/*.md — they are not just
+  documentation but active validators. On violation, either fix the code or
+  explicitly discard the rule from the spec; do not skip the gate.
 """
 
 [features]

package/template/.codex/agents/cowork-implement.toml

@@ -40,6 +40,12 @@ Rules:
 - Keep edits inside requested scope.
 - Do not treat shallow tests as TDD evidence; red-green-refactor proof must include redCommand, redExitCode, greenCommand, greenExitCode, and PRD acceptance ID mapping.
 - Report changed files and exact verification commands.
+- BEFORE editing any source file, run the spec-driven coding gate and treat a
+  nonzero exit as a hard blocker:
+  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standaries.py --validate --repo-root .
+  Parse every *.md under .cowork-flow/spec/backend and spec/frontend; rules
+  declared there activate validators dynamically. On violation, fix the code
+  (do not disable the rule) and re-run until exit code 0.
 """
 
 [features]

package/template/.codex/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".cowork-flow/run python .codex/hooks/inject-workflow-state.py",
+            "command": ".codex/hooks/inject-workflow-state.py",
             "timeout": 5
           }
         ]

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.31
+0.0.32

package/template/.cowork-flow/scripts/common/gates/validate_coding_standards.py

@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
-"""
-Coding standards helper.
+"""Spec-driven coding standards — gates honor user-edited spec files.
 
-Summarizes relevant standards and validates changed files for lifecycle gates.
+Files under ``.cowork-flow/spec/backend/``, ``spec/frontend/`` and
+``spec/guides/`` are parsed at runtime into review-checklist rules and matched
+against a small registry of registered validators. Anything a user adds to
+those files is activated at the next gate run — the gate re-reads the
+markdown every time.
 """
 
 from __future__ import annotations
@@ -11,170 +14,289 @@ import json
 import re
 import sys
 from pathlib import Path
+from typing import Callable, Iterable, Sequence
 
-from .coding_standards import validate_changed_files
+from common.gates.coding_standards import validate_changed_files
 from common.git.git_snapshot import collect_changed_files, collect_changed_paths
 
+# Source files our spec validators inspect.
+_EXTENSIONS = {
+    ".py", ".pyi",
+    ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
+    ".java", ".go", ".rs", ".rb", ".cs", ".kt", ".php",
+    ".yaml", ".yml", ".json", ".toml",
+}
 
-def get_coding_standards_summary(
-    repo_root: Path,
-    task_dir: Path,
-) -> str:
-    """
-    Get coding standards summary based on changed files.
+_BACKEND_SUFFIXES = re.compile(r"\.(py|java|go|rs|rb|cs|kt|php)$")
+_FRONTEND_SUFFIXES = re.compile(r"\.(tsx|jsx|vue|svelte|ts|js|mjs|cjs|css|scss)$")
 
-    Args:
-        repo_root: Repository root directory
-        task_dir: Task directory
 
-    Returns:
-        Summary string of relevant coding standards
-    """
-    modified_files = collect_changed_paths(repo_root)
-    if not modified_files:
-        return ""
+def _is_backend_file(rel_path: str) -> bool:
+    return bool(_BACKEND_SUFFIXES.search(rel_path))
 
-    # Classify files
-    backend_files = [f for f in modified_files if _is_backend_file(f)]
-    frontend_files = [f for f in modified_files if _is_frontend_file(f)]
 
-    summaries = []
+def _is_frontend_file(rel_path: str) -> bool:
+    return bool(_FRONTEND_SUFFIXES.search(rel_path))
 
-    # Get backend standards summary
-    if backend_files:
-        backend_summary = _get_standards_summary(repo_root, "backend")
-        if backend_summary:
-            summaries.append(f"=== Backend Coding Standards ===\n{backend_summary}")
 
-    # Get frontend standards summary
-    if frontend_files:
-        frontend_summary = _get_standards_summary(repo_root, "frontend")
-        if frontend_summary:
-            summaries.append(f"=== Frontend Coding Standards ===\n{frontend_summary}")
+# ---------------------------------------------------------------------------
+# Registered NL-backed validators
+# ---------------------------------------------------------------------------
 
-    return "\n\n".join(summaries)
+# Each entry: (compiled-pattern, category, validator-fn).
+# ``validator(content, rel_path)`` yields ``(lineno, message, fix_hint)``.
+_NL_VALIDATORS: list[tuple[re.Pattern, str, Callable[[str, str], Iterable[tuple[int, str, str]]]]] = []
 
 
-def validate_coding_standards(
-    repo_root: Path,
-    task_dir: Path | None = None,
-) -> list[dict]:
-    """Validate coding standards for changed files."""
-    return validate_changed_files(repo_root, collect_changed_files(repo_root))
-
-
-def _is_backend_file(file_path: str) -> bool:
-    """Check if file is a backend file"""
-    backend_patterns = [
-        r"\.py$",
-        r"\.java$",
-        r"\.go$",
-        r"\.rs$",
-        r"\.rb$",
-    ]
-    return any(re.search(p, file_path) for p in backend_patterns)
-
-
-def _is_frontend_file(file_path: str) -> bool:
-    """Check if file is a frontend file"""
-    frontend_patterns = [
-        r"\.tsx$",
-        r"\.jsx$",
-        r"\.vue$",
-        r"\.svelte$",
-    ]
-    return any(re.search(p, file_path) for p in frontend_patterns)
-
-
-def _get_standards_summary(repo_root: Path, category: str) -> str:
-    """
-    Get summary of coding standards from markdown files.
+def register_nl_validator(pattern: str) -> Callable[[Callable], Callable]:
+    def decorator(fn: Callable) -> Callable:
+        category = getattr(fn, "_nl_category", "backend")
+        _NL_VALIDATORS.append((re.compile(pattern, re.IGNORECASE), category, fn))
+        return fn
+    return decorator
 
-    Args:
-        repo_root: Repository root directory
-        category: 'backend' or 'frontend'
 
-    Returns:
-        Summary string
-    """
-    spec_dir = repo_root / ".cowork-flow" / "spec" / category
-    if not spec_dir.exists():
-        return ""
+def nl_category(category: str) -> Callable[[Callable], Callable]:
+    def decorator(fn: Callable) -> Callable:
+        fn._nl_category = category
+        return fn
+    return decorator
+
 
-    summaries = []
+@register_nl_validator(r"(硬编码|hardcode|hard.code|secret|password|api[_\s]?key|token)")
+@nl_category("backend")
+def _no_hardcoded_secrets(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    pattern = re.compile(
+        r"""(?ix)
+        (?:password|passwd|secret|api[_\s]?key|token|access[_\s]?key|aws_access_key_id|aws_secret_access_key)
+        \s*[:=]\s*["'][^"'}{)($]{3,}["']
+        """
+    )
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pattern.search(raw) and "process.env" not in raw and "os.environ" not in raw:
+            yield (lineno,
+                   "Possible hard-coded secret in source; spec forbids it.",
+                   "Read from configuration or environment variables.")
 
-    for md_file in sorted(spec_dir.glob("*.md")):
-        if md_file.name == "index.md":
+
+@register_nl_validator(r"(print\b|console\.(log|info|debug)|日志|logger|logging|结构化日志)")
+@nl_category("backend")
+def _no_debug_prints(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    if rel_path.endswith(".py"):
+        pat = re.compile(r"(?<!\w)print\s*\(")
+    elif rel_path.endswith((".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")):
+        pat = re.compile(r"\bconsole\.(log|info|debug)\s*\(")
+    else:
+        return
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pat.search(raw):
+            yield (lineno, "Debug print found; spec prefers structured logger.",
+                   "Use a structured logger instead.")
+
+
+@register_nl_validator(r"(吞|swallow|静默|except|空\s*except)")
+@nl_category("backend")
+def _no_silent_except(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    if not rel_path.endswith(".py"):
+        return
+    lines = content.splitlines()
+    for lineno, raw in enumerate(lines, start=1):
+        if re.match(r"^\s*except\b\s*.*:\s*(#.*)?$", raw):
+            nxt = lines[lineno].strip() if lineno < len(lines) else ""
+            if nxt in {"pass", "...", ""} or nxt.startswith(("pass ", "...")):
+                yield (lineno, "Empty exception handler silently swallows errors.",
+                       "Log or re-raise the exception, or narrow the except types.")
+
+
+@register_nl_validator(r"(硬编码|hardcode|明文|magic\s+number)")
+@nl_category("frontend")
+def _no_magic_values_frontend(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    pat = re.compile(r"""(?ix)(?:magic\s+number|hardcode|硬编码)""")
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pat.search(raw):
+            yield (lineno, "Hard-coded magic value in frontend source; spec forbids it.")
+
+
+# ---------------------------------------------------------------------------
+# Spec parser
+# ---------------------------------------------------------------------------
+
+_RULE_PATTERNS = [
+    re.compile(r"(?i)(?:^|\s)(?:must\s+not|should\s+not|do\s+not|never|avoid)\s+(.+)$"),
+    re.compile(r"(?:^|\s)(?:禁止|不得|不能|不应|避免|不要|不可|不许)\s*(.*)$"),
+    re.compile(r"(?i)(?:^|\s)(?:must|should|shall|always|应当|应该|需要)\s+(.+)$"),
+]
+
+
+def _rule_text(line: str) -> str | None:
+    line = line.strip().lstrip("-* ").strip()
+    if not line or line.startswith("#"):
+        return None
+    for pat in _RULE_PATTERNS:
+        m = pat.search(line)
+        if m:
+            text = m.group(m.lastindex).strip(" .。")
+            if len(text) > 3:
+                return text
+    return None
+
+
+def load_spec_rules(
+    repo_root,
+    categories: tuple[str, ...] = ("backend", "frontend"),
+) -> list[dict]:
+    """Return every natural-language rule declared under ``spec/<category>/``.
+
+    Re-reads markdown on every call, so user edits take effect without restart.
+    """
+    out: list[dict] = []
+    repo_root = Path(repo_root)
+    for category in categories:
+        spec_dir = repo_root / ".cowork-flow" / "spec" / category
+        if not spec_dir.is_dir():
             continue
+        for md in sorted(spec_dir.glob("*.md")):
+            if md.name == "index.md":
+                continue
+            text = md.read_text(encoding="utf-8")
+            for lineno, raw in enumerate(text.splitlines(), start=1):
+                rule = _rule_text(raw)
+                if rule is None:
+                    continue
+                out.append({
+                    "category": category,
+                    "source": f".cowork-flow/spec/{category}/{md.name}",
+                    "line": lineno,
+                    "text": rule,
+                    "validators": [
+                        pat.pattern for pat, cat, _ in _NL_VALIDATORS
+                        if cat in (category, "backend") and re.search(pat, rule)
+                    ],
+                })
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
 
-        content = md_file.read_text(encoding="utf-8")
-        rules = _extract_key_rules(content)
 
-        if rules:
-            summaries.append(f"File: {md_file.name}")
-            for rule in rules[:5]:  # Limit to top 5 rules per file
-                summaries.append(f"  - {rule}")
-            summaries.append("")
+def get_coding_standards_summary(
+    repo_root: Path,
+    task_dir: Path,
+) -> str:
+    """Render the active user-authored rules as a checklist (read-only)."""
+    changed = collect_changed_paths(repo_root)
+    if not changed:
+        return ""
 
-    return "\n".join(summaries)
+    backend = [p for p in changed if _is_backend_file(p)]
+    frontend = [p for p in changed if _is_frontend_file(p)]
+    if not backend and not frontend:
+        return ""
 
+    out: list[str] = []
+    if backend:
+        rules = load_spec_rules(repo_root, ("backend",))
+        if rules:
+            out.append("=== Backend spec rules — VALIDATED during check gate ===")
+            for r in rules:
+                out.append(f"- [{r['source']}:{r['line']}] {r['text']}")
+    if frontend:
+        rules = load_spec_rules(repo_root, ("frontend",))
+        if rules:
+            out.append("=== Frontend spec rules — VALIDATED during check gate ===")
+            for r in rules:
+                out.append(f"- [{r['source']}:{r['line']}] {r['text']}")
+    return "\n".join(out)
 
-def _extract_key_rules(content: str) -> list[str]:
-    """Extract key rules from markdown content"""
-    rules = []
 
-    # Extract forbidden patterns (Must not, Should not, Do not, etc.)
-    # Also match Chinese patterns
-    forbidden_patterns = [
-        r"[-*]\s*(Must not|Should not|Do not|Never|Avoid)\s+(.+)",
-        r"[-*]\s*(禁止|不得|不能|不应|避免|不要|不可)\s*(.+)",
-        r"[-*]\s*(.+不得|.+不能|.+不应|.+避免|.+不要)\s*(.+)",
-    ]
+def validate_coding_standards(
+    repo_root: Path,
+    task_dir: Path | None = None,
+) -> list[dict]:
+    """Run all coding-standard checks — hardcoded UTF-8 + spec-activated NL rules.
 
-    for line in content.split("\n"):
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
+    The NL rules only run when the user's spec files declare a matching rule
+    text, making spec files genuinely editable quality gates.
+    """
+    violations: list[dict] = []
 
-        for pattern in forbidden_patterns:
-            match = re.search(pattern, line, re.IGNORECASE)
-            if match:
-                # Extract the rule text
-                rule_text = line.lstrip("-* ").strip()
-                if len(rule_text) > 5:  # Skip very short rules
-                    rules.append(rule_text[:80])  # Limit length
-                    break  # Only match one pattern per line
+    # Phase 1: hardcoded UTF-8 / IO checks always run.
+    violations.extend(validate_changed_files(repo_root, collect_changed_files(repo_root)))
 
-    return rules[:10]  # Return top 10 rules
+    # Phase 2: spec-driven validators — activated by user-edited spec text.
+    spec_rules = load_spec_rules(repo_root)
+    if not spec_rules:
+        return violations
 
+    activated: set[str] = set()
+    for rule in spec_rules:
+        activated.update(rule.get("validators", []))
+    if not activated:
+        return violations
 
-def main():
-    """Main entry point"""
+    for changed_file in collect_changed_files(repo_root):
+        file_path = repo_root / changed_file.path
+        if not file_path.is_file():
+            continue
+        suffix = file_path.suffix.lower()
+        if suffix not in _EXTENSIONS:
+            continue
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for pat, _category, validator in _NL_VALIDATORS:
+            if pat.pattern not in activated:
+                continue
+            try:
+                results = validator(content, changed_file.path)
+            except Exception:  # noqa: BLE001 — defensively isolate parsing
+                continue
+            for lineno, msg, *rest in results:
+                fix_hint = rest[0] if rest else ""
+                violations.append({
+                    "rule_id": f"SPEC-{validator.__name__}",
+                    "type": "spec_coding_standard",
+                    "severity": "block",
+                    "passed": False,
+                    "message": msg,
+                    "file": changed_file.path,
+                    "line": lineno,
+                    "fix_hint": fix_hint,
+                })
+
+    return violations
+
+
+def main() -> None:
     import argparse
 
-    parser = argparse.ArgumentParser(description="Get coding standards summary")
-    parser.add_argument("--task-dir", required=True, help="Task directory path")
-    parser.add_argument("--repo-root", default=".", help="Repository root path")
-    parser.add_argument("--validate", action="store_true", help="Fail on coding standards violations")
+    parser = argparse.ArgumentParser(description="Spec-driven coding gate")
+    parser.add_argument("--task-dir", help="Task directory")
+    parser.add_argument("--repo-root", default=".", help="Repo root path")
+    parser.add_argument("--summarize", action="store_true")
+    parser.add_argument("--list", action="store_true", help="List parsed spec rules")
+    parser.add_argument("--validate", action="store_true", help="Run spec validators vs changed files")
 
     args = parser.parse_args()
-
     repo_root = Path(args.repo_root).resolve()
-    task_dir = Path(args.task_dir).resolve()
-
+    task_dir = Path(args.task_dir).resolve() if args.task_dir else repo_root
+
+    if args.list:
+        for r in load_spec_rules(repo_root):
+            print(json.dumps(r, ensure_ascii=False))
+        return
+    if args.summarize:
+        print(get_coding_standards_summary(repo_root, task_dir) or "No spec rules activated.")
+        return
     if args.validate:
-        violations = validate_coding_standards(repo_root, task_dir)
-        if violations:
-            for violation in violations:
-                print(json.dumps(violation, ensure_ascii=False))
-            sys.exit(1)
-        sys.exit(0)
-
-    summary = get_coding_standards_summary(repo_root, task_dir)
-    if summary:
-        print(summary)
-    else:
-        print("No relevant coding standards found for changed files.")
+        v = validate_coding_standards(repo_root, task_dir)
+        for x in v:
+            print(json.dumps(x, ensure_ascii=False))
+        sys.exit(1 if v else 0)
+    print(get_coding_standards_summary(repo_root, task_dir) or "No spec rules activated.")
 
 
 if __name__ == "__main__":

package/template/.cowork-flow/scripts/common/gates/validate_rules.py

@@ -306,7 +306,7 @@ def _validate_phase_gate(
         elif rule_id == "R-WF-004":
             return _check_plan_link(repo_root, change_dir, rule)
         elif rule_id == "R-WF-005":
-            return _check_task_link(change_dir, rule)
+            return _check_task_link(change_dir, task_dir, rule)
 
     # R-WF-006: Implementation without failing test
     if rule_id == "R-WF-006":
@@ -395,9 +395,11 @@ def _check_plan_link(
 
 def _check_task_link(
     change_dir: Path,
+    task_dir: Path,
     rule: dict,
 ) -> dict | None:
-    """Check if change has a task link."""
+    """Check if change references ``task_dir`` via ``task:``/``tasks:`` or any
+    list-item match in ``change.yaml``."""
     change_yaml = change_dir / "change.yaml"
     if not change_yaml.exists():
         return rule_violation(rule, change_yaml, detail="change.yaml is missing")
@@ -405,10 +407,16 @@ def _check_task_link(
     with open(change_yaml, encoding="utf-8") as f:
         content = f.read()
 
-    if not _metadata_has_link(content, ("task",)):
-        return rule_violation(rule, change_yaml, detail="task link is missing")
+    if _metadata_has_link(content, ("task", "tasks")):
+        return None
 
-    return None
+    task_name = task_dir.name
+    for raw in content.splitlines():
+        stripped = raw.strip().lstrip("-").strip().strip("#").strip().strip('"').strip("'").strip(",")
+        if stripped == task_name:
+            return None
+
+    return rule_violation(rule, change_yaml, detail="task link is missing")
 
 
 def log_violations(

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"

package/template/.zcode/hooks/runtime/run

@@ -47,6 +47,8 @@ select_python() {
 
 select_python
 
+SELECTED_PYTHON_ARG=${SELECTED_PYTHON_ARG:-}
+
 if [ -n "$SELECTED_PYTHON_ARG" ]; then
   export PYTHONPATH="$RUNTIME_SCRIPTS${PYTHONPATH:+:$PYTHONPATH}"
   exec "$SELECTED_PYTHON" "$SELECTED_PYTHON_ARG" "$RUNNER_SCRIPT" "$@"

package/template/.zcode/hooks/runtime/scripts/common/gates/validate_coding_standaries.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""Spec-driven coding standards (zcode hooks runtime).
+
+ZCode-flavored copy: relative imports (``.coding_standaries``), same CLI
+interface as the original (--task-dir required). Behaves identically to
+``template/.cowork-flow/scripts/common/gates/validate_coding_standaries.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Callable, Iterable, Sequence
+
+# Standalone-CLI import fallback: when loaded directly (not as a
+# package), the relative imports cannot resolve. Patch ``__package__``
+# and re-add this directory to ``sys.path`` so the absolute-style
+# fallbacks work identically to the relative ones.
+if __name__ == "__main__" and __package__ in (None, ""):
+    import sys as _sys
+    _dir = Path(__file__).resolve().parent
+    _parent = _dir.parent          # common/gates -> common
+    _grand = _parent.parent        # common
+    if str(_grand) not in _sys.path:
+        _sys.path.insert(0, str(_grand))
+    if str(_parent) not in _sys.path:
+        _sys.path.insert(0, str(_parent))
+    __package__ = "common.gates"
+
+from .coding_standards import validate_changed_files
+from common.git.git_snapshot import collect_changed_files, collect_changed_paths
+
+# Source files our spec validators inspect.
+_EXTENSIONS = {
+    ".py", ".pyi",
+    ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
+    ".java", ".go", ".rs", ".rb", ".cs", ".kt", ".php",
+    ".yaml", ".yml", ".json", ".toml",
+}
+
+_BACKEND_SUFFIXES = re.compile(r"\.(py|java|go|rs|rb|cs|kt|php)$")
+_FRONTEND_SUFFIXES = re.compile(r"\.(tsx|jsx|vue|svelte|ts|js|mjs|cjs|css|scss)$")
+
+
+def _is_backend_file(rel_path: str) -> bool:
+    return bool(_BACKEND_SUFFIXES.search(rel_path))
+
+
+def _is_frontend_file(rel_path: str) -> bool:
+    return bool(_FRONTEND_SUFFIXES.search(rel_path))
+
+
+# ---------------------------------------------------------------------------
+# Registered NL-backed validators
+# ---------------------------------------------------------------------------
+
+# Each entry: (compiled-pattern, category, validator-fn).
+# ``validator(content, rel_path)`` yields ``(lineno, message, fix_hint)``.
+_NL_VALIDATORS: list[tuple[re.Pattern, str, Callable[[str, str], Iterable[tuple[int, str, str]]]]] = []
+
+
+def register_nl_validator(pattern: str) -> Callable[[Callable], Callable]:
+    def decorator(fn: Callable) -> Callable:
+        category = getattr(fn, "_nl_category", "backend")
+        _NL_VALIDATORS.append((re.compile(pattern, re.IGNORECASE), category, fn))
+        return fn
+    return decorator
+
+
+def nl_category(category: str) -> Callable[[Callable], Callable]:
+    def decorator(fn: Callable) -> Callable:
+        fn._nl_category = category
+        return fn
+    return decorator
+
+
+@register_nl_validator(r"(硬编码|hardcode|hard.code|secret|password|api[_\s]?key|token)")
+@nl_category("backend")
+def _no_hardcoded_secrets(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    pattern = re.compile(
+        r"""(?ix)
+        (?:password|passwd|secret|api[_\s]?key|token|access[_\s]?key|aws_access_key_id|aws_secret_access_key)
+        \s*[:=]\s*["'][^"'}{)($]{3,}["']
+        """
+    )
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pattern.search(raw) and "process.env" not in raw and "os.environ" not in raw:
+            yield (lineno,
+                   "Possible hard-coded secret in source; spec forbids it.",
+                   "Read from configuration or environment variables.")
+
+
+@register_nl_validator(r"(print\b|console\.(log|info|debug)|日志|logger|logging|结构化日志)")
+@nl_category("backend")
+def _no_debug_prints(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    if rel_path.endswith(".py"):
+        pat = re.compile(r"(?<!\w)print\s*\(")
+    elif rel_path.endswith((".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")):
+        pat = re.compile(r"\bconsole\.(log|info|debug)\s*\(")
+    else:
+        return
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pat.search(raw):
+            yield (lineno, "Debug print found; spec prefers structured logger.",
+                   "Use a structured logger instead.")
+
+
+@register_nl_validator(r"(吞|swallow|静默|except|空\s*except)")
+@nl_category("backend")
+def _no_silent_except(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    if not rel_path.endswith(".py"):
+        return
+    lines = content.splitlines()
+    for lineno, raw in enumerate(lines, start=1):
+        if re.match(r"^\s*except\b\s*.*:\s*(#.*)?$", raw):
+            nxt = lines[lineno].strip() if lineno < len(lines) else ""
+            if nxt in {"pass", "...", ""} or nxt.startswith(("pass ", "...")):
+                yield (lineno, "Empty exception handler silently swallows errors.",
+                       "Log or re-raise the exception, or narrow the except types.")
+
+
+@register_nl_validator(r"(硬编码|hardcode|明文|magic\s+number)")
+@nl_category("frontend")
+def _no_magic_values_frontend(content: str, rel_path: str) -> Iterable[tuple[int, str, str]]:
+    pat = re.compile(r"""(?ix)(?:magic\s+number|hardcode|硬编码)""")
+    for lineno, raw in enumerate(content.splitlines(), start=1):
+        if pat.search(raw):
+            yield (lineno, "Hard-coded magic value in frontend source; spec forbids it.")
+
+
+# ---------------------------------------------------------------------------
+# Spec parser
+# ---------------------------------------------------------------------------
+
+_RULE_PATTERNS = [
+    re.compile(r"(?i)(?:^|\s)(?:must\s+not|should\s+not|do\s+not|never|avoid)\s+(.+)$"),
+    re.compile(r"(?:^|\s)(?:禁止|不得|不能|不应|避免|不要|不可|不许)\s*(.*)$"),
+    re.compile(r"(?i)(?:^|\s)(?:must|should|shall|always|应当|应该|需要)\s+(.+)$"),
+]
+
+
+def _rule_text(line: str) -> str | None:
+    line = line.strip().lstrip("-* ").strip()
+    if not line or line.startswith("#"):
+        return None
+    for pat in _RULE_PATTERNS:
+        m = pat.search(line)
+        if m:
+            text = m.group(m.lastindex).strip(" .。")
+            if len(text) > 3:
+                return text
+    return None
+
+
+def load_spec_rules(
+    repo_root,
+    categories: tuple[str, ...] = ("backend", "frontend"),
+) -> list[dict]:
+    """Return every natural-language rule declared under ``spec/<category>/``.
+
+    Re-reads markdown on every call, so user edits take effect without restart.
+    """
+    out: list[dict] = []
+    repo_root = Path(repo_root)
+    for category in categories:
+        spec_dir = repo_root / ".cowork-flow" / "spec" / category
+        if not spec_dir.is_dir():
+            continue
+        for md in sorted(spec_dir.glob("*.md")):
+            if md.name == "index.md":
+                continue
+            text = md.read_text(encoding="utf-8")
+            for lineno, raw in enumerate(text.splitlines(), start=1):
+                rule = _rule_text(raw)
+                if rule is None:
+                    continue
+                out.append({
+                    "category": category,
+                    "source": f".cowork-flow/spec/{category}/{md.name}",
+                    "line": lineno,
+                    "text": rule,
+                    "validators": [
+                        pat.pattern for pat, cat, _ in _NL_VALIDATORS
+                        if cat in (category, "backend") and re.search(pat, rule)
+                    ],
+                })
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_coding_standaries_summary(
+    repo_root: Path,
+    task_dir: Path,
+) -> str:
+    """Render the active user-authored rules as a checklist (read-only)."""
+    changed = collect_changed_paths(repo_root)
+    if not changed:
+        return ""
+
+    backend = [p for p in changed if _is_backend_file(p)]
+    frontend = [p for p in changed if _is_frontend_file(p)]
+    if not backend and not frontend:
+        return ""
+
+    out: list[str] = []
+    if backend:
+        rules = load_spec_rules(repo_root, ("backend",))
+        if rules:
+            out.append("=== Backend spec rules — VALIDATED during check gate ===")
+            for r in rules:
+                out.append(f"- [{r['source']}:{r['line']}] {r['text']}")
+    if frontend:
+        rules = load_spec_rules(repo_root, ("frontend",))
+        if rules:
+            out.append("=== Frontend spec rules — VALIDATED during check gate ===")
+            for r in rules:
+                out.append(f"- [{r['source']}:{r['line']}] {r['text']}")
+    return "\n".join(out)
+
+
+def validate_coding_standaries(
+    repo_root: Path,
+    task_dir: Path,
+) -> list[dict]:
+    """Run all coding-standard checks — hardcoded UTF-8 + spec-activated NL rules.
+
+    The NL rules only run when the user's spec files declare a matching rule
+    text, making spec files genuinely editable quality gates.
+    """
+    violations: list[dict] = []
+
+    # Phase 1: hardcoded UTF-8 / IO checks always run.
+    violations.extend(validate_changed_files(repo_root, collect_changed_files(repo_root)))
+
+    # Phase 2: spec-driven validators — activated by user-edited spec text.
+    spec_rules = load_spec_rules(repo_root)
+    if not spec_rules:
+        return violations
+
+    activated: set[str] = set()
+    for rule in spec_rules:
+        activated.update(rule.get("validators", []))
+    if not activated:
+        return violations
+
+    for changed_file in collect_changed_files(repo_root):
+        file_path = repo_root / changed_file.path
+        if not file_path.is_file():
+            continue
+        suffix = file_path.suffix.lower()
+        if suffix not in _EXTENSIONS:
+            continue
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for pat, _category, validator in _NL_VALIDATORS:
+            if pat.pattern not in activated:
+                continue
+            try:
+                results = validator(content, changed_file.path)
+            except Exception:  # noqa: BLE001 — defensively isolate parsing
+                continue
+            for lineno, msg, *rest in results:
+                fix_hint = rest[0] if rest else ""
+                violations.append({
+                    "rule_id": f"SPEC-{validator.__name__}",
+                    "type": "spec_coding_standard",
+                    "severity": "block",
+                    "passed": False,
+                    "message": msg,
+                    "file": changed_file.path,
+                    "line": lineno,
+                    "fix_hint": fix_hint,
+                })
+
+    return violations
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Spec-driven coding gate (zcode)")
+    parser.add_argument("--task-dir", required=True, help="Task directory path")
+    parser.add_argument("--repo-root", default=".", help="Repository root path")
+    parser.add_argument("--summarize", action="store_true")
+    parser.add_argument("--list", action="store_true", help="List parsed spec rules")
+    parser.add_argument("--validate", action="store_true")
+
+    args = parser.parse_args()
+    repo_root = Path(args.repo_root).resolve()
+    task_dir = Path(args.task_dir).resolve()
+
+    if args.list:
+        for r in load_spec_rules(repo_root):
+            print(json.dumps(r, ensure_ascii=False))
+        return
+    if args.summarize:
+        print(get_coding_standaries_summary(repo_root, task_dir) or "No spec rules activated.")
+        return
+    if args.validate:
+        v = validate_coding_standaries(repo_root, task_dir)
+        for x in v:
+            print(json.dumps(x, ensure_ascii=False))
+        sys.exit(1 if v else 0)
+    print(get_coding_standaries_summary(repo_root, task_dir) or "No spec rules activated.")
+
+
+if __name__ == "__main__":
+    main()

package/template/.zcode/hooks/runtime/scripts/common/gates/validate_rules.py

@@ -306,7 +306,7 @@ def _validate_phase_gate(
         elif rule_id == "R-WF-004":
             return _check_plan_link(repo_root, change_dir, rule)
         elif rule_id == "R-WF-005":
-            return _check_task_link(change_dir, rule)
+            return _check_task_link(change_dir, task_dir, rule)
 
     # R-WF-006: Implementation without failing test
     if rule_id == "R-WF-006":
@@ -395,9 +395,11 @@ def _check_plan_link(
 
 def _check_task_link(
     change_dir: Path,
+    task_dir: Path,
     rule: dict,
 ) -> dict | None:
-    """Check if change has a task link."""
+    """Check if change references ``task_dir`` via ``task:``/``tasks:`` or any
+    list-item match in ``change.yaml`` (supports the documented YAML list form)."""
     change_yaml = change_dir / "change.yaml"
     if not change_yaml.exists():
         return rule_violation(rule, change_yaml, detail="change.yaml is missing")
@@ -405,10 +407,16 @@ def _check_task_link(
     with open(change_yaml, encoding="utf-8") as f:
         content = f.read()
 
-    if not _metadata_has_link(content, ("task",)):
-        return rule_violation(rule, change_yaml, detail="task link is missing")
+    if _metadata_has_link(content, ("task", "tasks")):
+        return None
 
-    return None
+    task_name = task_dir.name
+    for raw in content.splitlines():
+        stripped = raw.strip().lstrip("-").strip().strip("#").strip().strip('"').strip("'").strip(",")
+        if stripped == task_name:
+            return None
+
+    return rule_violation(rule, change_yaml, detail="task link is missing")
 
 
 def log_violations(

package/template/AGENTS.md

@@ -16,24 +16,34 @@
 
 ## 0.1 编码前强制门禁
 
-**编辑文件、变更代码、派发子代理之前，MUST 调用 `before-dev` skill。**
+**编辑文件、变更代码、派发子代理之前，先确定当前工作流状态，再决定放行、阻断还是路由。**
 
-该 skill 读取 `<workflow-state>` 决定放行或阻断：
+按以下顺序判定当前状态：
 
-- `no_task` → **阻断**。拒绝写代码；引导 brainstorming → plan → task create → task start
-- `delegated_subtask` → 按子代理规则执行
-- `planning` → **阻断**。PRD 和 implement.jsonl 就绪前不允许实现
-- `in_progress` / `review` → 放行
-- `completed` → **阻断**。创建新任务
+1. **系统提示已包含 `<workflow-state>` 块（hook 注入）**: 直接按该块
+   `Status:` 行路由。
+2. **否则运行一次导航器**：
+   ```bash
+   ./.cowork-flow/run task next [task-dir-or-name]
+   ```
+   按返回的 `task.json.status` 路由，缺失活动任务时先创建再启动。
+
+状态路由：
+
+- `no_task` → **阻断**。拒绝写代码；引导 brainstorming → plan → task create → task start。
+- `delegated_subtask` → 按子代理规则执行，派发方核验绑定。
+- `planning` → **阻断**。PRD 和 implement.jsonl 就绪前不允许实现或派发 cowork-implement。
+- `in_progress` / `review` → 放行；按当前阶段推进。
+- `completed` → **阻断**。创建新任务或归档会话。
 
 豁免：
 
-- 只读问答
-- 纯查询命令（`git status`、`task next`、`task current`）
-- 用户明确说"跳过流程"
-- `before-dev` 本身
+- 只读问答。
+- 纯查询命令（`git status`、`task next`、`task current`）。
+- 用户明确说"跳过流程"。
+- `task next` / `task validate` 本身。
 
-不确定是否需要写代码时，先调用 `before-dev`。
+不确定是否需要写代码时，先运行 `task next`。
 
 ## 1. 先思考