@mstar-harness/omp 3.6.0-alpha.4

package/harness-skills/mstar-artifacts/references/plan-files-and-reports.md

@@ -0,0 +1,98 @@
+# Plan 文件与 Review Bundle 留档（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 排 review bundle / QC 波次前，须已 Read **`mstar-harness-core`** skill（SKILL.md；多 worktree 与 QC 单一 `HEAD` 见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
+
+## Plan 文件（`{PLAN_DIR}/<name>.md`）
+
+每个 plan 的详细内容（任务清单、决策、Sign-off）。
+
+**命名（推荐）**：`<plan-id>-<plan-name>.md`（例：`01-data-infrastructure.md`）。snapshot plan 行的 `file` 字段填相对仓库根或 `{PLAN_DIR}` 下的实际路径。
+
+## Review bundle（`{SDD_DIR}/review/`）
+
+QC/QA 原始过程报告默认是 **ephemeral review bundle**，置于 `{SDD_DIR}/review/`（即 `{HARNESS_DIR}/sdd/<plan-id>/review/`）。该目录随 `{SDD_DIR}` gitignored，不作为长期 git 审计链。
+
+**QC basename rule**：`{SDD_DIR}` 已含 `<plan-id>` — **do not** repeat it in report filenames. Put `plan_id` in YAML frontmatter only.
+
+| 类型 | 文件名（相对 `{SDD_DIR}/review/`） |
+|------|--------|
+| QC 三审报告（**SDD 默认** `Execution mode: sdd`） | `qc1.md`、`qc2.md`、`qc3.md` |
+| QC 单席报告（**`inline` / hotfix 例外**） | `qc.md` |
+| QC 汇总结论（tri 模式） | `qc-consolidated.md` |
+| QA 验收报告（`QA gate: mandatory`） | `qa.md`（或 Assignment 指定的同目录 basename） |
+
+
+## SDD 运行时（不入 reports）
+
+Per-task briefs, implementer reports, review diffs, branch review packages, and QC/QA bundle files live under **`{SDD_DIR}`** (`mstar-conventions`). Gitignored. Main plan may index `{SDD_DIR}` / `{SDD_DIR}/review/` paths only — do not paste SDD bodies or raw QC/QA reports into plan markdown.
+
+Plan template with Global Constraints / Interfaces → **`templates/plan.main.md`**.
+
+## QC 模式（L3 plan 级）
+
+职责分层 L1–L4 → **`mstar-review-qc/references/review-responsibility-boundaries.md`**。bundle basename 见上表；触发时机与 re-review 波次见下节 **§ QC 三审触发时机**。
+
+## Durable summaries（主 plan / status）
+
+Raw bundle files may disappear after the working context is gone. Before Done, PM must preserve the durable decision surface:
+
+- Main plan `## Review Gate Summary`:
+  - `Decision`: `Approve` | `Approve with residuals` | `Request Changes` | `Needs Discussion`
+  - `Review range / Diff basis`
+  - `Review bundle`: `{SDD_DIR}/review/`
+  - `QC inputs`: `qc1.md` / `qc2.md` / `qc3.md` or `qc.md`
+  - `Blocking result`: fixed / none / deferred with reason
+  - `Residual findings`: R# ids + short titles + owner/target
+- Main plan `## QA Gate Summary` when QA applies:
+  - `QA gate` / `QA mode`
+  - evidence reused vs newly run checks
+  - related R# closure recommendations
+- `{PROJECT_DIR}/<id>/residuals.json` (default `{HARNESS_DIR}/projects/<id>/`): open R# machine SSOT — `entries[<plan-id>]`.
+
+The durable summary is not a paste of raw reports. It is a small gate record sufficient for handoff after `{SDD_DIR}` is unavailable.
+
+## Residual findings（R#）：权威在哪、和主 plan 谁先谁后？
+
+- **Open 条目的单一事实来源（SSOT）**是 **`{PROJECT_DIR}/<id>/residuals.json`**（默认 `{HARNESS_DIR}/projects/<id>/`；无项目流程用 `_default`）的 **`entries[<plan-id>]`**（canonical 见 `mstar-artifacts` **SKILL.md** 开篇；字段见 `mstar-artifacts/references/status-and-residuals.md`）。**同一工作副本内**的会话 handoff、关闭流程**以该数组为准**（本地 SSOT，默认 gitignored）；**跨 clone** 须持久的 residual 须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 等（见 `mstar-conventions`「Git 跟踪策略」）。
+- **推荐操作顺序**（避免 plan 与 JSON 两套 ID 漂移）：
+  1. `project-manager` 读完 review bundle 并完成「QC 三审轻量汇总」：对 finding **去重合并**，为每条待跟踪项分配**稳定 `id`**（如 `R1`、`R2`，全 plan 内唯一）。
+  2. **立即**将上述条目写入 register **`entries[<plan-id>]`**（含 `source` 指向 reviewer seat + bundle basename + finding id + review range，便于回溯；`source_plan` = plan id，`registered_at` = 当日）；v1 根级 `residual_findings` 仅 legacy 只读，**勿**双写。
+  3. **可选**：在主 plan 中增加 **「Residual findings（索引）」** 小节，**仅复述** `id` + 短标题 + 决策摘要，并写明「**权威列表见** `projects/<id>/residuals.json` `entries[<plan-id>]`（见 `mstar-conventions` **SKILL.md** 开篇）」。**不要**只在主 plan 里「发明」R# 而不写回 SSOT。
+- **不要**反过来把主 plan 当作唯一登记处：若仅更新 plan、register 未同步，下一任 agent **无法**依赖 SSOT 继承债务状态。
+
+## QC 三审触发时机（单 plan · 多 batch）
+
+- **默认（SDD）**：同一 **`plan_id`** 下，**plan QC tri-review**（`qc-specialist` ×3 → `{SDD_DIR}/review/qc1.md`…`qc3.md` + `qc-consolidated.md`）**仅在** dev team 按该 plan 约定范围全部交付、且 **L2 task reviewers** 均已通过后执行 **一次**。**不要**在每个中间 batch 跑完整三审。
+- **单席例外**：`Execution mode: inline` / hotfix → 交付完成后 **一次** `qc.md`（`QC mode: single`）。
+- **batch 之间**：依赖实现方按 **`mstar-coding-behavior`** 提供完成证据、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
+- **After `Request Changes` (default — targeted re-review)**：PM maps each **blocking** finding to the QC seat that raised it (`source` on R#, consolidated table, or the originating `qcN.md` / `F-###`). Dispatch **only** those reviewers (`QC re-review: targeted — reviewers: qc-specialist, qc-specialist-2, …`). Each re-reviewing QC **updates the same** bundle file (`qc1.md` / `qc2.md` / `qc3.md`) in place (add `## Revalidation`, refresh verdict / `generated_at`); **do not** add `qc1-rev2.md` siblings for targeted re-review. PM **updates the same** `qc-consolidated.md` and durable plan summary.
+- **Full tri re-review (exception)**：Only when Assignment states **`QC re-review: full tri-review`**. Run **three** parallel reviews again; use **new bundle basenames** (`qc1-rev2.md` … `qc3-rev2.md`, `qc-consolidated-rev2.md`) so wave-1 files stay distinct; PM states **active wave** in consolidated decision and durable plan summary. See `mstar-review-qc` · `mstar-dispatch-gates`.
+- **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用 `{SDD_DIR}/review/<scope>/` 子目录，避免与终局 `qc1..3.md` 混名。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 向显式 `target_branch` **走 PR**，见 `mstar-conventions` SKILL.md **「Spec 驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
+
+### 多 `plan_id` 同时 `InReview`（PM 编排）
+
+- **流程**：实现完成 → 该 **`plan_id`** 进入 **`InReview`** → **QC 三审（仅针对该 plan 的 `Review range`）** → PM consolidated → **QA** → **`Done`**。**禁止**在多个 `plan_id` 已 `InReview` 的情况下，只推进新实现、不派 QC，或把多个 plan 的变更**伪装成**一套三审字段（单一 `plan_id` / 单一 diff 范围覆盖多 plan）。
+- **并行 vs 串行**：不同 `plan_id` **相互独立**时，可 **并行**派发多组三审（每组各自的 Assignment 与 `{SDD_DIR}/review/`）；若 PM 选择串行，须在 Status Update 写明顺序——**每组仍须完整三审 + QA**，不是「一个大 QC」混审。
+- **读 skill**：书写或派发 QC 相关 Assignment 前，PM **必须** Read **`mstar-review-qc`**（编排与 residual）；leaf `qc-specialist*` → **`mstar-roles/references/qc-specialist/`**。见 `mstar-conventions` SKILL.md **QC pre-dispatch gate**。
+
+**QC 落盘与宿主权限**：`qc-specialist` / `qc-specialist-2` / `qc-specialist-3` 在支持路径白名单的宿主上（如 OpenCode 的 **`permission.edit`**），默认 **仅可** Write/Edit Assignment 指定的 **`{SDD_DIR}/review/`** 下 **`.md`**。全局 agent 提示词应允许 `.mstar/sdd/**`、`.agents/sdd/**` 及 `.worktrees/**`。报告文件**必须**以 YAML **frontmatter** 开头（键见各 QC agent 提示词）。
+
+**QC 报告与 Git**：默认 raw QC/QA bundle **不**执行 `git add` / `git commit`。PM 将 durable gate summary 写入主 plan（本地会话 SSOT；默认 gitignored）并在当轮更新 project register 的 open residuals（本地 SSOT，默认 gitignored）。**跨 clone 须持久的** residual 或决策须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 或 `{HARNESS_DIR}/AGENTS.md`（见 `mstar-conventions`「Git 跟踪策略」）— **勿**默认 `git add` `status.json` / `workflows/` / `projects/` / `plans/`。若项目显式 opt-in 跟踪审计报告，在 Assignment 写 `Review archive mode: tracked reports` 并使用项目 allow rules。
+
+## 主 plan 内任务清单（Markdown checkbox）
+
+- **谁应更新**：`fullstack-dev` / `frontend-dev` / `fullstack-dev-2`、`qa-engineer`、`ops-engineer`、`architect`、`product-manager` 在**完成本人 Assignment 范围内的工作后**，须在主 plan（`<plan-id>-<plan-name>.md`）中把**对应条目**的 Markdown 任务标记为已完成（常见：`- [ ]` → `- [x]`；若项目用其它清单记号，保持同文件内一致）。与 Completion Report **并列**，作为跨会话可核对的**落盘痕迹**。
+- **范围**：**只勾选与当前任务直接对应、且已由本角色交付证据支撑的条目**；不得代为勾选他人负责或未完工项。若正文用分段、Owner 或角色标签区分任务，以 Assignment 与文内约定为准。
+- **与 snapshot / frontmatter 的关系**：勾选任务**不**等于整条计划收口。snapshot `plans[].status` 及主 plan frontmatter 的 **`Done`** 仍**仅** `project-manager` / `qa-engineer`（见「状态更新权限」）。`architect` / `product-manager` **不得**擅自将整条计划标为 `Done`；是否将 snapshot 推进为 `InReview` 等仍按下文「状态更新权限」与 Assignment。
+- **`qc-specialist*`**：**不得**修改主 plan（宿主仅允许 Assignment 指定的 review bundle `.md`）；审查结论落在 `{SDD_DIR}/review/` 内。若主 plan 需新增或勾选与审查相关的条目，由 `project-manager` 或 Assignment 明确授权的角色据报告回写。
+- **只读角色**：不直接改主 plan；将建议交给 `project-manager` 代为更新清单。
+
+Plan 正文与 snapshot 行必须保持一致；不一致时以 snapshot `plans[].status` 为准并尽快纠正正文或登记 notes（`workflows/<id>/notes.jsonl`）。
+
+## Done 标记方式
+
+1. **Frontmatter**（首选）：添加 `status: Done` 和可选的 `done_at: YYYY-MM-DD`。
+2. **文件名**（备选）：重命名为 `DONE__<name>.md` 或 `<name>.done.md`。
+
+同时更新 snapshot 对应 plan 行（`workflows/<id>/snapshot.json` → `plans[]`）与根 `status.json` `workflows[]` 登记。

package/harness-skills/mstar-artifacts/references/plan-quality-bar.md

@@ -0,0 +1,99 @@
+# Plan Quality Bar
+
+The standard every implementation plan must meet before it is locked and dispatched. Applies to `{PLAN_DIR}` main plans, SDD task-briefs derived from them, and audit-generated plans. Extends the Plan 质量门 in **`mstar-phase-gates`** and the `plan.main.md` template.
+
+## Core principle: write for a zero-context executor
+
+SDD implementers start with a fresh session — they have not seen the Prepare conversation, the spec, or other tasks. Audit plans may be executed sessions or days later by a different model. If a plan references "the pattern discussed above" or "as agreed in clarify", it is broken.
+
+The plan is the spec. Everything the executor needs must be in the file or reachable from a file path it names.
+
+## Quality checklist
+
+Before a plan is locked, verify every item:
+
+### 1. Self-contained context
+
+- Every task names **exact file paths** (create / modify / test), not "the relevant module".
+- **Current-state excerpts** — when a task modifies existing code, include the code as it exists today (short, with `file:line` markers), enough that the executor can confirm it is looking at the right thing.
+- **Conventions to follow** — name the repo pattern (error handling, naming, layering) and point to one exemplar file: "Error handling follows the Result pattern — see `src/lib/result.ts` and its use in `src/users/api.ts:40-60`. Match it."
+- **Interfaces** — consumed and produced signatures are listed verbatim, not paraphrased.
+
+### 2. Verification gates
+
+Every step ends with a **command and its expected result**, not a judgment call.
+
+| Pattern | Weak (do not use) | Strong (required) |
+|---------|-------------------|-------------------|
+| Test step | "run the tests" | `pnpm test -- orders` → all pass, including 2 new tests |
+| Typecheck | "make sure it compiles" | `pnpm typecheck` → exit 0, no errors |
+| Removal | "clean up the old code" | `grep -rn "oldPattern" src/` → no matches |
+
+The executor should never have to *judge* whether a step succeeded — it runs a command and compares output.
+
+### 3. Hard boundaries
+
+Each task lists:
+
+- **In scope** — the only files the executor should modify.
+- **Out of scope** — files that look related but must not be touched, with a one-line reason ("deprecated path, scheduled for deletion").
+
+### 4. STOP conditions
+
+Plan-specific escape hatches — not boilerplate. Name the risks particular to this work:
+
+- "If `config.ts` no longer exports `getDb`, STOP — the migration in plan 003 may have landed first."
+- "If the test in step 2 fails for a reason other than the missing import, STOP — the assumption that `User.email` is non-nullable may be false."
+
+The executor stops and reports instead of improvising. This is what lets a weaker model execute safely.
+
+### 5. Drift check
+
+Stamp the commit the plan was written against. Before execution, the executor (or PM) runs:
+
+```
+git diff --stat <planned-at-sha>..HEAD -- <in-scope-paths>
+```
+
+If any in-scope file changed, the executor compares the plan's "current state" excerpts against live code before proceeding. On mismatch → STOP condition.
+
+In SDD, this maps to the `BASE_SHA` recorded before Task 1.
+
+### 6. Done criteria (machine-checkable)
+
+ALL must hold — commands and expected results, not prose:
+
+```markdown
+## Done criteria
+
+- [ ] `pnpm typecheck` exits 0
+- [ ] `pnpm test` exits 0; new tests for <X> exist and pass
+- [ ] `grep -rn "<old-pattern>" src/` returns no matches
+- [ ] No files outside the in-scope list are modified (`git status`)
+```
+
+"Works correctly" is not a done criterion.
+
+## Relationship to existing plan elements
+
+| This quality bar | Existing mstar element |
+|------------------|----------------------|
+| Self-contained context | `plan.main.md` Global Constraints + per-task Files/Interfaces |
+| Verification gates | `plan.main.md` per-step "Run: `cmd`" lines |
+| Hard boundaries | `plan.main.md` per-task Files (Create/Modify) — extended with explicit Out-of-scope |
+| STOP conditions | New — not previously formalized |
+| Drift check | SDD `BASE_SHA` — generalized to all plans |
+| Done criteria | `plan.main.md` per-step checkboxes — elevated to machine-checkable |
+
+## When to apply
+
+| Plan source | Applies |
+|-------------|---------|
+| PM/architect Prepare | Full bar before `plan(locked)` |
+| SDD task-brief (extracted from plan) | Inherits from plan; `mstar sdd task-brief` carries excerpts forward |
+| Audit-generated plan (`mstar-audit`) | Full bar — audit plans are the most context-isolated |
+| Hotfix (`inline`) | Relaxed — see `mstar-phase-gates` hotfix exception |
+
+## Attribution
+
+The self-containment, verification-gate, STOP-condition, and drift-check concepts are adapted from the [improve](https://github.com/shadcn/improve) skill (MIT, © shadcn), integrated into Morning Star's plan-artifact conventions.