cowork-flow 2.3.0 → 2.4.0

package/template/.cowork-flow/scripts/services/task_creation.py

@@ -6,7 +6,14 @@ from __future__ import annotations
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
+import re
 
+from infra.config import get_language
+from services.decision_anchor_schema import (
+    ACCEPTANCE,
+    GOAL,
+    heading_for,
+)
 from services.task_tree import TaskTreeError, TaskTreeService
 from services import task_graph
 from infra.paths import (
@@ -19,6 +26,20 @@ from services.task_gate_profiles import GATE_PROFILE_STRICT
 from services.task_repository import TaskRepository, TaskRepositoryError
 
 
+_GOAL_LINE_RE = re.compile(r"^\*\*(?:Goal|目标):\*\*\s*(.+?)\s*$")
+_GOAL_BOLD_COLON_RE = re.compile(r"^\*\*(?:Goal|目标)\*\*:\s*(.+?)\s*$")
+_GOAL_TABLE_RE = re.compile(
+    r"^\|\s*\*\*(?:Goal|目标)\*\*\s*\|\s*(.+?)\s*\|\s*$"
+)
+
+_ANCHOR_PLACEHOLDERS = {
+    ("zh-CN", GOAL): "<!-- 用一句话描述可观察的目标。 -->",
+    ("zh-CN", ACCEPTANCE): "<!-- 至少一条，例如：- [ ] AC-001: ... -->",
+    ("en-US", GOAL): "<!-- One sentence describing the observable outcome. -->",
+    ("en-US", ACCEPTANCE): "<!-- At least one, e.g. - [ ] AC-001: ... -->",
+}
+
+
 class TaskCreationError(RuntimeError):
     """Raised when task creation cannot be completed."""
 
@@ -66,6 +87,25 @@ class TaskCreationResult:
     linked_parent: str | None
     missing_parent: str | None
     generated_anchor: bool
+    generated_anchor_from_plan: bool
+
+
+def _extract_plan_goal(plan_text: str) -> str | None:
+    """First machine-readable goal line, then the legacy table row."""
+    for raw in plan_text.splitlines():
+        line = raw.strip()
+        for pattern in (_GOAL_LINE_RE, _GOAL_BOLD_COLON_RE, _GOAL_TABLE_RE):
+            match = pattern.match(line)
+            if match:
+                return match.group(1).strip()
+    return None
+
+
+def _anchor_placeholder(section: str, language: str) -> str:
+    return _ANCHOR_PLACEHOLDERS.get(
+        (language, section),
+        _ANCHOR_PLACEHOLDERS[("zh-CN", section)],
+    )
 
 
 def ensure_tasks_dir(repo_root: Path) -> Path:
@@ -122,7 +162,7 @@ class TaskCreationService:
             created_files.append(task_dir / FILE_TASK_JSON)
 
             linked_parent, missing_parent = self._link_parent(request, task_dir)
-            generated_anchor = self._generate_anchor(
+            generated_anchor, generated_anchor_from_plan = self._generate_anchor(
                 task_dir,
                 bound_plan_path,
             )
@@ -136,6 +176,7 @@ class TaskCreationService:
             linked_parent=linked_parent,
             missing_parent=missing_parent,
             generated_anchor=generated_anchor,
+            generated_anchor_from_plan=generated_anchor_from_plan,
         )
 
     def _task_data(
@@ -316,41 +357,42 @@ class TaskCreationService:
             "plan file must live under .cowork-flow/plans",
         )
 
-    @staticmethod
     def _generate_anchor(
+        self,
         task_dir: Path,
         plan_path: Path | None,
-    ) -> bool:
-        if plan_path is None:
-            return False
-        if not plan_path.is_file():
-            return False
+    ) -> tuple[bool, bool]:
+        """Create a language-specific anchor scaffold.
 
-        try:
-            plan_text = plan_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError) as error:
-            raise TaskCreationError(
-                "TASK-CREATE-PLAN-001",
-                plan_path,
-                "plan cannot be read as UTF-8",
-            ) from error
-
-        goal = next(
-            (
-                line.split(":", 1)[1].strip()
-                for line in plan_text.splitlines()
-                if line.startswith("**Goal:**")
-                or line.startswith("**目标:**")
-            ),
-            None,
-        )
+        A bound plan's goal line (or legacy table row) fills the goal section;
+        otherwise the scaffold carries a localized placeholder. An anchor that
+        already exists is never overwritten.
+        """
         anchor_file = task_dir / "decision-anchor.md"
-        if not goal or anchor_file.exists():
-            return False
+        if anchor_file.exists():
+            return False, False
+
+        goal: str | None = None
+        if plan_path is not None and plan_path.is_file():
+            try:
+                plan_text = plan_path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError) as error:
+                raise TaskCreationError(
+                    "TASK-CREATE-PLAN-001",
+                    plan_path,
+                    "plan cannot be read as UTF-8",
+                ) from error
+            goal = _extract_plan_goal(plan_text)
+
+        language = get_language(self.repo_root)
+        goal_heading = heading_for(GOAL, language)
+        acceptance_heading = heading_for(ACCEPTANCE, language)
+        goal_body = goal or _anchor_placeholder(GOAL, language)
+        acceptance_body = _anchor_placeholder(ACCEPTANCE, language)
         try:
             anchor_file.write_text(
-                f"## 目标\n\n{goal}\n\n## 验收标准\n"
-                "<!-- 至少一条，例如：- [ ] AC-001: ... -->\n",
+                f"## {goal_heading}\n\n{goal_body}\n\n"
+                f"## {acceptance_heading}\n\n{acceptance_body}\n",
                 encoding="utf-8",
             )
         except OSError as error:
@@ -363,7 +405,7 @@ class TaskCreationService:
                 anchor_file,
                 "decision anchor could not be written",
             ) from error
-        return True
+        return True, goal is not None
 
 
 def _validate_dev_type(dev_type: str | None, path: Path) -> None:

package/template/.cowork-flow/scripts/services/task_gate_profiles.py

@@ -4,7 +4,7 @@ A task created today carries `meta.gateProfile = "strict"`; a task without the
 marker keeps the historical gate (legacy), so nothing that already exists is
 retroactively re-gated.
 
-The strict gate exists because the old one only checked that the `## 验收标准`
+The strict gate exists because the old one only checked that the acceptance
 heading was present. An anchor with an empty acceptance section passed, the
 acceptance/evidence gates then found no AC rows to check, and the whole chain
 silently did nothing.
@@ -12,20 +12,17 @@ silently did nothing.
 
 from __future__ import annotations
 
-import re
-
-from services.fact_view import ACCEPTANCE_RE
+from services.decision_anchor_schema import (
+    ACCEPTANCE_RE,
+    LIST_ITEM_RE,
+    acceptance_section_lines,
+)
 
 GATE_PROFILE_STRICT = "strict"
 GATE_PROFILE_LEGACY = "legacy"
 
 LIGHT_TASK_TYPE = "tiny"
 
-ACCEPTANCE_HEADING = "验收标准"
-
-_HEADING_RE = re.compile(r"^##\s*(.+?)\s*$")
-_LIST_ITEM_RE = re.compile(r"^\s*[-*]\s")
-
 
 def resolve_gate_profile(task_data: dict) -> str:
     """The gate a task is held to; an unmarked task is legacy."""
@@ -72,20 +69,6 @@ def is_light_task(task_data: dict) -> bool:
     return declares_light_profile(task_data)
 
 
-def acceptance_section_lines(anchor_text: str) -> list[str]:
-    """Raw lines under `## 验收标准`, up to the next heading."""
-    lines: list[str] = []
-    inside = False
-    for raw in anchor_text.splitlines():
-        heading = _HEADING_RE.match(raw.strip())
-        if heading:
-            inside = heading.group(1) == ACCEPTANCE_HEADING
-            continue
-        if inside:
-            lines.append(raw)
-    return lines
-
-
 def acceptance_row_blockers(anchor_text: str) -> list[str]:
     """Why the acceptance section cannot start a strict task.
 
@@ -101,7 +84,7 @@ def acceptance_row_blockers(anchor_text: str) -> list[str]:
         if match:
             ids.append(match.group(2))
             continue
-        if _LIST_ITEM_RE.match(raw):
+        if LIST_ITEM_RE.match(raw):
             malformed.append(raw.strip()[:80])
     blockers: list[str] = []
     if not ids:

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -289,7 +289,8 @@ Verify: npm run test:fast; python3 -m pytest tests/ -q
 - **Gates**: static preview text, identical on all hosts; the delegated
   variant replaces the self-declaration sentence with "scope is inherited
   from the parent task (read-only reference)".
-- **Verify**: `## 验证命令` lines from decision-anchor (first 10, 120 chars
+- **Verify**: `## Verification Commands`/`## 验证命令` lines from
+  decision-anchor (first 10, 120 chars
   each) — the agent's own declared self-checks; omitted when none.
 - **Per-edit warning**: PostToolUse on an edit tool injects at most one
   line when the edited file is outside the task's declared scope —
@@ -326,9 +327,9 @@ Verify: npm run test:fast; python3 -m pytest tests/ -q
   budget/limits come from `.cowork-flow/spec/runtime/scope-rules.json`, the
   single source consumed at runtime; a missing or malformed file degrades to
   embedded defaults that are byte-identical with the shipped file (locked by
-  `tests/test_scope_rules.py`). The file is template-managed
-  (`syncPolicy.safeFiles`): `cwf project sync` refreshes it, so local edits to
-  it do not survive a sync.
+  `tests/test_scope_rules.py`). The file is framework-managed: `cwf project
+  sync` refreshes it as part of the synced `spec/runtime/` tree, so local edits
+  to it do not survive a sync.
 - Absent for `no_task` / `planning` / `completed` states. Block content is
   byte-identical across host lines for the whole fixture matrix
   (`test/fixtures/stage-contract-matrix.json` drives the equality test:

package/template/.cowork-flow/spec/contracts/decision-anchor.md

@@ -8,8 +8,9 @@ the alternatives", which compresses the number of task artifacts.
 
 ## Schema
 
-These section names are literal: the runtime parser matches them exactly, so a
-translated heading would simply stop being read.
+These section names are machine-readable. The runtime parser accepts both the
+Chinese and English heading sets, and new anchors use the language configured in
+`.cowork-flow/config.yaml` (`zh-CN` is the default).
 
 ```markdown
 # Decision Anchor
@@ -38,14 +39,17 @@ translated heading would simply stop being read.
 
 ## Section requirements
 
+Both heading columns below are accepted; the left column is the `zh-CN` output
+and the right column the `en-US` output.
+
 | Section | Required | Why |
 |------|------|------|
-| `## 目标` | required | no goal, no acceptance baseline |
-| `## 验收标准` | required | `task_start` is blocked without acceptance criteria |
-| `## 被拒方案` | optional | required for brainstorming tasks, so a rejected option is not reconsidered during execution |
-| `## 关键假设` | optional | filled in for complex tasks to surface implicit constraints; not read by the runtime parser |
-| `## 范围边界` | optional | prevents scope creep |
-| `## 验证命令` | optional | filled in for complex tasks, as the basis for automated verification; when the changed files are covered by `.cowork-flow/spec/backend/` or `frontend/` rules, it must also carry the spec/gate check for the task's `dev_type` (deciding command, or clause-by-clause `pass` / `not_applicable` with reason) |
+| `## 目标` / `## Goal` | required | no goal, no acceptance baseline |
+| `## 验收标准` / `## Acceptance Criteria` | required | `task_start` is blocked without acceptance criteria |
+| `## 被拒方案` / `## Rejected Options` | optional | required for brainstorming tasks, so a rejected option is not reconsidered during execution |
+| `## 关键假设` / `## Key Assumptions` | optional | filled in for complex tasks to surface implicit constraints; not read by the runtime parser |
+| `## 范围边界` / `## Scope Boundary` | optional | prevents scope creep |
+| `## 验证命令` / `## Verification Commands` | optional | filled in for complex tasks, as the basis for automated verification; when the changed files are covered by `.cowork-flow/spec/backend/` or `frontend/` rules, it must also carry the spec/gate check for the task's `dev_type` (deciding command, or clause-by-clause `pass` / `not_applicable` with reason) |
 
 ### Machine-readable line formats (for injection)
 
@@ -84,15 +88,17 @@ After merging (5 files): `decision-anchor.md` + `implement.jsonl` + `check.jsonl
 ## Lifecycle check coupling
 
 - The preflight for `task next <dir> --run` checks that `decision-anchor.md` is
-  non-empty and requires the `## 目标` and `## 验收标准` sections to be present.
+  non-empty and requires the `## 目标` / `## Goal` and `## 验收标准` /
+  `## Acceptance Criteria` sections to be present.
 - **Gate profile `meta.gateProfile`**: a newly created task is written as
   `"strict"`; an unmarked task is treated as `"legacy"` — existing tasks are not
   retro-fitted with the stricter gate, and the profile is queryable through the
   fact view. On top of the section check, a strict task additionally requires: at
-  least one parseable `- [ ] AC-xxx: ...` row in `## 验收标准`, no duplicate AC ids,
-  no non-AC list rows in that section, and a declared `dev_type` (otherwise
-  `task specs` dev-type dispatch silently comes back shorter).
-- A `## 验收标准` row's checkbox state (`- [ ]` / `- [x]`) and the evidence records
+  least one parseable `- [ ] AC-xxx: ...` row in `## 验收标准` /
+  `## Acceptance Criteria`, no duplicate AC ids, no non-AC list rows in that
+  section, and a declared `dev_type` (otherwise `task specs` dev-type dispatch
+  silently comes back shorter).
+- An acceptance row's checkbox state (`- [ ]` / `- [x]`) and the evidence records
   (the task directory's `evidence.jsonl`) are the fact source of the completion
   gate: completion is blocked when an unchecked AC exists (`LIFECYCLE-AC-001`), a
   declared AC has no evidence (`LIFECYCLE-AC-002`), a strict task cannot read any
@@ -149,4 +155,5 @@ source; if a task directory has only `prd.md` and no `decision-anchor.md`,
 `decision-anchor.md is missing or empty`.
 
 An existing legacy task needs a human to convert the `prd.md` content into
-`decision-anchor.md`, fill in `## 目标` and `## 验收标准`, and only then start.
+`decision-anchor.md`, fill in `## 目标` / `## Goal` and `## 验收标准` /
+`## Acceptance Criteria`, and only then start.

package/template/.cowork-flow/spec/contracts/plan-binding.md

@@ -48,7 +48,8 @@ into `in_progress`:
 - `task.json.meta.planFile` exists.
 - `planFile` is a repo-relative `.cowork-flow/plans/` path.
 - The plan file exists and is non-empty.
-- `decision-anchor.md` contains `## 目标` and `## 验收标准`.
+- `decision-anchor.md` contains `## Goal`/`## 目标` and
+  `## Acceptance Criteria`/`## 验收标准`.
 - `implement.jsonl` passes the existing context validation.
 
 A Tiny task may have no planFile, but must still satisfy the existing anchor and

package/template/.cowork-flow/spec/index.md

@@ -1,35 +1,35 @@
 # Cowork Flow Spec Index
 
-本目录只存放项目规范、运行时合同和运行时配置 schema。按职责分层：
+This directory holds project specs, runtime contracts, and runtime configuration schemas. Layers by responsibility:
 
-| 目录 | 作用 |
+| Directory | Purpose |
 | --- | --- |
-| `contracts/` | 人读的 workflow、宿主适配器和子代理协议合同。 |
-| `runtime/` | runtime 读取的机器配置，包括 contract registry 和 host asset manifest。 |
-| `schemas/` | runtime 配置和宿主合同的 JSON Schema。 |
-| `backend/` | 后端实现规范；由 review skill 按需读取并逐条审查。 |
-| `frontend/` | 前端实现规范；由 review skill 按需读取并逐条审查。 |
-| `guides/` | brainstorming/task-planning 阶段的编码前思考、跨层设计和复用判断指引。 |
-| `references/` | 按需参考材料（DoD、测试清单、安全清单、协作模式）；不自动加载。加载条件见 contract-registry.json 的 references 数组。 |
-
-流程内核只负责任务状态、文件范围、runtime context、归档一致性等可机器判断的事实。
-动作、阶段指导和专属运行时由各 Skill 的 `manifest.json` 声明；不维护集中式
-Skill registry。
-`backend/`、`frontend/` 中的自然语言规范不注册为 runtime gate；
-`task-review` skill 根据当前 diff 和任务范围读取并逐条审查。
-`guides/` 属于前置澄清与计划参考；选用后的结论应进入 `decision-anchor.md` 或任务计划。
+| `contracts/` | Human-readable contracts for the workflow, host adapters, and subagent protocol. |
+| `runtime/` | Machine configuration read by the runtime, including the contract registry and host asset manifest. |
+| `schemas/` | JSON Schemas for runtime configuration and host contracts. |
+| `backend/` | Backend implementation specs; the review skill reads them on demand and checks each clause. |
+| `frontend/` | Frontend implementation specs; the review skill reads them on demand and checks each clause. |
+| `guides/` | Pre-implementation thinking, cross-layer design, and reuse guidance for brainstorming/task-planning. |
+| `references/` | On-demand reference material (DoD, testing checklist, security checklist, orchestration patterns); never auto-loaded. Load conditions are in the `references` array of contract-registry.json. |
+
+Sync ownership: `contracts/`, `runtime/`, `schemas/`, and this file are framework-maintained and follow `cwf project sync`; `backend/`, `frontend/`, `guides/`, and `references/` are project-maintained, and `sync` never overwrites or deletes files there.
+
+The workflow kernel only owns machine-checkable facts: task state, file scope, runtime context, and archive consistency.
+Actions, stage guidance, and dedicated runtimes are declared by each Skill's `manifest.json`; there is no centralized Skill registry.
+Natural-language specs under `backend/` and `frontend/` are not registered as runtime gates; the `task-review` skill reads them according to the current diff and task scope and checks each clause.
+`guides/` is pre-implementation clarification and planning reference; selected conclusions belong in `decision-anchor.md` or the task plan.
 
 ## references/
 
-> 按需参考材料。**不在主会话中自动加载**——仅当 skill 入口或 agent 判断需要时读取。
+> On-demand reference material. **Never auto-loaded in the main session** — read only when a skill entry or agent judges it necessary.
 
-reference 文件之作用是：
-1. 为 skill 入口提供补充上下文（main skill 是入口，reference 是补充）
-2. 减少每次会话需加载的内容（spec/backend/ 等窄域规范只有实际需要时才加载）
-3. 在 planning、check 或 review 阶段提供快速对照清单
+Reference files:
+1. Provide supplemental context for skill entries (the main skill is the entry point; references supplement it).
+2. Reduce what each session must load (narrow-domain specs such as `spec/backend/` are read only when needed).
+3. Provide quick checklists during planning, check, or review.
 
-加载规则：
-- contract-registry 中 loadWhen 之一被匹配时读取
-- skill 正文中显式引用 reference ID 时读取
-- 用户在主会话请求特定检查时
-- **不**自动加载——这是与 contracts/ 系列的区别
+Loading rules:
+- Read when one of the `loadWhen` conditions in contract-registry matches.
+- Read when a skill body explicitly references a reference ID.
+- Read when the user requests a specific check in the main session.
+- **Never auto-loaded** — that is the difference from `contracts/`.

package/template/.cowork-flow/spec/references/definition-of-done.md

@@ -1,44 +1,44 @@
 # Definition of Done
 
-> 项目级完成门槛。每项变更在被视为"完成"前必须满足。与 per-task AC 互补但不替代。
+> Project-level completion gates. Every change must satisfy these before it is considered "done". They complement per-task ACs; they do not replace them.
 
-## 通用门槛（所有任务）
+## General gates (all tasks)
 
-| # | 检查项 | 验证 |
+| # | Check | Verification |
 |---|---|---|
-| G1 | 代码实现符合 decision-anchor acceptance criteria | AC 全部为 verified |
-| G2 | 行为变更有对应测试或明确验证命令；高风险任务覆盖失败、边界或回归路径 | `./.cowork-flow/run task next <dir> --validate` 与任务验证命令通过 |
-| G3 | check phase 完成，无 unresolved blocker | `task-review` 结论为 pass，completion lifecycle blocker 为 0 |
-| G4 | 无新引入 lint/type/build 警告 | lint / build 命令通过 |
-| G5 | Git status snapshot 仅含任务相关变更，包括 staged、unstaged、untracked | git status --porcelain=v1 -uall |
+| G1 | Implementation satisfies the decision-anchor acceptance criteria | All ACs are verified |
+| G2 | Behavior changes have corresponding tests or an explicit verification command; high-risk tasks cover failure, boundary, or regression paths | `./.cowork-flow/run task next <dir> --validate` and the task verification commands pass |
+| G3 | Check phase is complete with no unresolved blocker | `task-review` verdict is pass, and the completion lifecycle blocker count is 0 |
+| G4 | No newly introduced lint/type/build warnings | lint / build commands pass |
+| G5 | Git status snapshot contains only task-related changes, including staged, unstaged, and untracked | git status --porcelain=v1 -uall |
 
-## L0 专属（docs/format/comments only）
+## L0 only (docs/format/comments only)
 
-| # | 检查项 |
+| # | Check |
 |---|---|
-| L0-1 | 确认变更不涉及行为（docs/format/comments only）|
-| L0-2 | git diff --check 无空白错误 |
+| L0-1 | Change is confirmed non-behavioral (docs/format/comments only) |
+| L0-2 | `git diff --check` reports no whitespace errors |
 
-## L1 专属（单模块行为变更）
+## L1 only (single-module behavior change)
 
-| # | 检查项 |
+| # | Check |
 |---|---|
-| L1-1 | brainstorming 记录存在 |
-| L1-2 | 修改未扩散到无关模块（git diff 范围与 task.scope 一致）|
+| L1-1 | Brainstorming record exists |
+| L1-2 | Changes do not spread into unrelated modules (git diff range matches task.scope) |
 
-## L2 专属（跨层 / 架构 / 迁移）
+## L2 only (cross-layer / architecture / migration)
 
-| # | 检查项 |
+| # | Check |
 |---|---|
-| L2-1 | proposal.md / spec.md / design.md 齐全 |
-| L2-2 | 结构化决策审查已按 Skill 指导完成或明确记录不适用 |
-| L2-3 | readiness gate 全部通过（`task next <dir> --run` 无 blocker）|
-| L2-4 | spec-sync Skill 已确认规格同步或明确记录无需更新 |
+| L2-1 | proposal.md / spec.md / design.md are complete |
+| L2-2 | Structured decision review completed per Skill guidance, or explicitly recorded as not applicable |
+| L2-3 | All readiness gates pass (no blocker from `task next <dir> --run`) |
+| L2-4 | spec-sync Skill confirms spec synchronization, or explicitly records that no update is needed |
 
-## DoD 与 per-task AC 的区别
+## DoD vs per-task AC
 
 | DoD | AC |
 |---|---|
-| 项目级不变量——本次任务不例外 | decision-anchor 特有的完成条件 |
-| 来源：spec/references/definition-of-done | 来源：<task>/decision-anchor.md |
-| 两者都满足 = 任务真正完成 |
+| Project-level invariant — this task is no exception | Completion conditions specific to the decision-anchor |
+| Source: spec/references/definition-of-done | Source: <task>/decision-anchor.md |
+| Satisfying both = the task is truly complete |

package/template/.cowork-flow/spec/references/index.md

@@ -1,20 +1,20 @@
-# References — 按需加载参考材料
+# References — On-Demand Reference Material
 
-> **不自动加载。** 仅当 skill 入口显式引用 reference ID 时、或 agent 判断需要时读取。
+> **Never auto-loaded.** Read only when a skill entry explicitly references a reference ID, or when an agent judges it necessary.
 
-本目录存放窄适用范围的快速参考卡，作为 skill 入口的补充。相较 `spec/contracts/`（契约）和 `spec/backend|frontend/`（域规范），reference 文件之作用是：
-1. 在 check / finish 阶段提供快速对照清单（而非完整规范）
-2. 在分析潜在 prompt injection 时提供防御规则集
-3. 声明性总结 cowork-flow 已实现的协作模式
+This directory holds narrow-scope quick-reference cards that supplement skill entries. Compared with `spec/contracts/` (contracts) and `spec/backend|frontend/` (domain specs), reference files:
+1. Provide quick checklists during check / finish (not full specs).
+2. Provide defensive rule sets for analyzing potential prompt injection.
+3. Declare the collaboration patterns cowork-flow already implements.
 
-加载规则：
-- contract-registry.json 的 `references[*].loadWhen` 之一被匹配时
-- skill 正文中显式引用 reference ID 时
-- 用户在主会话请求特定检查时（如"security checklist"）
-- **不**自动加载——这是与 contracts/ 系列的区别
+Loading rules:
+- Read when one of `contract-registry.json`'s `references[*].loadWhen` conditions matches.
+- Read when a skill body explicitly references a reference ID.
+- Read when the user requests a specific check in the main session (for example, "security checklist").
+- **Never auto-loaded** — that is the difference from `contracts/`.
 
-当前参考：
-- [definition-of-done.md](definition-of-done.md) — DoD：项目级完成门槛（L0/L1/L2 三档）
-- [testing-checklist.md](testing-checklist.md) — 测试结构/深度/反模式快速参考
-- [security-checklist.md](security-checklist.md) — OWASP Top 10 映射 + 快速检查
-- [orchestration-patterns.md](orchestration-patterns.md) — 已实现的协作模式声明性目录
+Current references:
+- [definition-of-done.md](definition-of-done.md) — DoD: project-level completion gates (L0/L1/L2).
+- [testing-checklist.md](testing-checklist.md) — quick reference for test structure, depth, and anti-patterns.
+- [security-checklist.md](security-checklist.md) — OWASP Top 10 mapping plus a quick check.
+- [orchestration-patterns.md](orchestration-patterns.md) — declarative catalog of the collaboration patterns already implemented.