@aipper/aiws-spec 0.0.10 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.agents/skills/aiws-change-validate/SKILL.md

@@ -19,5 +19,5 @@ fi
 ```
 
 说明：
-- `--strict` 会把 `WS:TODO`/缺少归因等视为错误（预期在工件未完善前会失败）
+- `--strict` 会把 `WS:TODO`/缺少归因视为错误，并启用计划质量门（章节完整、步骤粒度、验证命令与预期）
 - 紧急情况下可用 `--allow-truth-drift`（不推荐）

package/templates/workspace/.agents/skills/ws-dev/SKILL.md

@@ -10,6 +10,7 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 建议流程：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
+   - 若已有 `plan/` 工件：先执行 `$ws-plan-verify`；通过后再进入实现（防止计划过长/跑偏）。
 2) 建立变更归因（推荐）：
    - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
    - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变）

package/templates/workspace/.agents/skills/ws-plan/SKILL.md

@@ -9,21 +9,27 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 - 对齐真值文件（`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）
 - 为当前任务生成一份可追踪的执行计划文件：`plan/<timestamp>-<slug>.md`
 - 计划必须包含可复现验证命令（优先引用 `AI_WORKSPACE.md`）
+- 计划必须包含“主索引绑定”：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
 
 约束：
 - 不写入任何 secrets（token、账号、内网端点等不得进入 git）
 - 本 skill 只负责“想清楚怎么做 + 落盘计划”，不要直接大规模改动代码
 - 未运行不声称已运行；验证命令要写清“预期结果”
+- 若存在 `changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
 
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
 3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 生成计划文件：
+4) 识别主索引上下文（若存在）：
+   - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
+   - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
+5) 生成计划文件：
    - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
    - 若 `plan/` 不存在先创建
    - 必须实际写入到磁盘（不要只在对话里输出）；如因权限/策略无法写盘，必须明确说明原因并输出可复制的完整内容
-5) 计划内容至少包含（不要留空）：
+6) 计划内容至少包含（不要留空）：
+   - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
    - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
@@ -31,9 +37,11 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
    - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
-6) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
-7) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
+7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
+8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
+9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
+10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
 
 输出要求：
 - `Plan file:` <实际写入的路径>
-- `Next:` 推荐下一步（通常是 `$ws-dev` 或 `aiws change start <change-id> --hooks`；superproject + submodule 可用 `--worktree`）
+- `Next:` 推荐下一步（先 `$ws-plan-verify`，通过后再 `$ws-dev`；或 `aiws change start <change-id> --hooks`，superproject + submodule 可用 `--worktree`）

package/templates/workspace/.agents/skills/ws-plan-verify/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ws-plan-verify
+description: 计划质检（执行前检查计划是否过长/跑偏，并给出最小修正清单）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
+- 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
+- 失败时只给最小修正项，修完后再进入实现
+
+适用时机：
+- 已执行过 `$ws-plan`，且准备开始编码
+- 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 识别 change 上下文：
+   - 优先从当前分支推断 `change/<change-id>`
+   - 若无法推断：读取 `changes/*/proposal.md` 中的 `Change_ID`，并让用户确认本次要质检的 change
+3) 运行严格门禁（这是硬约束入口）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate <change-id> --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate <change-id> --strict
+else
+  npx @aipper/aiws change validate <change-id> --strict
+fi
+```
+4) 若失败：按报错逐条修正 `proposal.md` / `plan/...`，优先级如下：
+   - 先修绑定：`Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
+   - 再修计划质量：必需章节、步骤数量、步骤具体性、验证命令与预期
+5) 复跑 strict 校验，直到通过。
+6) 输出“可执行最小计划摘要”（3-8 步），再进入 `$ws-dev`。
+
+输出要求：
+- `Quality gate:` pass/fail
+- `Fix list:` 仅保留必须修改项（按阻断级别排序）
+- `Next:` 通过后建议 `$ws-dev`；未通过则继续修正并复跑 strict

package/templates/workspace/AGENTS.md

@@ -10,7 +10,7 @@
 - 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
 - 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
-- Codex skills（常用）：`$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
+- Codex skills（常用）：`$ws-preflight` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
 - Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
 - Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等

package/templates/workspace/changes/README.md

@@ -40,6 +40,12 @@ Active change（推荐，团队共享）：
 - 使用分支名声明当前变更：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
 - 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync|archive`
 
+计划质量门（推荐，执行前）：
+- 先生成计划：`$ws-plan`
+- 再执行计划质检：`$ws-plan-verify`
+- 最后进入实现：`$ws-dev`
+- 目标：确保计划具备主索引绑定、步骤不过长、验证命令可复现且有预期结果
+
 模板覆盖（可选）：
 - 在工作区创建 `changes/templates/` 可覆盖默认模板：
   - `changes/templates/proposal.md`

package/templates/workspace/changes/templates/proposal.md

@@ -12,12 +12,20 @@
 **非目标：**
 - <!-- WS:TODO 填写明确“不做什么”，防止 scope creep -->
 
-## 变更归因（强制二选一）
-
-- 需求交付：`Req_ID` = <!-- WS:TODO -->
-- 问题修复：`Problem_ID` = <!-- WS:TODO -->
-
-> 备注：若“问题阻塞需求”，两边都要在各自 CSV 的 `Notes` 字段互相引用对方 ID。
+## 主索引绑定（强制）
+
+- `Change_ID` = {{CHANGE_ID}}
+- 需求交付：`Req_ID` = <!-- WS:TODO （需求交付可填；例如 TOOLING-001B） -->
+- 问题修复：`Problem_ID` = <!-- WS:TODO （问题修复可填；例如 PROB-001） -->
+- `Contract_Row` = <!-- WS:TODO 绑定执行合同中的行 ID，可多项（逗号分隔）；例如 Req_ID=TOOLING-001B -->
+- `Plan_File` = <!-- WS:TODO 例如 plan/2026-02-08_15-30-00-xxx.md -->
+- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；例如 .agentdocs/tmp/review/codex-review.md -->
+
+> 规则：
+> - `Req_ID` 与 `Problem_ID` 至少填写一项。
+> - `Contract_Row` 必须引用 `requirements/requirements-issues.csv` 或 `issues/problem-issues.csv` 中的真实行。
+> - `Plan_File` 对应的计划文件必须存在，且其绑定字段与本文件一致。
+> - `Evidence_Path` 可先声明计划路径，交付前需完成证据落盘。
 
 ## 现状与问题
 

package/templates/workspace/changes/templates/tasks.md

@@ -9,6 +9,10 @@
 - [ ] 0.1 阅读并遵守 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`
 - [ ] 0.2 运行门禁校验：`aiws validate .`（或 `npx -y @aipper/aiws validate .`）
 - [ ] 0.3 若真值文件发生变化（例如你更新了 REQUIREMENTS.md），同步基线：`aiws change sync {{CHANGE_ID}}`
+- [ ] 0.4 在 `changes/{{CHANGE_ID}}/proposal.md` 填写主索引绑定：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
+- [ ] 0.5 生成 `plan/...` 后，确认计划文件中的绑定字段与 proposal 一致
+- [ ] 0.6 执行计划质检：在 AI 工具运行 `$ws-plan-verify`（或按同等清单手工检查“章节/步骤粒度/验证命令与预期”）
+- [ ] 0.7 严格校验：`aiws change validate {{CHANGE_ID}} --strict`
 
 ## 1. 需求/问题合同（如适用）
 

package/templates/workspace/manifest.json

@@ -136,6 +136,7 @@
       ".agents/skills/ws-finish/SKILL.md",
       ".agents/skills/ws-migrate/SKILL.md",
       ".agents/skills/ws-plan/SKILL.md",
+      ".agents/skills/ws-plan-verify/SKILL.md",
       ".agents/skills/ws-preflight/SKILL.md",
       ".agents/skills/ws-req-change/SKILL.md",
       ".agents/skills/ws-req-contract-sync/SKILL.md",

package/templates/workspace/tools/ws_change_check.py

@@ -77,7 +77,7 @@ def has_truth_files(root: Path) -> Tuple[bool, List[str]]:
 
 
 def extract_id(label: str, text: str) -> str:
-    m = re.search(rf"(?m)^.*{re.escape(label)}.*?[:=]\s*(.+)$", text)
+    m = re.search(rf"(?m)^.*{re.escape(label)}.*?[:=][ \t]*(.*)$", text)
     if not m:
         return ""
     v = m.group(1).strip()
@@ -86,6 +86,210 @@ def extract_id(label: str, text: str) -> str:
     return v
 
 
+def extract_first_id(labels: List[str], text: str) -> str:
+    for label in labels:
+        v = extract_id(label, text)
+        if v:
+            return v
+    return ""
+
+
+def split_declared_values(value: str) -> List[str]:
+    parts = re.split(r"[,;\n]+", value or "")
+    out: List[str] = []
+    for part in parts:
+        v = part.strip().strip("`").strip()
+        if v:
+            out.append(v)
+    return out
+
+
+def normalize_contract_ref(raw: str) -> Tuple[str, str]:
+    token = raw.strip().strip("`").strip()
+    token = re.sub(r"^(requirements/requirements-issues\.csv|issues/problem-issues\.csv)\s*[:#]\s*", "", token)
+    m = re.match(r"(?i)^(req[_-]?id|problem[_-]?id)\s*=\s*(.+)$", token)
+    if m:
+        key = m.group(1).lower()
+        value = m.group(2).strip()
+        if key.startswith("req"):
+            return ("Req_ID", value)
+        return ("Problem_ID", value)
+    if token.upper().startswith("PROB-"):
+        return ("Problem_ID", token)
+    return ("Any", token)
+
+
+def normalize_heading_token(raw: str) -> str:
+    token = (raw or "").strip().lower()
+    token = re.sub(r"<!--.*?-->", "", token)
+    token = re.sub(r"[^0-9a-z\u4e00-\u9fff]+", "", token)
+    return token
+
+
+def find_markdown_section(text: str, aliases: List[str]) -> str:
+    lines = text.splitlines()
+    alias_tokens: List[str] = []
+    for alias in aliases:
+        token = normalize_heading_token(alias)
+        if token:
+            alias_tokens.append(token)
+    if not alias_tokens:
+        return ""
+
+    start = -1
+    for i, line in enumerate(lines):
+        m = re.match(r"^\s{0,3}(#{2,6})\s+(.+?)\s*$", line)
+        if not m:
+            continue
+        heading_norm = normalize_heading_token(m.group(2))
+        if any(alias in heading_norm for alias in alias_tokens):
+            start = i + 1
+            break
+
+    if start < 0:
+        return ""
+
+    end = len(lines)
+    for j in range(start, len(lines)):
+        if re.match(r"^\s{0,3}#{1,6}\s+.+$", lines[j]):
+            end = j
+            break
+
+    return "\n".join(lines[start:end]).strip()
+
+
+def has_markdown_heading(text: str, aliases: List[str]) -> bool:
+    lines = text.splitlines()
+    alias_tokens: List[str] = []
+    for alias in aliases:
+        token = normalize_heading_token(alias)
+        if token:
+            alias_tokens.append(token)
+    if not alias_tokens:
+        return False
+    for line in lines:
+        m = re.match(r"^\s{0,3}(#{2,6})\s+(.+?)\s*$", line)
+        if not m:
+            continue
+        heading_norm = normalize_heading_token(m.group(2))
+        if any(alias in heading_norm for alias in alias_tokens):
+            return True
+    return False
+
+
+def extract_action_items(text: str) -> List[str]:
+    return [
+        m.group(1).strip()
+        for m in re.finditer(r"(?m)^\s*(?:- \[[ xX]\]|[-*+]|\d+[.)])\s+(.+)$", text or "")
+        if m.group(1).strip()
+    ]
+
+
+def has_runnable_command(text: str) -> bool:
+    if not text:
+        return False
+    if re.search(
+        r"(?i)\b(aiws|npx|node|npm|pnpm|yarn|python3?|pytest|bash|git|cargo|go|make|uv|\.\/gradlew)\b",
+        text,
+    ):
+        return True
+    if re.search(
+        r"(?mi)^\s*(?:aiws|npx|node|npm|pnpm|yarn|python3?|pytest|bash|git|cargo|go|make|uv|\.\/gradlew)\b",
+        text,
+    ):
+        return True
+    for inline in re.findall(r"`([^`]+)`", text):
+        if re.search(
+            r"(?i)\b(aiws|npx|node|npm|pnpm|yarn|python3?|pytest|bash|git|cargo|go|make|uv|\.\/gradlew)\b",
+            inline,
+        ):
+            return True
+    return False
+
+
+def is_concrete_plan_item(item: str) -> bool:
+    if re.search(r"`[^`]+`", item):
+        return True
+    if re.search(r"(?i)\b(aiws|npx|node|npm|pnpm|yarn|python3?|pytest|bash|git|cargo|go|make|uv|\.\/gradlew)\b", item):
+        return True
+    if re.search(r"\b(?:[A-Za-z0-9._-]+/)+[A-Za-z0-9._/-]+\b", item):
+        return True
+    return False
+
+
+def validate_plan_quality(plan_text: str, plan_rel: str, strict: bool) -> Tuple[List[str], List[str]]:
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    required_sections: List[Tuple[str, List[str]]] = [
+        ("Bindings", ["bindings", "主索引绑定", "绑定"]),
+        ("Goal", ["goal", "目标"]),
+        ("Non-goals", ["nongoals", "非目标"]),
+        ("Scope", ["scope", "范围", "改动范围"]),
+        ("Plan", ["plan", "执行步骤", "实施计划", "步骤"]),
+        ("Verify", ["verify", "verification", "验证"]),
+        ("Risks & Rollback", ["risksrollback", "riskrollback", "风险与回滚", "回滚"]),
+        ("Evidence", ["evidence", "证据"]),
+    ]
+
+    section_content: Dict[str, str] = {}
+    missing_sections: List[str] = []
+    empty_sections: List[str] = []
+    for section_name, aliases in required_sections:
+        exists = has_markdown_heading(plan_text, aliases)
+        body = find_markdown_section(plan_text, aliases)
+        section_content[section_name] = body
+        if not exists:
+            missing_sections.append(section_name)
+        elif not body.strip():
+            empty_sections.append(section_name)
+
+    if missing_sections:
+        (errors if strict else warnings).append(
+            f"{plan_rel} missing required sections: {', '.join(missing_sections)}"
+        )
+    if empty_sections:
+        (errors if strict else warnings).append(
+            f"{plan_rel} has empty sections: {', '.join(empty_sections)}"
+        )
+
+    scope_items = extract_action_items(section_content.get("Scope", ""))
+    if scope_items and len(scope_items) > 12:
+        (errors if strict else warnings).append(
+            f"{plan_rel} scope is too broad ({len(scope_items)} items > 12); split into smaller phases"
+        )
+
+    plan_items = extract_action_items(section_content.get("Plan", ""))
+    if section_content.get("Plan", "").strip() and not plan_items:
+        (errors if strict else warnings).append(
+            f"{plan_rel} Plan section has no actionable items (`- [ ]` / bullet / numbered list)"
+        )
+    if plan_items:
+        if len(plan_items) > 8:
+            (errors if strict else warnings).append(
+                f"{plan_rel} Plan section is too long ({len(plan_items)} steps > 8); keep to small verifiable steps"
+            )
+        concrete_count = sum(1 for item in plan_items if is_concrete_plan_item(item))
+        min_concrete = 1 if len(plan_items) <= 2 else ((len(plan_items) * 3 + 4) // 5)
+        if concrete_count < min_concrete:
+            (errors if strict else warnings).append(
+                f"{plan_rel} Plan steps are too abstract ({concrete_count}/{len(plan_items)} concrete, need >= {min_concrete}); include files/commands per step"
+            )
+
+    verify_body = section_content.get("Verify", "")
+    if verify_body.strip():
+        if not has_runnable_command(verify_body):
+            (errors if strict else warnings).append(
+                f"{plan_rel} Verify section must contain runnable command(s)"
+            )
+        if not re.search(r"(?i)(期望|预期|expected)", verify_body):
+            (errors if strict else warnings).append(
+                f"{plan_rel} Verify section must include expected result (期望/预期/expected)"
+            )
+
+    return errors, warnings
+
+
 def csv_has_id(path: Path, column: str, value: str) -> bool:
     with path.open("r", encoding="utf-8", errors="replace", newline="") as f:
         reader = csv.DictReader(f)
@@ -187,6 +391,12 @@ def validate_change(
 
     req_id = ""
     prob_id = ""
+    change_id_decl = ""
+    contract_row_decl = ""
+    plan_file_decl = ""
+    evidence_path_decl = ""
+    req_csv = root / "requirements" / "requirements-issues.csv"
+    prob_csv = root / "issues" / "problem-issues.csv"
 
     if proposal_path:
         t = read_text(proposal_path)
@@ -196,13 +406,25 @@ def validate_change(
         if "AI_WORKSPACE.md" not in t:
             warnings.append("proposal.md does not reference AI_WORKSPACE.md (recommended)")
 
+        change_id_decl = extract_id("Change_ID", t)
         req_id = extract_id("Req_ID", t)
         prob_id = extract_id("Problem_ID", t)
+        contract_row_decl = extract_first_id(["Contract_Row", "Contract_Row(s)"], t)
+        plan_file_decl = extract_first_id(["Plan_File", "Plan file"], t)
+        evidence_path_decl = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], t)
+
+        if strict and not change_id_decl:
+            errors.append("proposal.md must include non-empty Change_ID")
+        if change_id_decl and change_id_decl != change_id:
+            (errors if strict else warnings).append(f"Change_ID mismatch in proposal.md: {change_id_decl} (expected: {change_id})")
         if strict and not (req_id or prob_id):
             errors.append("proposal.md must include a non-empty Req_ID or Problem_ID (attribution)")
-
-        req_csv = root / "requirements" / "requirements-issues.csv"
-        prob_csv = root / "issues" / "problem-issues.csv"
+        if strict and not contract_row_decl:
+            errors.append("proposal.md must include non-empty Contract_Row")
+        if strict and not plan_file_decl:
+            errors.append("proposal.md must include non-empty Plan_File")
+        if strict and not evidence_path_decl:
+            errors.append("proposal.md must include non-empty Evidence_Path")
 
         if req_id and req_csv.exists():
             ok = False
@@ -222,6 +444,127 @@ def validate_change(
             if not ok:
                 (errors if strict else warnings).append(f"Problem_ID not found in issues/problem-issues.csv: {prob_id}")
 
+        normalized_contract_refs: List[Tuple[str, str]] = []
+        for raw_ref in split_declared_values(contract_row_decl):
+            kind, value = normalize_contract_ref(raw_ref)
+            found = False
+            resolved_kind = kind
+            try:
+                if kind == "Req_ID":
+                    found = req_csv.exists() and csv_has_id(req_csv, "Req_ID", value)
+                elif kind == "Problem_ID":
+                    found = prob_csv.exists() and csv_has_id(prob_csv, "Problem_ID", value)
+                else:
+                    if req_csv.exists() and csv_has_id(req_csv, "Req_ID", value):
+                        found = True
+                        resolved_kind = "Req_ID"
+                    elif prob_csv.exists() and csv_has_id(prob_csv, "Problem_ID", value):
+                        found = True
+                        resolved_kind = "Problem_ID"
+            except Exception as e:
+                warnings.append(f"failed to resolve Contract_Row reference {raw_ref}: {e}")
+            if not found:
+                (errors if strict else warnings).append(f"Contract_Row not found in requirements/problem CSVs: {raw_ref}")
+                continue
+            normalized_contract_refs.append((resolved_kind, value))
+
+        if req_id:
+            has_req_binding = any(kind == "Req_ID" and value == req_id for kind, value in normalized_contract_refs)
+            if not has_req_binding:
+                (errors if strict else warnings).append(
+                    f"Contract_Row must include Req_ID binding for proposal Req_ID: {req_id}"
+                )
+        if prob_id:
+            has_prob_binding = any(kind == "Problem_ID" and value == prob_id for kind, value in normalized_contract_refs)
+            if not has_prob_binding:
+                (errors if strict else warnings).append(
+                    f"Contract_Row must include Problem_ID binding for proposal Problem_ID: {prob_id}"
+                )
+
+        plan_files = split_declared_values(plan_file_decl)
+        if strict and len(plan_files) > 1:
+            errors.append("proposal.md Plan_File must contain exactly one plan path")
+        if plan_files:
+            plan_rel = plan_files[0]
+            if plan_rel.startswith("./"):
+                plan_rel = plan_rel[2:]
+            if os.path.isabs(plan_rel):
+                (errors if strict else warnings).append(f"Plan_File must be workspace-relative, got absolute path: {plan_rel}")
+            if not plan_rel.startswith("plan/"):
+                (errors if strict else warnings).append(f"Plan_File should be under plan/: {plan_rel}")
+
+            plan_abs = (root / plan_rel).resolve()
+            try:
+                plan_abs.relative_to(root)
+            except Exception:
+                (errors if strict else warnings).append(f"Plan_File points outside workspace: {plan_rel}")
+            else:
+                if not plan_abs.exists():
+                    (errors if strict else warnings).append(f"Plan_File does not exist: {plan_rel}")
+                else:
+                    plan_text = read_text(plan_abs)
+                    plan_change_id = extract_id("Change_ID", plan_text)
+                    plan_req_id = extract_id("Req_ID", plan_text)
+                    plan_prob_id = extract_id("Problem_ID", plan_text)
+                    plan_contract_row = extract_first_id(["Contract_Row", "Contract_Row(s)"], plan_text)
+                    plan_file_from_plan = extract_first_id(["Plan_File", "Plan file"], plan_text)
+                    plan_evidence_path = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], plan_text)
+
+                    if strict and not plan_change_id:
+                        errors.append(f"{plan_rel} must include non-empty Change_ID")
+                    if plan_change_id and plan_change_id != change_id:
+                        (errors if strict else warnings).append(
+                            f"Change_ID mismatch in {plan_rel}: {plan_change_id} (expected: {change_id})"
+                        )
+                    if strict and not (plan_req_id or plan_prob_id):
+                        errors.append(f"{plan_rel} must include non-empty Req_ID or Problem_ID")
+                    if req_id and plan_req_id != req_id:
+                        (errors if strict else warnings).append(
+                            f"Req_ID mismatch between proposal.md and {plan_rel}: proposal={req_id}, plan={plan_req_id or '(empty)'}"
+                        )
+                    if prob_id and plan_prob_id != prob_id:
+                        (errors if strict else warnings).append(
+                            f"Problem_ID mismatch between proposal.md and {plan_rel}: proposal={prob_id}, plan={plan_prob_id or '(empty)'}"
+                        )
+                    if strict and not plan_contract_row:
+                        errors.append(f"{plan_rel} must include non-empty Contract_Row")
+                    if strict and not plan_file_from_plan:
+                        errors.append(f"{plan_rel} must include non-empty Plan_File")
+                    if strict and not plan_evidence_path:
+                        errors.append(f"{plan_rel} must include non-empty Evidence_Path")
+
+                    if plan_file_from_plan:
+                        plan_file_refs = split_declared_values(plan_file_from_plan)
+                        normalized_plan_ref = plan_file_refs[0] if plan_file_refs else ""
+                        if normalized_plan_ref.startswith("./"):
+                            normalized_plan_ref = normalized_plan_ref[2:]
+                        if normalized_plan_ref and normalized_plan_ref != plan_rel:
+                            (errors if strict else warnings).append(
+                                f"Plan_File mismatch in {plan_rel}: {normalized_plan_ref} (expected: {plan_rel})"
+                            )
+
+                    proposal_contract_set = {normalize_contract_ref(v) for v in split_declared_values(contract_row_decl)}
+                    plan_contract_set = {normalize_contract_ref(v) for v in split_declared_values(plan_contract_row)}
+                    missing_contract = proposal_contract_set - plan_contract_set
+                    if missing_contract:
+                        missing_text = ", ".join([f"{kind}={value}" for kind, value in sorted(missing_contract)])
+                        (errors if strict else warnings).append(
+                            f"{plan_rel} missing Contract_Row bindings declared in proposal.md: {missing_text}"
+                        )
+
+                    proposal_evidence_set = set(split_declared_values(evidence_path_decl))
+                    plan_evidence_set = set(split_declared_values(plan_evidence_path))
+                    missing_evidence = proposal_evidence_set - plan_evidence_set
+                    if missing_evidence:
+                        missing_text = ", ".join(sorted(missing_evidence))
+                        (errors if strict else warnings).append(
+                            f"{plan_rel} missing Evidence_Path entries declared in proposal.md: {missing_text}"
+                        )
+
+                    quality_errors, quality_warnings = validate_plan_quality(plan_text, plan_rel, strict)
+                    errors.extend(quality_errors)
+                    warnings.extend(quality_warnings)
+
     if tasks_path:
         t = read_text(tasks_path)
         placeholder_scan("tasks.md", t)
@@ -249,7 +592,11 @@ def main(argv: Optional[List[str]] = None) -> int:
         default="",
         help="Branch name to validate against (for CI detached HEAD). When set, enforces change/<id> naming.",
     )
-    parser.add_argument("--strict", action="store_true", help="Treat WS:TODO as errors and require attribution IDs.")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat WS:TODO as errors; require main bindings and enforce plan quality gate (sections, step granularity, verify commands).",
+    )
     parser.add_argument(
         "--allow-truth-drift",
         action="store_true",