@mstar-harness/omp 3.6.0-alpha.4

package/harness-commands/codebase-audit.md

@@ -0,0 +1,40 @@
+---
+name: codebase-audit
+description: Survey a codebase as a senior advisor and produce prioritized, self-contained improvement plans. Read-only on source code. Use standalone before iteration-start to discover what's worth doing, or independently to build a prioritized backlog.
+agent: project-manager
+input: "[simplify]"
+---
+
+# Audit Codebase
+
+Run a read-only codebase audit that discovers what is worth doing and writes self-contained plans for the normal Prepare → Execute flow.
+
+**Read-only.** No source edits, no state machine, no commits. Output: prioritized plans in `{PLAN_DIR}/audit-<date>/`.
+
+## Boot
+
+1. `mstar-harness-core`
+2. `mstar-audit` → SKILL.md（common core：hard rules、recon、vet、variant dispatch、`## Plan output (all variants)`）+ `references/codebase-audit.md`（full-audit 变体：Phase 2 类别 + effort、scope variants、Phase 4 变体细则、audit index 模板）
+3. `mstar-roles` → `references/code-reviewer.md`（执行角色：audit 执行体）
+4. `mstar-conventions` (path symbols — `{PLAN_DIR}`, `{HARNESS_DIR}`)
+5. `mstar-host` → active host reference (invoke capability for parallel subagents)
+
+## Routing（谁执行 audit）
+
+| Context | Who runs the audit |
+|---------|-------------------|
+| **Small repo** (single scan pass feasible) | PM dispatches `@code-reviewer` — single scan pass, then vet and write plans |
+| **Large repo** (parallel categories needed) | `@code-reviewer` fans out read-only `scout` / `explore` subagents per category via Assignment `Delegation: allowed (scout/explore only, read-only)`, then vets and writes plans |
+| **Specialist depth needed** | PM orchestrates an `@architect` consult for architecture/tech-debt depth (separate dispatch, or folded into the audit delegation brief) |
+
+This command is the PM entry point; the audit execution body is `code-reviewer`（PM dispatch）.
+
+The audit is **advisory** — it does not enter the per-plan state machine (`Todo → InProgress → InReview → Done`). Its output is plan *candidates*.
+
+## Execute
+
+Execute **`mstar-audit`** end to end（SKILL.md common core：Recon → Vet & prioritize；full-audit detail：**`references/codebase-audit.md`** —— Phase 2 九类别 fan-out、effort `quick` / `standard` / `deep`、scope variants `bare` / `quick` / `deep` / category focus（`security` / `perf` / `tests`, ...）/ `branch` / `next` / `roadmap` / `simplify`、Phase 4 变体细则、audit index 输出模板；plan writing → SKILL.md **`## Plan output (all variants)`**）。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index，per **`mstar-artifacts/references/plan-quality-bar.md`**。
+
+Executor: PM dispatches `@code-reviewer`；大型仓库 scout 扇出经 Assignment `Delegation: allowed (scout/explore only, read-only)`（Routing 表）。
+
+Pursued plans feed the normal Prepare → Execute flow（fast-track Prepare — intent gate + clarify still apply）or `/iteration-start` as direction candidates。

package/harness-commands/iteration-drive.md

@@ -0,0 +1,48 @@
+---
+name: iteration-drive
+description: Drive the active iteration to completion — Phase 2 Autonomous Execute, Phase 3 iteration-close, Phase 4 Create PR, Phase 5 PR merge-ready loop (prefer babysit/*-babysit; optional greploop when repo has it; else CI fallback) until mergeable. Not Done until Phase 5 exit checklist passes.
+agent: project-manager
+input: "[no args]"
+---
+
+# Drive Iteration
+
+Drive the active Morning Star iteration forward. **Boot loads skills; this command sequences Phase 2 → 3 → 4 → 5.** Phase gate SSOT → **`mstar-iteration`** §2–§5；本 command 仅补充 **可选第三方 helper skill 发现**（Phase 5），不反向写入 `mstar-*`。
+
+## Phase flow（禁止跳步）
+
+`Phase 2: Autonomous Execute → Phase 3: iteration-close → Phase 4: Create PR → Phase 5: PR merge-ready`。Transition gates（HARD）→ **`mstar-iteration`** **Phase transition gates** table。
+
+**Done 定义**：**仅** Phase 5 §5.5 exit checklist 全 `[x]`。**Phase 3 close ≠ Done；Phase 4 开 PR ≠ Done。**
+
+## 共享 invariants / preflight / todos / STOP
+
+Phase 2–5 共享内容（PM invariants、assignment preflight、session todos、continuous-execution STOP）→ **`mstar-iteration/references/command-shared-invariants.md`**（SSOT；不在本命令重复）。
+
+## Boot
+
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 2–5 + `command-shared-invariants.md` → `mstar-compound` → `mstar-dispatch-gates` + host reference → **`mstar-sdd`**（first implement dispatch 前）→ `mstar-review-qc`（first QC 前）→ `mstar-artifacts` / `mstar-conventions` / `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
+
+## Phase 2: Autonomous Execute
+
+Execute **`mstar-iteration` § Phase 2** exactly（§2.0 五道闸 → §2.1 session todos → §2.2 backlog → §2.3 integration branch + control worktree → §2.4 per-plan loop（lease-gated；SDD per-task；QC tri N=3 + QA；serial merge）→ §2.5 dispatch-first → §2.6 push 纪律）。全部 plan `Done` → **STOP** → 打印 `## Phase 3: iteration-close`。
+
+**Assignment preflight**：每次 implement/QC/QA 派发前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行。
+
+## Phase 3: iteration-close
+
+当 **every** plan 为 `Done`：**STOP** per-plan loop → 打印 **`## Phase 3: iteration-close`** → execute **`mstar-iteration` § Phase 3**（→ **`references/phase-3-iteration-close.md`** §3.0→§3.5；§3.1 entry checklist HARD GATE；§3.2 compound + package promotion；§3.4 `status: completed` + `end_date`）→ §3.5 exit 全 `[x]` 后打印 **`## Phase 4: Create PR`**。
+
+## Phase 4: Create PR
+
+Execute **`mstar-iteration` § Phase 4**（→ **`references/phase-4-5-pr-delivery.md`**）：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number → 勾掉 `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
+
+## Phase 5: PR merge-ready（babysit loop）
+
+Execute **`mstar-iteration` § Phase 5**（→ **`references/phase-4-5-pr-delivery.md`** §5.0–§5.2；**§5.1a push cadence HARD**）。**§5.5 exit checklist 全 `[x]` = 本 command Done.**
+
+本 command **叠加**可选 helper skill 发现（**non-`mstar-*`**；不写入 `mstar-*` load order）→ **`mstar-iteration/references/phase5-helper-discovery.md`**（babysit / `*-babysit` / greploop / fallback 路径清单；first readable `SKILL.md` wins）。Loop + review fix hygiene + exit checklist → §5.1–§5.2（同上 reference）。
+
+**Then** report: iteration id, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
+
+PR merge itself may still be manual or a separate host action unless user authorized auto-merge.

package/harness-commands/iteration-loop.md

@@ -0,0 +1,99 @@
+---
+name: iteration-loop
+description: "Autonomous full iteration loop for cloud agents — Phase 1 (code-first auto direction lock + compass/plans + Review & Edit chain) through Phase 2–5 (execute → close → PR → merge-ready). Optional args: direction, scale (S|M|L|XL, default M). Not Done until Phase 5 exit checklist passes. Minimal human intervention; no grill-me."
+agent: project-manager
+input: "[direction] [scale]"
+---
+
+# Iteration Loop
+
+Run a **full** Morning Star iteration with minimal human intervention. **Done = Phase 5 §5.5 exit checklist 全 `[x]`** — not Phase 1 lock, not Phase 3 close, not Phase 4 PR open.
+
+**vs other commands:**
+
+| Command | Scope |
+| `iteration-start` | Phase 1 (**grill-me** with user) → **auto-continue** Phase 2→5（`pause` 止于 Phase 1） |
+| `iteration-drive` | Phase 2→5 re-entry / resume on an already locked iteration |
+| **`iteration-loop`** | Phase 1→5 end-to-end; **autonomous** direction lock |
+
+Phase gate SSOT → **`mstar-iteration`** §1–§5. This command is a **consumer**; it does not redefine skill semantics.
+
+## Args（最多 2 个）
+
+```text
+/iteration-loop [direction] [scale]
+```
+
+| Arg | Meaning | Default |
+|-----|---------|---------|
+| `direction` | Iteration direction / feedback constraint (free text) | Code-first research → **auto-lock recommended** |
+| `scale` | `S` \| `M` \| `L` \| `XL` | **`M`** |
+
+**Scale budget**（写入 compass；约束 **业务** plan 数量）→ **`mstar-iteration`** §1.2 + `references/autonomous-direction-lock.md`：
+
+- **S** → 1 business plan
+- **M** → 2–3 business plans
+- **L** → 3–4 business plans（上限 4）
+- **XL** → **>4** business plans（5+；适合大范围 autonomous 迭代）
+
+**HARD**：budget **只计**实际业务交付 plan；**不计** harness 流程（Review 链、QC/QA、compound、close、PR、merge-ready、compass/`status.json` 维护等）。流程门禁仍须执行，但不占 S/M/L/XL 名额，也不得写成独立 process plan 来“凑数/占坑”。
+
+Parse: if the last token is exactly `S`/`M`/`L`/`XL` (case-insensitive), treat it as `scale`; remaining text is `direction`. If only one token and it is `S`/`M`/`L`/`XL`, that is `scale` with empty `direction`.
+
+## Phase flow（禁止跳步）
+
+`Phase 1: Autonomous start → Phase 2: Autonomous Execute → Phase 3: close → Phase 4: PR → Phase 5: merge-ready`。Transition gates（HARD）→ **`mstar-iteration`** **Phase transition gates** table。
+
+## Continuous execution（HARD — Phase 1 lock 后至 Phase 5 exit）
+
+Execute **`mstar-iteration` §2.6**（Continuous execution SSOT）+ **`mstar-iteration/references/command-shared-invariants.md`** STOP list（branch metadata 缺失 / **`Blocked`** / 用户显式打断 — 不在本命令重复）。**Loop 特有 STOP**：branch metadata 按 **`mstar-iteration`** autonomous resolve 顺序仍无法确定（**禁止**静默默认 `main`/`master`）；代码/roadmap **无可信候选**且无 `direction` 参数。**Turn 收束纪律**：最后一条内容必须是 **in-flight 动作**（invoke 已发出或下一 Assignment），**不得**以确认问句结尾。
+
+**Do not** Read `skills/grill-me/SKILL.md` for this command.
+
+## Boot
+
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1–5 + `command-shared-invariants.md` → `mstar-dispatch-gates` → `mstar-phase-gates` → `mstar-conventions` / `mstar-artifacts` → `mstar-host` → `mstar-compound`（Phase 3 前）→ **`mstar-sdd`**（first implement 前）→ `mstar-review-qc`（first QC 前）→ `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
+
+**Session todos（loop 专属；Phase 2–5 共享 rows → `command-shared-invariants.md`）**：
+
+| Todo id | 何时追加 | 何时可勾掉 |
+|---------|----------|------------|
+| `phase-1-autonomous-start` | Boot | compass `locked` + integration committed |
+
+## Phase 1: Autonomous start
+
+Execute **`mstar-iteration` § Phase 1**（**autonomous** direction lock + scale budget + branch resolve SSOT → `references/autonomous-direction-lock.md`）：
+
+### 1–4. Research → Explore → Lock → Write
+
+Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）+ `STRATEGY.md`（if present）→ scope **2–4** candidates → **autonomous** lock（`direction` arg 约束；落盘 rationale + success criteria + non-goals + scale budget；branch resolve — never silent `main`/`master`；**STOP** if no credible candidate and no `direction` arg）→ write compass + plans per §1.3–§1.5（business plan count within scale budget）。
+
+### 5. Review & Edit Chain（HARD GATE）
+
+Execute **`mstar-iteration` §1.6**：`product-manager` → `architect` → `writing-specialist` 顺序 invoke（**禁止** `{KNOWLEDGE_DIR}/` 新增；corpus hygiene）→ PM lock。**Assignment preflight** per **`command-shared-invariants.md`**。
+
+**Pre-commit checklist**（print before §6；all `[x]`）：
+
+- [ ] Autonomous direction lock rationale recorded in compass（**not** grill-me）
+- [ ] Scale budget applied（business plan 按 S/M/L/XL 名额）
+- [ ] compass + plans + `status.json` registered
+- [ ] product-manager / architect / writing-specialist invokes completed（**未**向 `{KNOWLEDGE_DIR}/` 新增）
+- [ ] PM final lock：compass `status: locked` + Prepare gates pass
+- [ ] Branch policy locked：`iteration_base_branch` / `spec_integration_branch` / `target_branch` recorded
+- [ ] **THEN** commit + push `iteration/<iteration-id>`
+
+### 6. Integration Branch
+
+Per **`mstar-iteration` §2.3**（create from `iteration_base_branch`；register branch fields；commit docs；push）。**STOP** if base/target missing。**Immediately** print `## Phase 2: Autonomous Execute` → continue（勾掉 `phase-1-autonomous-start`）。
+
+---
+
+## Phase 2–5: Execute → close → PR → merge-ready
+
+Delegate to **`iteration-drive`**（Phase 2 → §2、Phase 3 → §3 + `references/phase-3-iteration-close.md`、Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`、Phase 5 helper discovery → `phase5-helper-discovery.md`）。**Assignment preflight** per **`command-shared-invariants.md`**。
+
+**Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration` §5.1a**；exit checklist → §5.2（`references/phase-4-5-pr-delivery.md`）。
+
+**Then** report: iteration id, locked direction + scale, plans completed, compound summary, PR link, merge-ready evidence。
+
+PR merge itself may remain manual unless user authorized auto-merge.

package/harness-commands/iteration-start.md

@@ -0,0 +1,122 @@
+---
+name: iteration-start
+description: "Start a new harness iteration — optional direction hint, research, grill-me, compass/plans, Review & Edit chain (long-lived {SPECS_DIR}/ + {ITERATION_DIR}/<id>/ package; compound promotes package at close only), PM lock, integration branch; then auto-continue Phase 2→5 (execute → close → PR → merge-ready) unless `pause` arg given."
+agent: project-manager
+input: "[direction] [pause]"
+---
+
+# Start Iteration
+
+Start a new Morning Star harness iteration. **Phase 1 is not complete until the Review & Edit chain runs via dispatched roles and PM lock — not when compass files are first written.** By default, after Phase 1 lock + integration branch, **auto-continue into Phase 2→5** (execute → close → PR → merge-ready); pass **`pause`** to stop after Phase 1 and resume later with `/iteration-drive`.
+
+## Args
+
+```text
+/iteration-start [direction] [pause]
+```
+
+| Arg | Meaning | Default |
+|-----|---------|---------|
+| `direction` | Iteration direction hint — constrains §2 candidates and seeds §3 grill-me; **not** a lock (start stays interactive) | Research → grill-me converges with user |
+| `pause` | Stop after Phase 1 (lock + integration branch); run `/iteration-drive` later to resume | **Auto-continue** into Phase 2→5 |
+
+**Parse**: if any token is exactly `pause` (case-insensitive), treat as the `pause` flag; the remaining tokens (joined) are the `direction` hint. `/iteration-start pause` = pause with empty direction.
+
+## PM invariants（Phase 1 review-chain — 本命令全程有效）
+
+你是 **`project-manager` 编排者**，不是三专业角色的合并替身。
+
+| 禁止（PM 线程） | 必须（宿主有 Task 时） |
+|-----------------|------------------------|
+| 自己 Edit compass/plans/specs 冒充 product-manager / architect / writing-specialist 的审查编辑 | §5.1 → §5.2 → §5.3 **顺序**各 **1 次 invoke**；上一角色返回后再派发下一角色 |
+| 只写 `## Assignment` 或 checklist 就声称 review chain 完成 | **几条角色 ⇒ 几条 invoke**；零 invoke = `dispatch incomplete`（`mstar-dispatch-gates`） |
+| §5 完成前 commit / 创建 integration 分支 | 5.4 PM lock 在 subagent 返回且磁盘产物已修订之后（`mstar-iteration` §1.6） |
+
+派发细则 → **`mstar-dispatch-gates`**（specialist review-and-edit dispatch）+ **`mstar-host`**（宿主 invoke 能力）。**不得**在 PM 线程加载其他 role reference 代劳。
+
+**Phase 1 完成定义**：compass `status: locked` + 三角色 invoke 已返回 + pre-commit checklist 全 `[x]` — 不是初稿落盘。**Command Done**（§7 auto-continue）= Phase 5 §5.5 exit checklist 全 `[x]`（同 `iteration-drive`）；`pause` 时 = Phase 1 完成。
+
+**Phase 2–5 共享 invariants / preflight / todos / STOP** → **`mstar-iteration/references/command-shared-invariants.md`**（不在本命令重复）。
+
+## Path split（HARD — 路由）
+
+| 宿主上下文 | 走哪条 |
+|------------|--------|
+| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → **§P** — **先**空白 CreatePlan，再 **feedback-driven** 自主改同一份 plan；grill-me **仅**在用户明确结束反馈后、仍有阻塞疑问时；**Build 前不执行** Review 链 / commit / integration 分支 |
+| **其它**（Agent、OpenCode、非 Plan） | §0 Boot → §1–§6（Research → Explore → grill-me → Write → Review → branch） |
+
+**Both paths converge at §6**（integration branch）。Default → §7 auto-continue Phase 2→5；`pause` → command ends at §6。
+
+## 0. Boot
+
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1 + `mstar-phase-gates` + `mstar-dispatch-gates` + `mstar-conventions/artifacts` + `mstar-host` → active host reference）。Cursor Plan mode 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）。完整 load list → **`mstar-roles`**。
+
+**若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
+
+## P. Cursor Plan mode（Phase 1 scaffold → feedback loop → deferred grill → Build）
+
+Execute **`mstar-host/references/cursor-plan-mode-bridge.md`** § **"mstar-iteration Phase 1 in Plan mode"**（Detect / 语义 / Single CreatePlan URI（HARD）/ Research → Early CreatePlan → Feedback loop → Feedback-close deferred grill → Pre-Build / Build 全流程 SSOT）。
+
+Command-unique 补充（bridge 未枚举）：
+
+- **空白脚手架字段**：Direction / Scope / Acceptance Criteria / Non-Goals / Delivery Branch Policy（`iteration_base_branch` / `spec_integration_branch` / `target_branch`）/ Plans / Feedback log / Deferred grill log
+- **Build 才勾的 todos**（顺序）：`harness-init` → `finalize-compass-plans`（同一 CreatePlan 落成 compass + plans + `status.json` 登记 + 索引）→ review-edit-product-manager → review-edit-architect → review-edit-writing-specialist → `pm-lock` → `integration-branch`
+
+## 非 Plan 路径从这里继续 ↓
+
+## 1. Research
+
+Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ glob for planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）；read `STRATEGY.md`（if exists）and `{KNOWLEDGE_DIR}/README.md`（if exists — Active index rows are Research candidates）。Prioritize deferred / incomplete items from prior iterations。
+
+## 2. Explore Directions
+
+Scope **2–4** candidates targeting **product completeness**（default to deferred items from previous iterations；allow substantive refactoring where it accelerates product maturity）。**If `direction` arg given** — narrow candidates to that hint (still scope 2–4 unless explicitly singular)；record the hint in grill-me context。
+
+## 3. Lock Direction — bundled `grill-me`
+
+> **非 Plan 路径**。Cursor Plan mode 用 §P feedback loop + deferred grill（主路径不是 grill）。
+
+**Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md` — **only this command step** references it.
+
+**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。**If `direction` arg given** — seed grill-me with it (still interactive; the hint does **not** skip grill-me)。Confirm delivery branch policy（`iteration_base_branch` / `target_branch`）per **`mstar-iteration` §1.2** — **Do not default to `main`/`master` just because those names exist.**
+
+## 4. Write Compass & Plans
+
+Produce harness artifacts per **`mstar-iteration` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（§1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。
+
+## 5. Review & Edit Chain（HARD GATE — do not commit before this）
+
+Execute **`mstar-iteration` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三 roles；OpenCode plain role id — `mstar-host/references/opencode.md`）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每 role 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
+
+**Assignment preflight**：每次 invoke 前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行（warn-only + `enforcement: hard` fail-fast；bin 缺失静默跳过）。
+
+**Prepare gate (per plan in compass)**:
+
+- [ ] specify / clarify / plan = done on each plan file
+- [ ] `primary_spec` path exists (if declared)
+- [ ] `blocked_by` / sequential deps documented
+
+### iteration-start pre-commit checklist
+
+PM must print this block before §6; all `[ ]` must be `[x]`:
+
+- [ ] direction lock decisions recorded in compass（Plan 路径：Feedback log + deferred grill log；非 Plan：grill-me）
+- [ ] Draft compass + plans + `status.json` registered
+- [ ] product-manager / architect / writing-specialist invokes completed — 编辑 compass / plans / specs / **`<iteration-id>/` package**；**未**向 `{KNOWLEDGE_DIR}/` 新增
+- [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)
+- [ ] Branch policy locked: `iteration_base_branch` / `spec_integration_branch` / `target_branch` recorded in compass / `status.json`
+- [ ] **THEN**: commit + push `iteration/<iteration-id>`
+
+## 6. Integration Branch
+
+Per **`mstar-iteration` §2.3**：create `spec_integration_branch` from `iteration_base_branch`（`git fetch` → `git checkout -b <spec_integration_branch> <iteration_base_branch>`）；register `iteration_base_branch` / `spec_integration_branch` / `target_branch` in compass frontmatter **and** `status.json` metadata；commit docs；push。**STOP** if `iteration_base_branch` / `target_branch` missing — never default `main`/`master`.
+
+---
+
+## 7. Phase 2–5（auto-continue）
+
+**`pause` arg → command ends here**（Phase 1 locked + integration pushed；run `/iteration-drive` later）。**Default（no `pause`）→ auto-continue**：execute **`iteration-drive`**（Phase 2 → **`mstar-iteration` §2**；Phase 3 → §3 + `references/phase-3-iteration-close.md`；Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`；Phase 5 helper discovery → `phase5-helper-discovery.md`）。Shared invariants / preflight / STOP → **`mstar-iteration/references/command-shared-invariants.md`**。
+
+**Done = Phase 5 §5.5 exit checklist 全 `[x]`**（同 `iteration-drive`）。**Then** report: iteration id, direction lock summary, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
+
+PR merge itself may remain manual unless user authorized auto-merge.

package/harness-skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/harness-skills/mstar-artifacts/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mstar-artifacts
+description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and durable review summaries, `{SDD_DIR}/review/` ephemeral QC/QA bundles, `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` indexes, plus `{HARNESS_DIR}/status.json` (v2 root register) / `{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases) and `{PROJECT_DIR}/<id>/residuals.json` (residual register; severity SSOT, open/close lifecycle). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing status/snapshot/register, or mapping QC severity to JSON. Required for `@project-manager` on status, residuals, and InReview/QC waves; `@qc-specialist*` before writing review bundle reports; `@qa-engineer` before closing R# when `QA gate: mandatory`. Verdict rules: leaf → `mstar-roles/references/qc-specialist/report-template.md`; PM → `mstar-review-qc`."
+---
+
+## Load order
+
+**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md), and `mstar-conventions` when path symbols matter.** Git branch / worktree / QC checkout → **`mstar-branch-worktree`**. On conflict, **`mstar-harness-core` wins**.
+
+## Scope (plan directory artifacts)
+
+| Topic | See |
+|-------|-----|
+| Main plan, review bundle naming, durable summaries, QC waves, residual and plan index order | `references/plan-files-and-reports.md` |
+| Plan template (Global Constraints, Interfaces) | `templates/plan.main.md` |
+| knowledge / iterations / specs boundaries and indexes | `references/knowledge-and-designs.md` |
+| `status.json` (v2 root), workflow snapshots, project register, residual severity / lifecycle, engine-check queries | `references/status-and-residuals.md` |
+| Empty-repo `status.json` template | `templates/status.empty.json` (`templates/README.md`) |
+| Tech-debt rollup (read-only) | `mstar status tech-debt [path]` (engine `techDebtRollup`; see `references/status-and-residuals.md`) |
+
+**Out of scope:** branch and QC/QA checkout alignment → **`mstar-branch-worktree`**; leaf QC checklist and verdict → **`mstar-roles/references/qc-specialist/`**; PM QC orchestration → **`mstar-review-qc`**; `{HARNESS_DIR}` discovery and init → **`mstar-conventions`**.
+
+## `status.json`, workflow snapshots, and open residual (summary)
+
+- **`{HARNESS_DIR}/status.json` (v2)**: active-lifecycle register — `{ version: 2, updated_at, workflows[] }`. Each entry points at its snapshot dir (`dir: workflows/<id>`); terminal lifecycles are unregistered after the snapshot write.
+- **`{WORKFLOW_DIR}/<id>/snapshot.json`**: per-lifecycle running state — `plans[]` rows (legacy PlanRow shape verbatim) + per-row `execution_lease` + top-level `integration_merge_lease` / `execution_policy` / `branch` anchors / `control_worktree_path`.
+- **`{PROJECT_DIR}/<id>/residuals.json`**: open residual register, `entries[<plan-id>]` arrays — the **open-list SSOT** (severity enum + lifecycle semantics verbatim; project-less flows use `_default`).
+- **Canonical**: register new findings only in the project register (`projects/<id>/residuals.json`); v1 root `residual_findings` is legacy read-only — migrate via `mstar migrate`, do not dual-write.
+
+> **Engine check (when available):** run `mstar status validate <path>` (or `import { validateStatus } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+- **Fail-loud handoff**: findings must pass `validateResidual` (per entry) / `validateProjectRegister` (register) before registration; snapshots and the v2 root pass `validateWorkflowSnapshot` / `validateStatus` (`mstar status validate`); malformed → reject + rewrite → **`references/status-and-residuals.md`** (“Fail-loud handoff contract”).
+- **Lifecycle**: open → verified close **in place** in the register (`lifecycle` / `closed_at` / `closure_note`); machine **`severity`** enum in reference. v1 `archived/residuals/` + `archive-residuals` are retired.
+
+- **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (the `metadata.findings_cleanup` mirror is deleted); iteration Phase 2 defaults to **`zero-residual`** → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
+
+> **Engine check (when available):** run `mstar status findings-cleanup <plan-id> [--project <id>] [--mode zero-residual|allow-residual]` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the Findings cleanup mode above against the plan's register entries. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+- **`{WORKFLOW_DIR}/<id>/notes.jsonl`**: per-workflow append-only notes ledger (runtime); snapshot plan-row `notes` is the legacy verbatim copy. **Tech-debt rollup**: `mstar status tech-debt <project-dir>` over the project registers — **`references/status-and-residuals.md`**.
+- **Iteration Phase 2 leases** (snapshot: `control_worktree_path`, `plans[].execution_lease`, top-level `integration_merge_lease`): field semantics → **`references/status-and-residuals.md`** (“Iteration execution leases”); Phase 2 execution checklist → **`mstar-iteration`** `references/phase-2-worktree-lease.md`; full protocol prose (single copy) → **`mstar-engine-legacy`** `references/lease-protocol.md`.
+
+> **Engine check (when available):** run `mstar lease verify --workflow <id> [--plan <plan-id>]` or `mstar lease verify-integration --workflow <id>` (or import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook) to validate the iteration leases above on the workflow snapshot (execution_lease / integration_merge_lease). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq` examples → **`references/status-and-residuals.md`**.
+
+**Templates (this skill):** `templates/status.empty.json` — the **v2 shape** (`version: 2`, `updated_at`, `workflows: []`); copy into `{HARNESS_DIR}/` (`templates/README.md`).
+
+## Workflow
+
+产物生命周期主链：主 plan 落盘 `{PLAN_DIR}`（命名见 `references/plan-files-and-reports.md`）→ 实现推进时更新 workflow snapshot（`workflows/<id>/snapshot.json` 的 `plans[]` 行 + 根 `status.json` `workflows[]` 登记）→ 审查波次产出 `{SDD_DIR}/review/` bundle（raw QC/QA reports）+ durable gate summary 回写主 plan / snapshot → 关闭后 residual **in place** close in the project register（`projects/<id>/residuals.json`）。索引（`{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{PLAN_DIR}`）随产物更新。
+
+## Decision Rules
+
+- residual **severity** 是机器字段 SSOT（`references/status-and-residuals.md`）；每条新 finding 只登记 project register（`projects/<id>/residuals.json` → `entries[<plan-id>]`），v1 根级 `residual_findings` 仅 legacy 只读，**禁止**双写。
+- **`Findings cleanup: zero-residual`** 默认（迭代 Phase 2）：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap。
+- 登记前必须过 `validateResidual` / `validateProjectRegister` / `validateStatus`（fail-loud handoff）；malformed → reject + rewrite。
+
+## Evidence
+
+正确结果 = 可复核产物链：`{SDD_DIR}/review/` 审查 bundle 落盘 + 主 plan / workflow snapshot 的 durable gate summary + residual 生命周期（open → verified close **in place** in the register）。拒绝「仅对话声称」。
+
+## References
+
+- `references/plan-files-and-reports.md` — 主 plan / review bundle 命名、QC 波次、durable summaries
+- `references/status-and-residuals.md` — `status.json` (v2), workflow snapshots, project register, residual severity / lifecycle / engine-check queries
+- `references/knowledge-and-designs.md` — knowledge / iterations / specs 边界与索引

package/harness-skills/mstar-artifacts/references/knowledge-and-designs.md

@@ -0,0 +1,110 @@
+# `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 迭代 compass / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
+
+**路径符号（默认）**：`**{KNOWLEDGE_DIR}** = **{HARNESS_DIR}/knowledge/**`；`**{ITERATION_DIR}** = **{HARNESS_DIR}/iterations/**`。完整符号表见 `mstar-conventions` SKILL.md「Harness 与 Plan 目录发现」。
+
+本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
+
+## 与公开文档目录的分工（典型为 `docs/`）
+
+
+| 区域 | 典型内容 | 受众 / 权威 |
+|------|----------|-------------|
+| **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
+| **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
+| **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
+| **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
+| **`{PROJECT_DIR}/<id>/references/`**（可选） | 主题化研究：surveys、epic roadmaps、第三方 notes — **与项目绑定**，非跨迭代 corpora | 项目所有者 / operator；engine 只列文件名，**无 markdown schema** |
+| **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
+
+
+**不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC/QA 原始过程报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{SDD_DIR}/review/`；长期 gate 摘要回写主 plan。
+
+## `{ITERATION_DIR}`（可选·迭代/版本级 package）
+
+- **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.mstar/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列；legacy 项目可继续为 `.agents/iterations/`）。
+- **放什么**：**`<iteration-id>/` package** — `delivery-compass.md`（迭代状态 SSOT）；`guides/`（探索、过程）；`specs/`（迭代级规格草案）；可选 package `README.md`；遗留规划快照。
+- **不放什么**：已锁定的仓库级规范（→ **`{SPECS_DIR}/`**）；已提升的跨迭代实施 SSOT（→ **`{KNOWLEDGE_DIR}/`**，经 compound）；单 plan QC/QA 原始报告（→ `{SDD_DIR}/review/`）。
+- **索引**：`**{ITERATION_DIR}/README.md**` **一行 = 一次迭代**（指向 `<iteration-id>/`）；`<iteration-id>/README.md` 登记 package 内文档（Documents 单表）。
+- **维护**：`@product-manager` / `@architect` 起草 package；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 package 并**提升**至 `{KNOWLEDGE_DIR}/`。
+- **Compass 路径**：canonical `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`（迭代状态 SSOT）；legacy flat `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 仅兼容读。
+
+## `{SPECS_DIR}`（可选·长期规格）
+
+- `{SPECS_DIR}` 解析（非空即停）：`{HARNESS_DIR}/specs/` → `docs/specs/` → 仓库根 `specs/`；皆无或皆空则 init 创建 `{HARNESS_DIR}/specs/`。Legacy 只读：`{HARNESS_DIR}/designs/` 或根 `designs/` 非空时可用。细则 → `mstar-conventions` SKILL.md「`{SPECS_DIR}` 解析」。
+- **放什么**：跨迭代有效、已锁定或待锁定的产品/API 规范、ADR、契约 — **iteration-start 主产出**（product/architect）。
+- **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ package 或 plan 素材，**close 时 compound 提升**）。
+- **索引**：非 trivial 树建议 `{SPECS_DIR}/README.md`；plan **`primary_spec` / `spec_refs`** 主要指向此处。
+
+## `{KNOWLEDGE_DIR}`（可选·实施知识库）
+
+- **新增 SSOT 默认路径**：**iteration-close** 时经 **`mstar-compound`** 写入；**iteration-start §1.6 禁止** product/architect 新增（见 **`mstar-iteration/references/iteration-artifact-boundaries.md`**）。
+- **必须**维护 `**{KNOWLEDGE_DIR}/README.md**` 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
+- 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-conventions` 与本 reference 为准。
+- 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
+
+## `{PROJECT_DIR}/<id>/references/`（可选·主题化研究语料）
+
+- **物理路径**：`**{PROJECT_DIR}/<id>/references/**`（默认 `{HARNESS_DIR}/projects/<id>/references/`；`.mstarc` `project_dir` 声明时用声明值）。
+- **放什么**：**主题化研究** — surveys、epic roadmaps、第三方 notes，与拥有它的项目（`<id>`）绑定（compass ruling 1）。项目缺失用 `_default`（`{PROJECT_DIR}/_default/references/`）。
+- **不放什么**：冻结规格 / ADR（→ `{SPECS_DIR}/`）；compound 结晶的实现 SSOT（→ `{KNOWLEDGE_DIR}/`）；迭代内 ranking notes 与草稿 spec（→ `{ITERATION_DIR}/<id>/guides|specs/`）。研究**不**迁入这三处 corpora，三处内容也**不**迁入 `references/`。
+- **engine 职责边界**：`listProjectReferenceFiles(projectDir)` 只返回**文件名**（相对路径、`/` 分隔、code-unit 排序；跳过根级 `roadmap.md` / `residuals.json`；缺失目录 → `[]`）；**不**读文件正文，**不**做 markdown schema 校验 — 归属语义是本 reference（技能散文）契约，不是 engine 校验。
+- **历史 dump**：harness 根 `.mstar/references/` 已退役（dogfood 后缺省或仅一行 redirect）；当前路径由 `mstar-project-governance` Scope 表与 `mstar-conventions` `references/artifact-storage-paths.md` 命名。
+
+## 文件命名
+
+- 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
+- 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
+- 迭代 compass 放在 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间；**不要**新写根目录 flat `*-delivery-compass.md`。
+
+## 与 `status.json` 的链接
+
+- 某 plan 的**权威设计输入**在规格、迭代 compass 或（已有）知识库中时，在 `**plans[].metadata**` 中登记路径：`**primary_spec**` / `**spec_refs**` → 优先 **`{SPECS_DIR}/`**；`**iteration_compass**` / `**iteration_refs**` → **`{ITERATION_DIR}/`**；已有 **`{KNOWLEDGE_DIR}/`** 链接保留，但 **iteration-start 不得新增** knowledge 路径。
+- 执行方在 **implement 前**：先扫 `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（发现式阅读，不要求通读全库）；再按 metadata 读取已登记路径；均与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
+
+## 维护规则
+
+1. **新增**：
+   - **Specs（长期）**：`{SPECS_DIR}/` → spec 索引（若有）→ `plans[].metadata` 的 `primary_spec` / `spec_refs`
+   - **迭代 package**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md`（目录一行）+ package README → `iteration_refs`
+   - **Knowledge**：**`mstar-compound`** @ iteration-close（含 package **提升**）→ `{KNOWLEDGE_DIR}/README.md`
+2. **阅读**：开发类 agent 在开始编码前，**先扫** `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（不要求通读全库）；随后**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
+3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
+4. **归档**：
+   - **iteration-start（强制）**：`writing-specialist` §1.6 以 **`{SPECS_DIR}/` 全库卫生为主**；对**既有** `{KNOWLEDGE_DIR}/` 仅归档/错放纠正，**不**新增 knowledge。细则 → **`mstar-iteration/references/iteration-corpus-hygiene.md`**。
+   - **其它时机**：当文档内容已完全反映到已合并代码中、且非 iteration-start 扫库时：可将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`；可保留原位或迁入 `archived/knowledge/`。
+5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` package 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
+
+## 与 review bundle、`{PLAN_DIR}/residuals/` 的区分
+
+- `**{SDD_DIR}/review/`**：偏 **审查流程临时证据**（review package、QC1/2/3、consolidated、QA），gitignored，可在 Done 后丢失。
+- `**主 plan gate summary**`：偏 **长期门禁决策摘要**（verdict、review range、R#、QA gate），随主 plan 追踪。
+- `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与 project register `entries[<plan-id>]` 配套，canonical 见 `mstar-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
+- `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
+- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
+- `**{PROJECT_DIR}/<id>/references/**`：偏 **主题化研究**（surveys、epic 备注、第三方 notes），随项目绑定；与 specs / knowledge / iteration guides 职责不混写。
+- review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
+
+---
+
+## `{PLAN_DIR}/residuals/<plan-id>/`（可选·open residual 散文详情）
+
+当某条 open residual 需要**多于** register（`projects/<id>/residuals.json` → `entries[<plan-id>]`）里结构化字段所能承载的叙述时，可在本目录增加 **Markdown 散文**，作为 **SSOT 的补充**（**不替代** JSON；**权威仍以 register 中的 open 条目为准**）。
+
+
+| 与相邻目录的分工                                  | 典型内容                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `**{SDD_DIR}/review/**`       | QC / QA **流程临时证据**（`qc1.md` … `qc-consolidated.md`、`qa.md` 等），gitignored                  |
+| **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
+| `**{KNOWLEDGE_DIR}/**`            | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
+| `**{ITERATION_DIR}/**`            | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
+
+
+**文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 register（`projects/<id>/residuals.json` → `entries[<plan-id>]`，见 `mstar-conventions` **SKILL.md** 开篇）中的 `**id`**（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。
+
+**登记**：在对应 open 条目中填写可选 `**detail_doc`**（仓库内相对路径，常形如 `**{PLAN_DIR}/residuals/<plan-id>/R1-….md**`）。**禁止**只写散文、不在 register 中登记 open 行。
+
+**维护**：`**@project-manager`**（或与 Assignment 一致的可写角色）；`**@qc-specialist***` 宿主白名单通常**不含**本目录——审查结论仍以 Assignment 指定的 `**{SDD_DIR}/review/`** 为准，散文由 PM/实现方据结论整理。
+
+**关闭**：当该条在 register 中 close（`lifecycle` / `closed_at` / `closure_note`）或从 `entries[<plan-id>]` 移除时，应将对应 `**.md**` 一并收口：可迁入 `**{HARNESS_DIR}/archived/knowledge/**`（若视为历史考据）、或团队约定的归档子路径（与 register 变更同批可追溯）；并在关闭条目的 `**closure_evidence` / `closure_note**`（或团队约定字段）中**写明散文最终路径**。勿长期保留「JSON 已关闭而散文仍留在 `residuals/` 且声称仍 open」的状态。