cowork-flow 0.0.32 → 0.0.34

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

@@ -1,11 +1,21 @@
 #!/usr/bin/env python3
-"""Spec-driven coding standards — gates honor user-edited spec files.
+"""Coding-standard gates — context-injection model.
 
-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.
+Under Approach A, rules authored under ``.cowork-flow/spec/backend/*.md`` and
+``spec/frontend/*.md`` are machine-parsed into checklist items, then surfaced to
+the LLM via ``get_coding_standards_summary`` (already wired into the check/
+review gates). The LLM is trusted to verify its own code against these items.
+
+Only machine-decidable checks run here as hard blocks:
+
+* Phase 1 — UTF-8 / IO-encoding (``validate_changed_files``).
+* ``validate_complexity_signals`` — oversize Python functions (warn).
+
+A separate ``collect_machine_checks`` helper is exposed for callers that want
+additional regex-style warnings (hardcoded secrets, debug prints, silent
+excepts, trailing comments...) WITHOUT hard-blocking the workflow. These are
+emitted at severity=advisory so they can be rendered for the LLM without being a
+wall the user must satisfy.
 """
 
 from __future__ import annotations
@@ -14,7 +24,7 @@ import json
 import re
 import sys
 from pathlib import Path
-from typing import Callable, Iterable, Sequence
+from typing import Sequence
 
 from common.gates.coding_standards import validate_changed_files
 from common.git.git_snapshot import collect_changed_files, collect_changed_paths
@@ -39,84 +49,6 @@ 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
 # ---------------------------------------------------------------------------
@@ -148,6 +80,8 @@ def load_spec_rules(
     """Return every natural-language rule declared under ``spec/<category>/``.
 
     Re-reads markdown on every call, so user edits take effect without restart.
+    ``validators`` is preserved as an empty list (legacy field kept so external
+    tooling that inspects the rule dict does not break).
     """
     out: list[dict] = []
     repo_root = Path(repo_root)
@@ -168,10 +102,7 @@ def load_spec_rules(
                     "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)
-                    ],
+                    "validators": [],
                 })
     return out
 
@@ -180,12 +111,15 @@ def load_spec_rules(
 # Public API
 # ---------------------------------------------------------------------------
 
-
 def get_coding_standards_summary(
     repo_root: Path,
     task_dir: Path,
 ) -> str:
-    """Render the active user-authored rules as a checklist (read-only)."""
+    """Render the active user-authored rules as a review checklist (read-only).
+
+    Calls whose changed paths cover neither backend nor frontend files return
+    an empty string — there is nothing actionable for the LLM to review.
+    """
     changed = collect_changed_paths(repo_root)
     if not changed:
         return ""
@@ -199,13 +133,13 @@ def get_coding_standards_summary(
     if backend:
         rules = load_spec_rules(repo_root, ("backend",))
         if rules:
-            out.append("=== Backend spec rules — VALIDATED during check gate ===")
+            out.append("=== Backend spec rules — LLM review checklist ===")
             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 ===")
+            out.append("=== Frontend spec rules — LLM review checklist ===")
             for r in rules:
                 out.append(f"- [{r['source']}:{r['line']}] {r['text']}")
     return "\n".join(out)
@@ -215,28 +149,44 @@ 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.
+    """Run hard machine-checkable coding-standard gates.
 
-    The NL rules only run when the user's spec files declare a matching rule
-    text, making spec files genuinely editable quality gates.
+    Approach A keeps only the UTF-8 / IO-encoding check here. All natural
+    language rules authored in the spec tree are surfaced to the LLM via the
+    checklist in ``get_coding_standards_summary``; they do not block the
+    workflow from this function. Optional advisory warnings live in
+    ``collect_machine_checks``.
     """
-    violations: list[dict] = []
+    return list(validate_changed_files(repo_root, collect_changed_files(repo_root)))
 
-    # 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
+def collect_machine_checks(
+    repo_root: Path,
+    task_dir: Path | None = None,
+) -> list[dict]:
+    """Emit regex-style advisory signals (severity=advisory).
 
-    activated: set[str] = set()
-    for rule in spec_rules:
-        activated.update(rule.get("validators", []))
-    if not activated:
+    The LLM decides how to act on them; the workflow never blocks on a hit.
+    Kept separate from ``validate_coding_standards`` so callers can choose
+    whether to render them in a gate log, inject them into context, or ignore.
+    """
+    violations: list[dict] = []
+    try:
+        changed_files = collect_changed_files(repo_root)
+    except Exception:  # noqa: BLE001 — defensively isolate git errors
         return violations
 
-    for changed_file in collect_changed_files(repo_root):
+    secret_re = re.compile(
+        r"""(?ix)
+        (?:password|passwd|secret|api[_\s]?key|token|access[_\s]?key)
+        \s*[:=]\s*["'][^"'}{)($]{3,}["']
+        """
+    )
+    silent_except_re = re.compile(r"^\s*except\b\s*.*:\s*(#.*)?$")
+    bare_print_re = re.compile(r"(?<!\w)print\s*\(")
+    console_re = re.compile(r"\bconsole\.(log|info|debug)\s*\(")
+
+    for changed_file in changed_files:
         file_path = repo_root / changed_file.path
         if not file_path.is_file():
             continue
@@ -247,38 +197,125 @@ def validate_coding_standards(
             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,
-                })
-
+        lines = content.splitlines()
+        for lineno, raw in enumerate(lines, start=1):
+            # Low-signal heuristic: only flag if the line also has an
+            # assignment / call so variable-name mentions do not trip it.
+            if (secret_re.search(raw)
+                    and "process.env" not in raw
+                    and "os.environ" not in raw):
+                violations.append(_adv(
+                    "MACHINE-HARDCODED-SECRET-001",
+                    "Possible hard-coded secret in source",
+                    changed_file.path, lineno,
+                    "Read the value from configuration or environment variables.",
+                ))
+            if suffix == ".py" and bare_print_re.search(raw):
+                violations.append(_adv(
+                    "MACHINE-DEBUG-PRINT-001",
+                    "Debug print on changed line",
+                    changed_file.path, lineno,
+                    "Use a structured logger or remove the print.",
+                ))
+            if suffix in {".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"} and console_re.search(raw):
+                violations.append(_adv(
+                    "MACHINE-CONSOLE-LOG-001",
+                    "console.{log,info,debug} on changed line",
+                    changed_file.path, lineno,
+                    "Use the project logger or remove the call.",
+                ))
+            if (suffix == ".py"
+                    and silent_except_re.match(raw)
+                    and lineno < len(lines)
+                    and lines[lineno].strip() in {"pass", "...", ""}):
+                violations.append(_adv(
+                    "MACHINE-SILENT-EXCEPT-001",
+                    "Empty exception handler silently swallows errors",
+                    changed_file.path, lineno,
+                    "Log or re-raise the exception, or narrow the except types.",
+                ))
     return violations
 
 
+def _adv(
+    rule_id: str,
+    message: str,
+    file_path: str,
+    line: int,
+    fix_hint: str,
+) -> dict:
+    return {
+        "rule_id": rule_id,
+        "type": "machine_check",
+        "severity": "advisory",
+        "passed": False,
+        "message": message,
+        "file": file_path,
+        "line": line,
+        "fix_hint": fix_hint,
+    }
+
+
+def validate_complexity_signals(repo_root: Path, task_dir: Path | None) -> list[dict]:
+    """Detect over-complexity signals in modified files (warn-level)."""
+    import ast
+    import subprocess
+    warnings: list[dict] = []
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=ACMR", "HEAD~"],
+            cwd=str(repo_root), capture_output=True, text=True,
+            encoding="utf-8", timeout=10,
+        )
+        changed_files = [f for f in result.stdout.splitlines() if f]
+    except (subprocess.SubprocessError, OSError):
+        return warnings
+
+    for rel_path in changed_files:
+        if not rel_path.endswith(".py"):
+            continue
+        full_path = repo_root / rel_path
+        if not full_path.is_file():
+            continue
+        try:
+            source = full_path.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+        except (OSError, SyntaxError, UnicodeDecodeError):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                end = getattr(node, "end_lineno", None) or node.lineno
+                func_lines = end - node.lineno
+                if func_lines > 50:
+                    warnings.append({
+                        "rule_id": "COMPLEX-FUNC-001",
+                        "type": "coding_standard",
+                        "severity": "warn",
+                        "passed": False,
+                        "message": (
+                            f"{rel_path}:{node.name} function is "
+                            f"{func_lines} lines (< 50 recommended)"
+                        ),
+                        "file": str(rel_path),
+                        "fix_hint": (
+                            "Split into multiple named functions "
+                            "by responsibility."
+                        ),
+                    })
+    return warnings
+
+
 def main() -> None:
     import argparse
 
-    parser = argparse.ArgumentParser(description="Spec-driven coding gate")
+    parser = argparse.ArgumentParser(description="Coding-standard 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")
+    parser.add_argument("--validate", action="store_true")
+    parser.add_argument("--machine-checks", action="store_true",
+                        help="Also emit advisory machine-check warnings")
 
     args = parser.parse_args()
     repo_root = Path(args.repo_root).resolve()
@@ -293,9 +330,11 @@ def main() -> None:
         return
     if args.validate:
         v = validate_coding_standards(repo_root, task_dir)
+        if args.machine_checks:
+            v.extend(collect_machine_checks(repo_root, task_dir))
         for x in v:
             print(json.dumps(x, ensure_ascii=False))
-        sys.exit(1 if v else 0)
+        sys.exit(1 if any(x["severity"] == "block" for x in v) else 0)
     print(get_coding_standards_summary(repo_root, task_dir) or "No spec rules activated.")
 
 

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

@@ -186,29 +186,54 @@ def _check_unrequested_features(
     task_dir: Path,
     rule_index: dict[str, dict],
 ) -> list[dict]:
-    """R-AG-005: Check if unrequested features were introduced"""
+    """R-AG-005: Check if unrequested files were modified (diff files must be in implement.jsonl)."""
     violations = []
 
-    # Read PRD
-    prd_path = task_dir / "prd.md"
-    if not prd_path.exists():
+    # Collect allowed files from implement.jsonl
+    implement_jsonl = task_dir / "implement.jsonl"
+    if not implement_jsonl.exists():
         return violations
 
-    prd_content = prd_path.read_text(encoding="utf-8")
+    allowed_files: set[str] = set()
+    try:
+        for line in implement_jsonl.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            file_path = entry.get("file")
+            if isinstance(file_path, str) and file_path:
+                # Normalize paths (strip repo root prefix if present)
+                allowed_files.add(file_path)
+                # Also add stripped versions for matching
+                if file_path.startswith("./"):
+                    allowed_files.add(file_path[2:])
+                else:
+                    allowed_files.add(f"./{file_path}")
+    except (OSError, UnicodeDecodeError):
+        return violations
 
-    # Check for obvious extra features
-    # This is a simple heuristic check, actual implementation may need more complex NLP analysis
-    feature_indicators = [
-        r"Added.*feature",
-        r"New.*functionality",
-        r"Implemented.*module",
-    ]
+    if not allowed_files:
+        return violations
 
-    for pattern in feature_indicators:
-        if re.search(pattern, diff_output) and not re.search(pattern, prd_content):
+    # Get modified project files (exclude .cowork-flow/ metadata)
+    modified_files = _get_modified_files(repo_root)
+    for file_path in modified_files:
+        # Skip .cowork-flow metadata files and template files
+        if ".cowork-flow/" in file_path:
+            continue
+        normalized = file_path.replace("\\", "/")
+        # Check if file is in allowed list
+        if normalized not in allowed_files and f"./{normalized}" not in allowed_files:
             rule = rule_index.get("R-AG-005")
             violations.append(
-                rule_violation(rule, "", detail=f"detected pattern: {pattern}")
+                rule_violation(
+                    rule, file_path,
+                    detail=f"modified file not in implement.jsonl allowed list"
+                )
                 if rule
                 else _missing_rule(repo_root, "R-AG-005")
             )

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

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""JSONL file format validator for cowork-flow context files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def validate_format(file_path: Path | str) -> tuple[bool, list[str]]:
+    """Validate a JSONL file and return (is_valid, error_messages)."""
+    path = Path(file_path)
+    errors: list[str] = []
+
+    try:
+        content = path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError) as exc:
+        return False, [f"Cannot read file: {exc}"]
+
+    if not content:
+        return False, ["File is empty"]
+
+    for line_no, raw_line in enumerate(content.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            json.loads(line)
+        except json.JSONDecodeError as exc:
+            errors.append(f"Line {line_no}: Invalid JSON: {exc}")
+
+    return (not errors, errors)

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

@@ -266,14 +266,8 @@ def _validate_rule(
     scope: str,
 ) -> dict | None:
     """Validate a single rule. Returns violation dict if rule fails."""
-    rule_type = rule["type"]
-
-    if rule_type == "phase_gate":
+    if rule["type"] == "phase_gate":
         return _validate_phase_gate(rule, repo_root, task_dir, scope)
-    elif rule_type == "forbidden_action":
-        # Forbidden actions are validated at runtime, not at checkpoints
-        return None
-
     return None
 
 
@@ -308,11 +302,6 @@ def _validate_phase_gate(
         elif rule_id == "R-WF-005":
             return _check_task_link(change_dir, task_dir, rule)
 
-    # R-WF-006: Implementation without failing test
-    if rule_id == "R-WF-006":
-        # This is a warn-level rule, just log
-        return None
-
     # R-WF-007: Task completion without check
     if rule_id == "R-WF-007":
         if scope == "task_complete" and task_dir:

package/template/.cowork-flow/scripts/common/git/git_context.py

@@ -189,7 +189,7 @@ def _get_active_task_snapshot(repo_root: Path) -> ActiveTaskSnapshot:
     return ActiveTaskSnapshot(
         path=active_task,
         data=data,
-        has_prd=(active_task_dir / "prd.md").is_file(),
+        has_prd=(active_task_dir / "decision-anchor.md").is_file(),
     )
 
 
@@ -271,7 +271,7 @@ def _build_resume_checklist(
     commands.append(f"./{DIR_WORKFLOW}/run task list-context {active_task}")
 
     if snapshot.has_prd:
-        read_files.append(f"{active_task}/prd.md")
+        read_files.append(f"{active_task}/decision-anchor.md")
 
     read_files.extend(_task_plan_references(repo_root, snapshot))
     notes.append("Read current plan status only when continuing implementation.")
@@ -314,7 +314,7 @@ def _append_resume_checklist(
         return
 
     active_task = snapshot.path
-    prd_path = f"{active_task}/prd.md"
+    prd_path = f"{active_task}/decision-anchor.md"
     if prd_path in read_files:
         lines.append(f"- Read active task PRD: {prd_path}")
     else:
@@ -362,7 +362,7 @@ def _append_active_task(
 
     if include_prd_hint and snapshot.has_prd:
         lines.append("")
-        lines.append("[!] This task has prd.md - read it for task details")
+        lines.append("[!] This task has decision-anchor.md - read it for task details")
     lines.append("")