# Iteration Compass Template

Copy this template when creating `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`.

```markdown
---
iteration_id: <id>
start_date: YYYY-MM-DD
status: active
iteration_base_branch: <branch-or-ref>
target_branch: <branch>
pr_merge_policy: <reviewed-auto | owner-gated>
plans: []
---

# <iteration-id> Delivery Compass

## Scope

本迭代锁定的 spec 点：

- <spec point 1>
- <spec point 2>

## Decisions

> Settled direction-lock items — the record a dispatched role reads instead of re-deriving context from a conversation it never saw.

| # | Decision | Rationale | Source |
|---|----------|-----------|--------|
| D1 | <settled decision> | <why it was settled this way> | user instruction / grill-me / autonomous ranking |

Record product-manager and architect **include/omit rationale** here: complexity, remaining gaps, and prototype contributions reused. Selection/lock obligations → `phase-1-prepare.md` §1.6; writing-specialist is always the final editing round.

## Open Questions

> Unresolved items owned by PM or a **selected** Phase 1 editing role; do not create questions for an omitted specialist. Row disposition before §1.6 lock → `phase-1-prepare.md` §1.3. Write `None` instead of a table when none remain.

| # | Question | Owner | Blocking? |
|---|----------|-------|-----------|
| Q1 | <open question> | product-manager / architect / writing-specialist / PM | Yes / No |

## Prototype baseline

> Filled only after the §1.2.5 checkpoint. Design context, not a frozen spec or runnable acceptance evidence.

- Retained prototype: <package-relative `prototypes/` path and revision>
- Disposition: <explicit user confirmation of this revision, or autonomous disposition with rationale; link the retained evidence>
- Feedback/decisions and contributor inputs: <retained record or summary>
- Formal compass/plans/specs reflect this baseline; material design changes reopen §1.2.5 before authoring/lock continues.

## Plans

| plan_id | Name | Status | Notes |
|---------|------|--------|-------|
| <plan-id-1> | <plan name> | Todo | |
| <plan-id-2> | <plan name> | Todo | |

Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`

## Milestones

This table tracks **iteration delivery nodes**, not store `project_milestones` records. Project milestone reads/writes follow **`mstar-project-governance`**; neither mechanism substitutes for the other.

| Milestone | Target date | Status |
|-----------|-------------|--------|
| Spec freeze | YYYY-MM-DD | pending |
| Dev complete | YYYY-MM-DD | pending |
| QC complete | YYYY-MM-DD | pending |
| Iteration close | YYYY-MM-DD | pending |

## Acceptance Criteria

- <迭代级验收项 1>
- <迭代级验收项 2>

## Non-Goals

- <明确排除项 1> — <排除理由>
- <明确排除项 2> — <排除理由>

## Roadmap Position

- **Current iteration（<iteration-id>）**：<what this iteration delivers>
- **Next iteration**：<what comes next>，触发条件：<condition>，owner：<who>
- **最终目标**：<the long-term Done definition this iteration contributes to>

## Delivery Branch Policy

> Mirror of frontmatter; keep in sync with the ACTIVE workflow branch anchors (store execution authority).

| Field | Value |
|-------|-------|
| `iteration_base_branch` | <branch-or-ref integration branch is cut from> |
| `spec_integration_branch` | <e.g. iteration/<iteration-id>> |
| `target_branch` | <PR target after iteration-close> |

## Risk Register

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| <risk> | Low/Med/High | Low/Med/High | <mitigation> |

## Iteration package

> Sibling paths under `{ITERATION_DIR}/<iteration-id>/`, not `{SPECS_DIR}/` or `{KNOWLEDGE_DIR}/`. Prototypes remain iteration design history; eligible formal material is considered at iteration-close under the existing promotion rules.

| Path | Purpose |
|------|---------|
| `prototypes/` | Retained design preview/revisions, feedback and confirmation or autonomous disposition; mandatory checkpoint input |
| `guides/` | Exploration, process notes |
| `specs/` | Iteration-scoped spec drafts |
| `README.md` | Optional package prose/links; document registration belongs to catalog |

## Quality Gate Summary

> Filled at iteration-close. Human summary only; per-plan gate details stay in each main plan. Open findings SSOT is the plan-linked open issues in `{HARNESS_DIR}/store.db`.

| plan_id | QC decision | QA gate | Residuals | Durable summary |
|---------|-------------|---------|-----------|-----------------|
| <plan-id-1> | Approve / Approve with residuals / Request Changes / N/A | mandatory / pm-acceptance / report-only / N/A | none / R1,R2 / accepted | `{PLAN_DIR}/<plan>.md#review-gate-summary` |

Notes:

- Raw review bundle: `{SDD_DIR}/review/` (ephemeral; do not rely on it after Done).
- Open findings: store issue IDs + issue severity + tracking location; gate via `mstar status findings-cleanup <plan-id>`. Project `residuals.json` is migration history, never a live register.

## Compound Round Summary

> Filled at iteration-close.

- 结晶文档数：<N>
- 新增 CONCEPTS.md 条目：<N>
- 触发 compound-refresh：<是/否>

## Iteration Retrospective (minimal)

> Filled at iteration-close.

- 做得好的：
- 可改进的：
- 下迭代建议：
```

## Fields guide

| Field | Required | When to fill |
|-------|----------|-------------|
| `iteration_id` | Yes | Phase 1 |
| `start_date` | Yes | Phase 1 |
| `end_date` | No | Phase 3 §3.4 only |
| `status` | Yes | Phase 1 → `active` / `locked`（§1.6 PM lock）；Phase 3 §3.4 → **`completed`**（YAML frontmatter，非 prose completion status） |
| `iteration_base_branch` | Yes | Phase 1; integration branch must be created from this ref |
| `target_branch` | Yes | Phase 1; final PR target after Phase 3 |
| `pr_merge_policy` | Yes | Phase 1 at direction lock: exactly `reviewed-auto` or `owner-gated`, confirmed with the user and never defaulted. Phase 5 dispatches its review path on it; Phase 6 requires the merge authorization it names (`phase-4-5-pr-delivery.md` §5.3). |
| `plans` (frontmatter) | Recommended | Phase 1 (initial), Phase 2 (add new) |
| `## Plans` table | Yes | Phase 2 (sync status), Phase 3 (final) |
| `## Milestones` | Recommended | Phase 1, Phase 2 (update) |
| `## Acceptance Criteria` | Yes | Phase 1 |
| `## Non-Goals` | Yes | Phase 1; each entry carries its rationale |
| `## Decisions` | Yes | Phase 1 draft (appended in Phase 2); settled items with rationale and source |
| `## Open Questions` | Yes (`None` allowed) | Phase 1 draft; owners must be PM or selected editing roles; row disposition before lock → `phase-1-prepare.md` §1.3 |
| `## Roadmap Position` | **Yes** | Phase 1（必填节，非散落于 general context prose）；Phase 3 §3.3（current iteration → `delivered`） |
| `## Risk Register` | Optional | Phase 1, Phase 2 (update) |
| `## Prototype baseline` | Yes | Phase 1 §1.3, from §1.2.5; retained path/revision and truthful confirmation/autonomous disposition |
| Iteration package (`prototypes/`, optional `guides/` / `specs/`) | Yes (prototype) | Prototype before formal authoring; README is optional prose, not a required index |
| `## Quality Gate Summary` | Yes | Phase 3 §3.4 |
| `## Compound Round Summary` | Yes | Phase 3 §3.4 |
| `## Iteration Retrospective` | Recommended | Phase 3 §3.4 |

## Legacy compass drift

若仓库中已有 compass **无** YAML frontmatter、**无** `## Roadmap Position`，或只有 prose completion status：

- **新迭代**：Phase 1 必须按本模板写入 **`{ITERATION_DIR}/<iteration-id>/delivery-compass.md`**，不延续 prose-only 或根目录 flat 文件惯例。
- **收口时**：`mstar-iteration` §3.0.5 在 Phase 3 入口规范化，再执行 §3.3–§3.4。
- **Legacy path**：若仍存在 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`，读时兼容；本轮若改写该迭代，迁入 `<iteration-id>/delivery-compass.md`。