# 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`）。执行 plan 行的 `file` 字段填相对仓库根或 `{PLAN_DIR}` 下的实际路径。

**身份与路径权威**：plan 的 id / title / 文档路径 / project-iteration 归属与 spec/knowledge 关系是 **`{HARNESS_DIR}/store.db`** 的 catalog 行（contract §1；读法 `mstar catalog show plan <plan-id>`）。ACTIVE 的 `execution_plans` 行承载 **prepare 时从某个 catalog revision 复制来的冻结执行输入** `id/title/file`（`catalog_pin`），**不是**可独立编辑的第二份 catalog。catalog 变更不静默刷新在途输入，进度更新也不改写它。从 tracked 正文发现候选用 `mstar catalog discover`（只读提案，含显式 `unknowns`），review 后 `mstar catalog import` 登记。

## Edit attribution (process-local SSOT)

For each substantive edit, the local gitignored iteration/process record carries actual ISO-8601 edit time, editor seat, model **only if observable** (otherwise `unknown`), iteration/workflow identity, and edited scope. Record a correction at its actual correction time and disclose the prior unobserved edit; never backdate or infer another agent's model. Tracked plans and examples may contain synthetic attribution only, not real runtime paths, persons or model provenance. Plan QC and iteration close review the local record against edits and report omissions for correction; this is review-side judgment, **not** a status field, signature, author database or machine gate.

## 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） |
| L2 task review 报告（**`Execution mode: sdd`，每个已完成 task**） | `../task-N-review.md` |
| Implementer 报告（**`Execution mode: sdd`**） | `../task-N-report.md` |

后两行的 `../` 是**必需**前缀：这两份 artifact 落在 `{SDD_DIR}` 根，**不在** review bundle 内。按上表表头解析，`../task-N-review.md` = **`{SDD_DIR}/task-N-review.md`**，`../task-N-report.md` = **`{SDD_DIR}/task-N-report.md`**；漏掉该前缀（即让它们落在 `{SDD_DIR}/review/` 下）就是错误解析。两者由不同角色写、互不覆盖：implementer 始终写 `task-N-report.md` —— 它是 L2 的**输入**，永不被 L2 覆盖，也不能充当独立审查；fresh L2 task reviewer 始终写 `task-N-review.md`（`Execution mode: sdd` 下每个已完成 task 都必有，不是可选、也不是只留在对话里）。**不存在**接受任一 basename 的 fallback。

Mandatory QA always writes `${SDD_DIR}/review/qa.md` (or the Assignment's explicit same-directory basename) with its AC → evidence → result mapping; report-only is a mode, not a condition for mandatory report landing.

## 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`
  - `Task reviews`: compact per completed task — task number + review range + earned `Task quality` + report pointer (`task-N-review.md` → `{SDD_DIR}/task-N-review.md`); required for handoff once `{SDD_DIR}` is unavailable. The L2 report file lives at the SDD root (outside `{SDD_DIR}/review/`); bundle cleanup removes only the ephemeral `review/` artifacts. The pointer names the L2 report, never the implementer's `task-N-report.md`
  - `Blocking result`: fixed / none / deferred with reason
  - `Residual findings`: each open issue — id + short title + issue severity + store tracking location + owner/target + blocker-defer flag (`N/A — none open` when none)
- Main plan `## QA Gate Summary` when QA applies:
  - `QA gate` / `QA mode`
  - acceptance trace: compact AC → evidence → result mapping + coverage/gap disclosure + exact report pointer (`qa.md` → `{SDD_DIR}/review/qa.md`)
  - evidence reused vs newly run checks
  - related R# closure recommendations
- `{HARNESS_DIR}/store.db` linked issues: open-item machine SSOT (`mstar issue list` / `mstar issue show`); `{PROJECT_DIR}/<id>/residuals.json` is migration history only.

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）**是 **`{HARNESS_DIR}/store.db` 的 plan-linked issues**（canonical → `mstar-artifacts` SKILL.md；字段 → `references/status-and-residuals.md`）。会话 handoff、关闭流程以 issue 状态为准；project register 数组仅作迁移历史，任何 authority 状态下都不是写目标。**跨 clone** 须持久的 finding 须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 等。
- **推荐操作顺序**（避免报告与 store 两套身份漂移）：
  1. PM 读完 review bundle 并完成去重合并；已有 issue 复用身份，重复出现追加 occurrence。
  2. **立即**经 `mstar plan issue-add`（计划内）或 `mstar issue add` 捕获，保留 reviewer seat、bundle basename、finding id 与 review range 等来源证据；以回执 issue id 追踪，不写 register。
  3. **可选**：主 plan 增加「Residual findings（索引）」，仅复述 issue id + 短标题 + 决策摘要，注明「**权威列表见 store 的 plan-linked issues（`mstar issue list` / `mstar issue show`）**」。
- **不要**把主 plan 当作唯一登记处：仅更新散文而未捕获 issue，下一任 agent 无法继承权威债务状态。

## 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.
- **Three-seat re-review**：Only when all three seats have affected findings; Assignment may state **`QC re-review: full tri-review`** for the seat count. Each reviews only its findings and fix delta, never unchanged scope; 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/`）；若有真实依赖需串行，须在 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` 在支持路径白名单的宿主上，默认 **仅可** 写入或编辑 Assignment 指定的 **`{SDD_DIR}/review/`** 下 **`.md`**。权限范围应按 Assignment 的绝对报告路径配置；worktree 默认根为 `<parent-of-repo-root>/{repo-basename}.worktrees/`（repo root 为 Git top-level 的 realpath），不据此假定任何相对权限 glob 的解析基准或覆盖范围。报告文件**必须**以 YAML **frontmatter** 开头（键见各 QC agent 提示词）。

**QC 报告与 Git**：默认 raw QC/QA bundle **不**执行 `git add` / `git commit`。PM 将 durable gate summary 写入主 plan（authored artifact；默认 gitignored），并在当轮捕获/关闭 store 中的 plan-linked issues。**跨 clone 须持久的** finding 或决策须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 或 `{HARNESS_DIR}/AGENTS.md` — **勿**默认 `git add` `status.json` / `workflows/` / `projects/` / `plans/`。若项目显式 opt-in 跟踪审计报告，在 Assignment 写 `Review archive mode: tracked reports` 并使用项目 allow rules。
PM 提交显式 opt-in 的 tracked reports 时仅用已配置身份；身份缺失或失败则 **Blocked**，不得编造或逐次提交覆盖身份 → `mstar-roles/references/_shared/leaf-executor-core.md`「Git NEVER (repo writes)」。

## 主 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 与文内约定为准。
- **与执行行 / frontmatter 的关系**：勾选任务**不**等于整条计划收口。store 执行 plan 行及主 plan frontmatter 的 **`Done`** 仍**仅** PM / QA；是否推进 `InReview` 等按状态权限与 Assignment。
- **`qc-specialist*`**：**不得**修改主 plan（宿主仅允许 Assignment 指定的 review bundle `.md`）；审查结论落在 `{SDD_DIR}/review/` 内。若主 plan 需新增或勾选与审查相关的条目，由 `project-manager` 或 Assignment 明确授权的角色据报告回写。
- **只读角色**：不直接改主 plan；将建议交给 `project-manager` 代为更新清单。

Plan 正文与执行行必须保持一致；不一致时以 store plan 行状态为准，尽快纠正正文或经公共动词追加 notes（`workflows/<id>/notes.jsonl`）。

## Done 标记方式

1. **Frontmatter**（首选）：添加 `status: Done` 和可选的 `done_at: YYYY-MM-DD`。
2. **文件名**（备选）：重命名为 `DONE__<name>.md` 或 `<name>.done.md`。

执行状态经 `mstar plan complete` 等公共 plan 动词写入 store；完成交付尾段后由 `mstar status workflow-close` 收口 root register。不要手写 root `status.json` 或 workflow snapshot；它们是 migration sources / retained history，不是执行权威。主 plan 标记不是执行状态权威。