cowork-flow 0.0.41 → 0.0.42

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

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""Validate task-local quality review evidence."""
+
+from __future__ import annotations
+
+import json
+from json import JSONDecodeError
+from pathlib import Path
+from typing import Iterable
+
+from common.gates.validate_coding_standards import collect_machine_checks
+
+
+QUALITY_REVIEW_FILE = "quality-review.jsonl"
+REQUIRED_FIELDS = frozenset(
+    {"id", "source", "type", "status", "files", "evidence", "verification"}
+)
+ALLOWED_TYPES = frozenset({"checklist", "machine_warning", "dod"})
+ALLOWED_STATUSES = frozenset(
+    {"pass", "fail", "not_applicable", "acknowledged_warning"}
+)
+VAGUE_EVIDENCE = frozenset(
+    {
+        "checked",
+        "done",
+        "ok",
+        "pass",
+        "passed",
+        "n/a",
+        "na",
+        "已检查",
+        "已确认",
+        "通过",
+        "无问题",
+    }
+)
+
+
+def validate_quality_review(
+    repo_root: Path,
+    task_dir: Path | None,
+) -> list[dict]:
+    """Return blocking violations for missing or incomplete quality evidence."""
+    if task_dir is None:
+        return [
+            _violation(
+                "QUALITY-REVIEW-TASK-001",
+                "",
+                "Quality review gate requires a task directory",
+                "Run task complete with an explicit or active task directory.",
+            )
+        ]
+
+    evidence_path = Path(task_dir) / QUALITY_REVIEW_FILE
+    entries, violations = _read_entries(evidence_path)
+    if violations and not entries:
+        return violations
+
+    violations.extend(_validate_entries(entries, evidence_path))
+    if not violations:
+        violations.extend(_validate_machine_warning_coverage(repo_root, entries))
+    return violations
+
+
+def _read_entries(evidence_path: Path) -> tuple[list[dict], list[dict]]:
+    if not evidence_path.is_file():
+        return [], [
+            _violation(
+                "QUALITY-REVIEW-MISSING-001",
+                str(evidence_path),
+                "quality-review.jsonl is required before task complete",
+                "Record quality checklist, machine warning, and DoD evidence in quality-review.jsonl.",
+            )
+        ]
+
+    entries: list[dict] = []
+    violations: list[dict] = []
+    try:
+        lines = evidence_path.read_text(encoding="utf-8").splitlines()
+    except UnicodeDecodeError:
+        return [], [
+            _violation(
+                "QUALITY-REVIEW-UTF8-001",
+                str(evidence_path),
+                "quality-review.jsonl must be valid UTF-8",
+                "Rewrite quality-review.jsonl as UTF-8.",
+            )
+        ]
+    except OSError as error:
+        return [], [
+            _violation(
+                "QUALITY-REVIEW-READ-001",
+                str(evidence_path),
+                f"quality-review.jsonl could not be read: {error}",
+                "Restore a readable quality-review.jsonl file.",
+            )
+        ]
+
+    for index, raw_line in enumerate(lines, start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            value = json.loads(line)
+        except JSONDecodeError as error:
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-JSONL-001",
+                    evidence_path,
+                    index,
+                    f"quality-review.jsonl line is invalid JSON: {error.msg}",
+                    "Write one JSON object per line.",
+                )
+            )
+            continue
+        if not isinstance(value, dict):
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-JSONL-001",
+                    evidence_path,
+                    index,
+                    "quality-review.jsonl line must be a JSON object",
+                    "Write one JSON object per evidence record.",
+                )
+            )
+            continue
+        entries.append(value)
+
+    if not entries and not violations:
+        violations.append(
+            _violation(
+                "QUALITY-REVIEW-EMPTY-001",
+                str(evidence_path),
+                "quality-review.jsonl must contain at least one evidence record",
+                "Add checklist and DoD evidence records before completing the task.",
+            )
+        )
+    return entries, violations
+
+
+def _validate_entries(entries: list[dict], evidence_path: Path) -> list[dict]:
+    violations: list[dict] = []
+    has_dod = False
+    for index, entry in enumerate(entries, start=1):
+        missing = sorted(field for field in REQUIRED_FIELDS if field not in entry)
+        if missing:
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-SCHEMA-001",
+                    evidence_path,
+                    index,
+                    f"quality-review record is missing fields: {', '.join(missing)}",
+                    "Include id, source, type, status, files, evidence, and verification.",
+                )
+            )
+            continue
+
+        entry_type = str(entry.get("type") or "").strip()
+        status = str(entry.get("status") or "").strip()
+        if entry_type not in ALLOWED_TYPES:
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-TYPE-001",
+                    evidence_path,
+                    index,
+                    f"unsupported quality-review type: {entry_type}",
+                    "Use checklist, machine_warning, or dod.",
+                )
+            )
+        if status not in ALLOWED_STATUSES:
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-STATUS-002",
+                    evidence_path,
+                    index,
+                    f"unsupported quality-review status: {status}",
+                    "Use pass, fail, not_applicable, or acknowledged_warning.",
+                )
+            )
+        if status == "fail":
+            violations.append(
+                _line_violation(
+                    "QUALITY-REVIEW-STATUS-001",
+                    evidence_path,
+                    index,
+                    "quality-review record is still failing",
+                    "Resolve the finding or keep the task out of complete.",
+                )
+            )
+        if entry_type == "dod" and status in {"pass", "not_applicable"}:
+            has_dod = True
+
+        violations.extend(_validate_files(entry, evidence_path, index))
+        violations.extend(_validate_evidence(entry, evidence_path, index))
+        violations.extend(_validate_verification(entry, evidence_path, index))
+
+    if not has_dod:
+        violations.append(
+            _violation(
+                "QUALITY-REVIEW-DOD-001",
+                str(evidence_path),
+                "quality-review.jsonl must include Definition of Done evidence",
+                "Add a dod record for .cowork-flow/spec/references/definition-of-done.md.",
+            )
+        )
+    return violations
+
+
+def _validate_files(entry: dict, evidence_path: Path, index: int) -> list[dict]:
+    files = entry.get("files")
+    if _non_empty_string_list(files):
+        return []
+    return [
+        _line_violation(
+            "QUALITY-REVIEW-FILES-001",
+            evidence_path,
+            index,
+            "quality-review files must be a non-empty list of paths",
+            "List the reviewed changed files for this evidence record.",
+        )
+    ]
+
+
+def _validate_evidence(entry: dict, evidence_path: Path, index: int) -> list[dict]:
+    evidence = str(entry.get("evidence") or "").strip()
+    normalized = evidence.casefold()
+    if len(evidence) >= 24 and normalized not in VAGUE_EVIDENCE:
+        return []
+    return [
+        _line_violation(
+            "QUALITY-REVIEW-EVIDENCE-001",
+            evidence_path,
+            index,
+            "quality-review evidence is too vague",
+            "Describe the concrete file, rule, finding, or verification result.",
+        )
+    ]
+
+
+def _validate_verification(entry: dict, evidence_path: Path, index: int) -> list[dict]:
+    verification = entry.get("verification")
+    if _non_empty_string_list(verification):
+        return []
+    return [
+        _line_violation(
+            "QUALITY-REVIEW-VERIFICATION-001",
+            evidence_path,
+            index,
+            "quality-review verification must be a non-empty list of commands or reasons",
+            "Record executed commands, or an explicit reason a command was not applicable.",
+        )
+    ]
+
+
+def _validate_machine_warning_coverage(
+    repo_root: Path,
+    entries: list[dict],
+) -> list[dict]:
+    warnings = collect_machine_checks(Path(repo_root))
+    if not warnings:
+        return []
+
+    acknowledgements = _machine_warning_acknowledgements(entries)
+    violations: list[dict] = []
+    for warning in warnings:
+        rule_id = str(warning.get("rule_id") or "")
+        file_path = str(warning.get("file") or "")
+        if (rule_id, file_path) in acknowledgements:
+            continue
+        violations.append(
+            _violation(
+                "QUALITY-REVIEW-MACHINE-WARNING-001",
+                file_path,
+                f"machine warning {rule_id} is not addressed in quality-review.jsonl",
+                "Fix the warning or add a machine_warning record with status acknowledged_warning.",
+            )
+        )
+    return violations
+
+
+def _machine_warning_acknowledgements(entries: Iterable[dict]) -> set[tuple[str, str]]:
+    acknowledgements: set[tuple[str, str]] = set()
+    for entry in entries:
+        if entry.get("type") != "machine_warning":
+            continue
+        if entry.get("status") != "acknowledged_warning":
+            continue
+        source = str(entry.get("source") or entry.get("rule_id") or "").strip()
+        files = entry.get("files")
+        if not source or not isinstance(files, list):
+            continue
+        for file_path in files:
+            if isinstance(file_path, str) and file_path.strip():
+                acknowledgements.add((source, file_path.strip()))
+    return acknowledgements
+
+
+def _non_empty_string_list(value: object) -> bool:
+    return (
+        isinstance(value, list)
+        and bool(value)
+        and all(isinstance(item, str) and bool(item.strip()) for item in value)
+    )
+
+
+def _line_violation(
+    rule_id: str,
+    path: Path,
+    line: int,
+    message: str,
+    fix_hint: str,
+) -> dict:
+    violation = _violation(rule_id, str(path), message, fix_hint)
+    violation["line"] = line
+    return violation
+
+
+def _violation(
+    rule_id: str,
+    file_path: str,
+    message: str,
+    fix_hint: str,
+) -> dict:
+    return {
+        "rule_id": rule_id,
+        "type": "quality_review",
+        "severity": "block",
+        "passed": False,
+        "message": message,
+        "file": file_path,
+        "fix_hint": fix_hint,
+    }

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

@@ -14,7 +14,7 @@ Only machine-decidable checks run here as hard blocks:
 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
+emitted at severity=warn so they can be rendered for the LLM without being a
 wall the user must satisfy.
 """
 
@@ -163,7 +163,7 @@ def validate_coding_standards(
     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
+    workflow from this function. Optional machine warnings live in
     ``collect_machine_checks``.
     """
     return list(validate_changed_files(repo_root, collect_changed_files(repo_root)))
@@ -173,7 +173,7 @@ def collect_machine_checks(
     repo_root: Path,
     task_dir: Path | None = None,
 ) -> list[dict]:
-    """Emit regex-style advisory signals (severity=advisory).
+    """Emit regex-style machine warning signals (severity=warn).
 
     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
@@ -185,6 +185,14 @@ def collect_machine_checks(
     return violations
 
 
+def validate_machine_checks(
+    repo_root: Path,
+    task_dir: Path | None = None,
+) -> list[dict]:
+    """Gate binding for optional quality machine-check warnings."""
+    return collect_machine_checks(repo_root, task_dir)
+
+
 def _changed_machine_check_files(repo_root: Path) -> Sequence[object]:
     try:
         return collect_changed_files(repo_root)
@@ -289,7 +297,7 @@ def _adv(
     return {
         "rule_id": rule_id,
         "type": "machine_check",
-        "severity": "advisory",
+        "severity": "warn",
         "passed": False,
         "message": message,
         "file": file_path,
@@ -357,7 +365,7 @@ def main() -> None:
     parser.add_argument("--list", action="store_true", help="List parsed spec rules")
     parser.add_argument("--validate", action="store_true")
     parser.add_argument("--machine-checks", action="store_true",
-                        help="Also emit advisory machine-check warnings")
+                        help="Also emit machine-check warnings")
 
     args = parser.parse_args()
     repo_root = Path(args.repo_root).resolve()

package/template/.cowork-flow/spec/protocols/review.md

@@ -7,7 +7,8 @@
 1. Read the task decision anchor, plan, `check.jsonl`, registered context, and current diff.
 2. Review behavior, caller/callee contracts, persisted state, templates, specs, and scope.
 3. Review test intent, reject shallow tests, run focused tests that fail for meaningful behavior breaks, then broader validation for shared runtime changes.
-4. Reject shallow tests and unresolved blockers; fix only in-scope issues.
+4. Verify `quality-review.jsonl` covers quality checklist, machine warning, and Definition of Done evidence.
+5. Reject shallow tests and unresolved blockers; fix only in-scope issues.
 
 ## Output
 
@@ -18,10 +19,28 @@ Report the same core fields on every Host:
 - `findings`
 - `test_intent_review`
 - `verification`
+- `quality_review`
 - `resolution`
 
 Do not claim completion from intent or unexecuted commands.
 
+## Quality Evidence
+
+`quality-review.jsonl` is the task-local audit trail for quality review. Each
+record must include `id`, `source`, `type`, `status`, `files`, `evidence`, and
+`verification`.
+
+- `source`: a spec/checklist path or machine warning rule ID.
+- `type`: `checklist`, `machine_warning`, or `dod`.
+- `status`: `pass`, `fail`, `not_applicable`, or `acknowledged_warning`.
+- `evidence`: concrete file/rule reasoning, not generic "checked" claims.
+- `verification`: exact commands run or an explicit reason a command was not applicable.
+
+Backend/frontend natural-language markdown supplies review checklist context,
+not dynamic hard validators. Deterministic hard gates cover machine-decidable
+checks; machine warning output must be fixed or acknowledged in
+`quality-review.jsonl` before completion.
+
 ## Simplification Review
 
 When a change exceeds 50 lines or readability is a finding:

package/template/.opencode/agents/cowork-check.md

@@ -49,6 +49,12 @@ Rules:
 - Read the task directory from the bound runtime context.
 - Read `<task>/decision-anchor.md`, the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/`), `<task>/check.jsonl`, each JSONL `file` entry, and
   current `git diff`.
+- Read `<task>/quality-review.jsonl` if present and verify checklist, machine
+  warning, and Definition of Done evidence.
+- Treat backend/frontend natural-language specs as review checklist context,
+  not dynamic hard validators.
+- Fix machine warning findings or require acknowledged warning evidence in
+  `<task>/quality-review.jsonl`.
 - Check behavior, tests, spec sync, and scope.
 - Fix only in-scope issues.
 - Report changed files and exact verification commands.

package/template/.opencode/agents/cowork-implement.md

@@ -62,6 +62,11 @@ Then read the relevant spec directory:
 - Backend work: `.cowork-flow/spec/backend/index.md` (and all linked docs)
 - Frontend work: `.cowork-flow/spec/frontend/index.md` (and all linked docs)
 
+Backend/frontend natural-language specs are review checklist context, not
+dynamic hard validators. Deterministic gates handle machine-decidable checks;
+machine warning findings must be fixed or acknowledged in
+`quality-review.jsonl`.
+
 ---
 
 ## Coding Gates (Hard Constraints)
@@ -163,6 +168,7 @@ Before marking any change complete, you MUST verify:
 3. Error paths, permission paths, data boundaries are verified
 4. New conventions, contracts, or migration impacts are documented in spec or task records
 5. Failed verification is NOT worked around by shrinking assertions, deleting tests, or skipping critical paths
+6. `quality-review.jsonl` records checklist, machine warning, and Definition of Done evidence
 
 ---
 
@@ -197,8 +203,9 @@ You MUST NOT do any of the following:
 7. Apply coding gates — verify each gate before proceeding
 8. Implement changes within assigned scope
 9. Run verification commands (compile, lint, test, build, type-check)
-10. Report changed files and exact verification commands
-11. Do NOT run task start, task finish, task archive, unscoped resume, commit, or push
+10. Write `<task>/quality-review.jsonl` with checklist, machine warning, and Definition of Done evidence
+11. Report changed files and exact verification commands
+12. Do NOT run task start, task finish, task archive, unscoped resume, commit, or push
 
 ---
 
@@ -208,6 +215,11 @@ Rules:
 - Read `<task>/decision-anchor.md`, `<task>/implement.jsonl`,
   and each JSONL `file` entry.
 - Read the plan file linked from this task. Follow the plan steps in order.
+- Read quality source entries from context; natural-language specs are not dynamic hard validators.
+- Fix machine warning findings or record acknowledged warning evidence in
+  `<task>/quality-review.jsonl`.
+- Record Definition of Done and quality checklist evidence in
+  `<task>/quality-review.jsonl`.
 - Keep edits inside the assigned scope.
 - Report changed files and exact verification commands.
 - Do not use the `task` tool or invoke subagents.

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

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

package/template/.zcode/scaffold/.cowork-flow/spec/backend/database-guidelines.md

@@ -1,23 +0,0 @@
-# 后端数据库规范
-
-## 目标
-
-- 数据模型、迁移、查询方式保持一致。
-- 数据变更可审计、可回滚、可复现。
-- 事务边界与业务动作一致，不用扩大事务掩盖建模问题。
-
-## 默认规则
-
-- 表结构变更必须通过迁移文件、版本化脚本或仓库既有机制管理。
-- 查询优先使用仓库统一的数据访问方式；没有统一封装时，保持查询入口集中且可测试。
-- 写操作应明确幂等性、并发影响、失败补偿和重试边界。
-- 审计字段、逻辑删除、版本号、租户隔离等约定必须在同一数据域内一致。
-- 原始 SQL、批量更新、跨表聚合和长事务都需要说明索引、锁、性能和回滚影响。
-
-## 检查项
-
-- 新表或新集合是否补齐主键、唯一约束、索引和必要审计信息。
-- 复杂查询是否避免 N+1、隐式全表扫描和不受控分页。
-- 事务中是否包含外部调用、慢查询或不必要的长时间锁持有。
-- 数据迁移是否考虑历史数据、重复执行、失败恢复和线上回滚。
-- 错误处理是否区分数据不存在、数据冲突、约束失败和系统异常。

package/template/.zcode/scaffold/.cowork-flow/spec/backend/directory-structure.md

@@ -1,27 +0,0 @@
-# 后端目录结构规范
-
-## 目标
-
-- 模块职责清晰
-- 包结构稳定
-- 新人和 AI 能快速定位代码
-
-## 推荐做法
-
-- 按业务能力或边界拆模块，不按“工具类型”滥拆
-- Controller / API 只做参数接收、鉴权入口和响应编排
-- Service / UseCase 承接业务规则
-- Repository / DAO 承接持久化访问
-- Domain Model / Entity / Aggregate 保持边界清晰
-
-## 命名建议
-
-- 模块名体现业务边界，不体现实现细节
-- 包名与目录名统一小写
-- 同一层命名保持后缀一致，例如 `Controller`、`Service`、`Repository`
-
-## 不建议
-
-- 一个模块同时承担多个无关业务
-- 在 Controller 中堆业务逻辑
-- 在公共模块中混入业务特化逻辑

package/template/.zcode/scaffold/.cowork-flow/spec/backend/encoding-guidelines.md

@@ -1,27 +0,0 @@
-## 字符集编码要求
-
-### Windows 平台编码规范
-
-- **环境初始化**：在执行任何 `PowerShell` 脚本或命令前，优先执行
-  `$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8`，强制统一当前会话的输入输出编码。
-- **绝对强制使用 UTF-8**：包含但不限于修改源代码、读写配置、生成文本、日志记录等所有涉及字符流输入输出的操作，都必须显式指定
-  `UTF-8` 编码，严禁依赖系统默认编码（如 `GBK/CP936`）。
-- **PowerShell 读写规范**：
-  - 使用 `Get-Content` 和 `Set-Content` 时，必须显式添加 `-Encoding UTF8` 参数。
-  - 使用 `Out-File` 时，必须显式添加 `-Encoding UTF8` 参数。
-  - 尽量避免使用重定向符号 `>` 进行文本输出，推荐使用 `Set-Content -Encoding UTF8` 替代。
-- **无 BOM 格式约束**：除非目标系统（如旧版 Windows 记事本或特定遗留软件）明确要求，否则生成的 `UTF-8` 文本文件**必须不带
-  `BOM`
-  **。在 PowerShell 中，建议使用
-  `[System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding $false))` 来确保无 `BOM` 写入。
-- **Python 读写规范**：所有 `open()` 函数调用必须显式包含 `encoding="utf-8"` 参数（例如
-  `open("file.txt", "r", encoding="utf-8")`）。
-- **Node.js 读写规范**：在 `fs.readFile` 或 `fs.writeFile` 中，必须显式指定 `{ encoding: "utf8" }` 选项。
-- **Java 读写规范**：
-  - 严禁使用 `FileReader` 或 `FileWriter`（它们会隐式使用系统默认编码）。必须使用 `FileInputStream` / `FileOutputStream` 配合
-    `InputStreamReader` / `OutputStreamWriter`，并显式传入 `StandardCharsets.UTF_8`。
-  - 在使用 `Files.readAllLines` 或 `Files.write` 时，必须显式传入 `StandardCharsets.UTF_8` 参数。
-  - 涉及 `Scanner` 读取文件时，必须指定 `new Scanner(file, "UTF-8")`。
-- **Go 语言读写规范**：使用 `os.Create` 或 `os.OpenFile` 后，建议使用 `bufio` 或 `ioutil` 时确保写入的是 `UTF-8` 字节流；若涉及
-  Windows 特定 API，需注意转换。
-- **文件头检查**：在修改现有文件前，应检查文件当前的编码格式，避免将非 `UTF-8` 文件错误地以 `UTF-8` 解析导致乱码损坏。

package/template/.zcode/scaffold/.cowork-flow/spec/backend/error-handling.md

@@ -1,20 +0,0 @@
-# 后端异常处理规范
-
-## 目标
-
-- 调用方能稳定感知错误
-- 内部错误与外部错误边界清晰
-
-## 推荐做法
-
-- 统一定义错误码或错误类型
-- 参数校验错误、业务错误、系统错误分层处理
-- 对外返回稳定结构，对内保留足够上下文
-- 不把底层异常原样泄露给调用方
-
-## 典型检查项
-
-- 是否区分“可预期业务失败”和“系统异常”
-- 是否保留 traceId / requestId / correlationId
-- 是否有统一异常兜底
-- 是否记录了必要但不过量的日志

package/template/.zcode/scaffold/.cowork-flow/spec/backend/index.md

@@ -1,40 +0,0 @@
-# 后端开发规范
-
-## 默认基线
-
-- 后端代码以清晰的业务边界、稳定的接口契约和可验证的行为为核心。
-- 规范来源优先级：仓库已落地代码、配置、测试、迁移脚本、接口文档，然后才是本目录通用规则。
-- 新增实现应贴合现有架构，不静默引入第二套分层、命名、错误模型或数据访问方式。
-- 无法从现有代码判断约定时，采用本目录的保守默认规则，并在任务记录中说明假设。
-
----
-
-## 阅读顺序
-
-| 文档 | 用途 |
-|------|------|
-| [目录结构](./directory-structure.md) | 模块划分、包结构、命名方式 |
-| [数据库规范](./database-guidelines.md) | 实体、迁移、查询、事务 |
-| [异常处理](./error-handling.md) | 错误码、异常边界、统一返回 |
-| [日志规范](./logging-guidelines.md) | 结构化日志、敏感信息、链路标识 |
-| [质量规范](./quality-guidelines.md) | 测试、lint、门禁、禁止模式 |
-| [字符集编码规范](./encoding-guidelines.md) | 编码、换行、BOM 和跨平台读写约定 |
-
----
-
-## 使用原则
-
-- 优先遵循仓库现有模式，不新增与现有风格冲突的写法。
-- 先查已有公共模块、公共库或基础设施封装，再决定是否新增代码。
-- Controller / API 层保持薄入口，业务规则放在服务、用例或领域层。
-- 变更接口、数据结构、权限、异步链路或持久化模型时，同步更新调用方、测试和相关文档。
-- 涉及跨模块、异步链路、权限边界时，同时阅读 `guides/` 下的思考指引。
-
----
-
-## 默认完成标准
-
-- 关键路径有自动化验证或明确的手工验证记录。
-- 错误路径、空值、权限不足、重复提交等边界被显式考虑。
-- 运行时配置、数据迁移、兼容性和回滚影响已说明。
-- 不把“未运行测试”描述成“测试通过”。

package/template/.zcode/scaffold/.cowork-flow/spec/backend/logging-guidelines.md

@@ -1,20 +0,0 @@
-# 后端日志规范
-
-## 目标
-
-- 便于排查
-- 便于追踪链路
-- 不泄露敏感信息
-
-## 推荐做法
-
-- 使用结构化日志
-- 统一记录请求标识、用户标识、任务标识或链路标识
-- 错误日志记录上下文，不重复打印同一异常
-- 对账号、令牌、密钥、身份证号、手机号等敏感字段脱敏
-
-## 不建议
-
-- 直接输出完整请求体或完整响应体
-- 使用临时 `print` / `console` 式调试输出长期留在主干
-- 同一错误在多层重复打印