日常更新

ansible/tools/gen_stories_by_doc.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""按执行域 doc_id 生成 BMad [CS] story-doc-XX-YY.md（与 verify playbook 一一对应）。
+
+输出目录：_bmad-output/implementation-artifacts/stories-by-doc/
+索引：同目录 README.md
+
+用法：
+  python3 ansible/tools/gen_stories_by_doc.py              # 全量
+  python3 ansible/tools/gen_stories_by_doc.py --doc-id 02-05  # 单篇
+  python3 ansible/tools/gen_stories_by_doc.py --readme-only  # 仅刷新 README（含队列表）
+  python3 ansible/tools/gen_stories_by_doc.py --dry-run
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+VERIFY_DIR = ROOT / "ansible" / "playbooks" / "verify"
+DOCS_DIR = ROOT / "docs"
+OUT_DIR = ROOT / "_bmad-output" / "implementation-artifacts" / "stories-by-doc"
+
+EXEC_ID_RE = re.compile(r"^(0[1-9]|[1-9][0-9])-(0[1-9]|[1-9][0-9])\.yml$")
+
+
+def playbook_is_noop(doc_id: str) -> bool:
+    yml = VERIFY_DIR / f"{doc_id}.yml"
+    if not yml.is_file():
+        return False
+    content = yml.read_text(encoding="utf-8", errors="ignore")
+    return "noop verify" in content.lower() or "noop-doc-verify" in content
+
+
+def doc_title(doc_path: Path | None) -> str:
+    if doc_path is None or not doc_path.exists():
+        return "（文档待补）"
+    text = doc_path.read_text(encoding="utf-8", errors="ignore")
+    first = text.splitlines()[0].strip() if text else ""
+    if first.startswith("#"):
+        return first.lstrip("#").strip()
+    return doc_path.stem
+
+
+def story_body(doc_id: str, rel_doc: str, title: str, noop: bool) -> str:
+    pb_rel = f"ansible/playbooks/verify/{doc_id}.yml"
+    story_rel = f"_bmad-output/implementation-artifacts/stories-by-doc/story-doc-{doc_id}.md"
+    noop_line = (
+        "**noop + verify_common 基线**（文档步骤以手工/Helm 为主）"
+        if noop
+        else "**自定义断言**（非纯 noop）"
+    )
+    return f"""# Story [CS] doc_id {doc_id}：{title}
+
+Status: ready-for-dev
+
+<!-- BMad [CS]：与执行域 doc_id 一一对应；由 ansible/tools/gen_stories_by_doc.py 生成。实施入口：Cursor `/bmad-dev-story`，并指定本 Story 文件路径 `{story_rel}`；工作流见 `.cursor/skills/bmad-dev-story/workflow.md`。 -->
+
+## Meta
+
+| 字段 | 值 |
+|------|-----|
+| **doc_id** | `{doc_id}` |
+| **文档** | `{rel_doc}` |
+| **verify playbook** | `{pb_rel}` |
+| **清单/示例目录** | `ansible/files/{doc_id}/` |
+| **playbook 形态** | {noop_line} |
+
+## bmad-dev-story 入口
+
+- **实施**：在 Cursor 使用 **`/bmad-dev-story`**，并在对话中提供本文件路径：`{story_rel}`（仓库根相对路径）。  
+- **工作流**：技能 **`bmad-dev-story`** → `.cursor/skills/bmad-dev-story/workflow.md`；Agent 仅可改本 Story 内 Tasks 勾选、Dev Agent Record、File List、Change Log、Status（与 workflow 一致）。
+
+## Story
+
+作为一名 **实验室维护者**，  
+我希望 **`./ansible/bin/verify.sh run {doc_id}`**（或 `./scripts/cs {doc_id}`）的行为与 **`{rel_doc}`** 中的 TL;DR / 成功判据 / 自动化验收描述一致，并满足仓库 **doc_id 三元契约** 与 **Output Contract（`[OC]` / `[OC-ASSERT]`）** 约定，  
+以便 **状态板、offline-check 与文档** 不漂移；**实施与收尾一律按 `/bmad-dev-story` 工作流、以本 Story 为规格真源**。
+
+## Acceptance Criteria
+
+1. **契约**：存在 `docs/{doc_id}-*.md`、`ansible/playbooks/verify/{doc_id}.yml`、`ansible/files/{doc_id}/`；`python3 ansible/tools/validate_matrix_playbooks.py` 通过。  
+2. **离线门禁**：`./scripts/offline-check.sh` 通过（含 R3 链接、syntax-check）。  
+3. **运行验收**：在已连通集群的实验室环境执行 `./ansible/bin/verify.sh run {doc_id}`，结果符合该篇文档预期（`verified` / `gated` 均需可解释；失败则修 playbook 或文档）。  
+4. **输出语义**：playbook 日志中 **`[OC]`** 行可被状态板/脚本解析；含断言处优先带 **`[OC-ASSERT]`**（与 `project-context.md`、ADR-004 一致）。  
+5. **文档真源**：篇内「契约与真源」或等价段落指向 `ansible/files/{doc_id}/`（若含带 yaml 标注的 fenced 代码块，须出现 `ansible/files/{doc_id}/` 路径以满足弱门禁）。
+
+## Tasks / Subtasks
+
+- [ ] **T1** 对照 **`{rel_doc}`** 的 TL;DR / 验证命令 / 预期，列出与 playbook 任务映射表（缺项 = 未覆盖）。  
+- [ ] **T2** 若存在差距：改 **`{pb_rel}`** 或 **`verify_common` role**，或修订文档（禁止双真源）。  
+- [ ] **T3** 回归：`./scripts/offline-check.sh` + `./ansible/bin/verify.sh run {doc_id}`。  
+- [ ] **T4**（可选）将本轮结论记入 **`_bmad-output/implementation-artifacts/`** 下 OC 笔记（与本 Story 文件名并列索引）。
+
+## Dev Notes
+
+- **执行域**：`XX>0 && YY>0`；导航页 `YY=00` 无对应 story。  
+- **Helm / 手工步骤**：noop 篇以文档与 `ansible/files` 示例为准；自动化安装若扩展，需 **env 门控 + teardown**（见 `00-03` §2.1）。  
+- **禁止**：用 noop **冒充** 已覆盖文档中要求集群变更/探针的判据（见 `epics-and-stories` Epic 2 Story 2.3）。  
+- **主键**：以 `doc_id` 为准；见 `project-context.md`「doc_id 与验证框架」。  
+- **实施入口**：本目录下每篇 Story 均通过 **`/bmad-dev-story`** 执行；勿绕过 workflow 随意改规格外文件而不更新 Tasks / File List。
+
+### References
+
+- [Source: `{rel_doc}`]  
+- [Source: `{pb_rel}`]  
+- [Source: `ansible/files/{doc_id}/README.md`]（若存在）  
+- [Source: `project-context.md` — 契约 / OC]  
+- [Source: `docs/00-03-测试与验证框架.md`]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+（dev-story 填写）
+
+### Completion Notes List
+
+### File List
+
+---
+
+## Story completion status
+
+- **ready-for-dev**
+"""
+
+
+def write_readme(ids: list[str]) -> str:
+    lines = [
+        "# stories-by-doc 索引",
+        "",
+        "> BMad **[CS] Create Story**：每个执行域 `doc_id` 一篇。**实施入口统一为 Cursor `/bmad-dev-story`**：在对话中附上对应 `story-doc-<doc_id>.md` 的仓库根相对路径；工作流见 `.cursor/skills/bmad-dev-story/workflow.md`。",
+        "",
+        "**生成 / 更新**：在仓库根执行 `python3 ansible/tools/gen_stories_by_doc.py`（或 `--doc-id XX-YY` 只生成一篇）。仅刷新本 README、不覆盖各篇 Story 时：`python3 ansible/tools/gen_stories_by_doc.py --readme-only`。",
+        "",
+        "## 开发队列与工作方式（50 篇 ≠ 50 条 Cursor Todo）",
+        "",
+        "### 1. backlog 从哪来",
+        "",
+        "- **优先队列**：[`sprint-status.md`](../sprint-status.md) **§8 后续 Sprint Backlog** — 先做其中仍标 **ready-for-dev** 或缺口明显的 `doc_id`（与 §8 中某行叙事对上的 `doc_id` 共享同一工程真源：`verify` + docs）。",
+        "- **全量索引**：下表列出全部执行域 `doc_id`；需要按系列清扫时，可自 **01-xx → 07-xx** 顺序推进。",
+        "",
+        "### 2. WIP 与 IDE Todo",
+        "",
+        "- **WIP**：[`sprint-status.md`](../sprint-status.md) **§7** — 同一时间最多 **1** 篇 Story `in-progress`。",
+        "- **Cursor**：每次只跑 **`/bmad-dev-story`** + **一篇** `story-doc-XX-YY.md`；IDE Todo 建议只保留 **当前 `doc_id`**（及可选一条回归命令如 `offline-check` / `verify.sh run XX-YY`），**不要**把 50 篇拆成 50 条并行 Todo。",
+        "",
+        "### 3. 收尾与 §8 对齐",
+        "",
+        "- 完成条件以该篇 **AC + Tasks** 为准；按 `.cursor/skills/bmad-dev-story/workflow.md` 更新 Story 内 **Tasks 勾选、Dev Agent Record、File List、Change Log、Status**（如进入 `review`）。",
+        "- **`sprint-status.md` §8**：可与 Story 状态交叉备注；避免长期双真源 — **规格与闭合状态以 Story 文件 + `ansible/playbooks/verify/<doc_id>.yml` + docs 为准**，§8 由维护者 **周期性** 与已闭合项对齐（不必每篇同时改两处）。",
+        "",
+        "## 优先级（以 doc_id 为准）",
+        "",
+        "- **主键**：`doc_id`（`XX-YY`）→ 本目录 **`story-doc-<doc_id>.md`**；与 **`ansible/playbooks/verify/<doc_id>.yml`**、**`docs/<doc_id>-*.md`**、**`ansible/files/<doc_id>/`** 一一对齐。",
+        "- **补充 backlog**：若 `_bmad-output/implementation-artifacts/` 下另有 **同主题** 文件（如 **`*-baseline-verify-oc.md`**、Epic 编号命名的 `3-2-*.md`），视为**同一 `doc_id` 或跨多篇 `doc_id` 的深化说明**；实施与验收仍以 **`verify/<doc_id>.yml` + 对应 docs** 为真源，规划文件名仅作辅助索引。",
+        "",
+        "下表 **Playbook** 列由本脚本根据 `verify/*.yml` 内容自动标注（`noop+verify_common` ≈ 文档/手工为主；`自定义断言` ≈ 含非 noop 任务），便于拣选体量与回归方式。",
+        "",
+        f"共 **{len(ids)}** 篇。",
+        "",
+        "| doc_id | Playbook | Story 文件 |",
+        "|--------|----------|------------|",
+    ]
+    for did in ids:
+        kind = "noop+verify_common" if playbook_is_noop(did) else "自定义断言"
+        lines.append(f"| {did} | {kind} | [story-doc-{did}.md](story-doc-{did}.md) |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def collect_doc_ids(single: str | None) -> list[str]:
+    ids: list[str] = []
+    for p in sorted(VERIFY_DIR.glob("*.yml")):
+        if p.name.startswith("_"):
+            continue
+        if not EXEC_ID_RE.match(p.name):
+            continue
+        stem = p.stem
+        if single and stem != single:
+            continue
+        ids.append(stem)
+    if single and single not in ids:
+        print(f"ERR: doc_id 无对应 verify playbook：{single}", file=sys.stderr)
+        sys.exit(2)
+    return sorted(ids)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="按 doc_id 生成 BMad CS（story-doc-*.md）")
+    ap.add_argument("--doc-id", help="仅生成该 XX-YY（默认全量）")
+    ap.add_argument("--dry-run", action="store_true", help="只打印将写入的路径")
+    ap.add_argument(
+        "--readme-only",
+        action="store_true",
+        help="只重写 stories-by-doc/README.md（不重写各 story-doc-*.md）",
+    )
+    args = ap.parse_args()
+
+    if args.readme_only and args.doc_id:
+        print("ERR: --readme-only 与 --doc-id 不能同时使用", file=sys.stderr)
+        return 2
+
+    doc_ids = collect_doc_ids(args.doc_id)
+    if not doc_ids:
+        print("ERR: 未发现执行域 verify playbook", file=sys.stderr)
+        return 2
+
+    if not args.dry_run:
+        OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    if args.readme_only:
+        if args.dry_run:
+            print(f"would write {OUT_DIR.relative_to(ROOT)}/README.md")
+            return 0
+        readme = write_readme(doc_ids)
+        (OUT_DIR / "README.md").write_text(readme, encoding="utf-8")
+        print(f"[OK] {OUT_DIR.relative_to(ROOT)}/README.md ({len(doc_ids)} 条, --readme-only)")
+        return 0
+
+    for doc_id in doc_ids:
+        noop = playbook_is_noop(doc_id)
+        matches = sorted(DOCS_DIR.glob(f"{doc_id}-*.md"))
+        doc_path = matches[0] if matches else None
+        rel_doc = str(doc_path.relative_to(ROOT)) if doc_path else f"docs/{doc_id}-*.md（缺失）"
+        title = doc_title(doc_path)
+        body = story_body(doc_id, rel_doc, title, noop)
+        out_path = OUT_DIR / f"story-doc-{doc_id}.md"
+        if args.dry_run:
+            print(f"would write {out_path.relative_to(ROOT)}")
+            continue
+        out_path.write_text(body, encoding="utf-8")
+        print(f"[OK] {out_path.relative_to(ROOT)}")
+
+    if args.dry_run:
+        return 0
+
+    readme = write_readme(doc_ids)
+    (OUT_DIR / "README.md").write_text(readme, encoding="utf-8")
+    print(f"[OK] {OUT_DIR.relative_to(ROOT)}/README.md ({len(doc_ids)} 条)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())