# Mstar Project Governance

> Morning Star 项目治理层约定 —— `projects/<id>/roadmap.md` 编写约定（frontmatter schema + body 约定）与 `projects/<id>/residuals.json` register 生命周期（open → verified close in place、severity 枚举、provenance 字段）、`_default` 项目回退规则。写/审 roadmap、登记或关闭 residual、判断项目归属（含无项目流程的 `_default` fallback）、或对齐 roadmap/register 与 engine 校验时 Read。schema 事实与 `packages/engine/src/project.ts` 逐字一致；字段语义 SSOT → `mstar-artifacts`；路径符号 → `mstar-conventions`。

- Skill: `btspoony/mstar-project-governance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add btspoony/mstar-project-governance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/btspoony/mstar-project-governance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: btspoony (https://skillmd.com/u/btspoony)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/btspoony/mstar-project-governance

---


# mstar-project-governance（项目治理层：roadmap + register）

## Load Order

- 先 Read **`mstar-harness-core`**（SKILL.md；冲突时以 core 为准）。
- 路径符号（`{PROJECT_DIR}` / `{WORKFLOW_DIR}` 解析与 `.mstarc` 声明）→ **`mstar-conventions`**。
- 字段语义 SSOT（severity 含义、findings cleanup modes、close 协议全文、engine-check 查询）→ **`mstar-artifacts`**（`references/status-and-residuals.md`）。本 skill 只承载**编写约定与生命周期规则**，不重复字段全文。

## Scope

项目层 = `{PROJECT_DIR}/<id>/`（默认 `{HARNESS_DIR}/projects/<id>/`；`.mstarc` `project_dir` 声明时用声明值）：

| 文件 | 内容 |
|------|------|
| `roadmap.md` | 项目方向与目标（frontmatter machine-checkable + body 约定） |
| `residuals.json` | 项目 register（`entries[<plan-id>]` 数组）：**迁移历史** —— open item 的 SSOT 是 `{HARNESS_DIR}/store.db` 的 issue（→ § Issue capture）；保留为契约 §7 迁移映射的来源 |
| `references/` | 主题化研究语料（surveys / epic 备注 / 第三方 notes）。与 `{SPECS_DIR}`（冻结规格/ADR）、`{KNOWLEDGE_DIR}`（compound 结晶实现 SSOT）、`{ITERATION_DIR}`（迭代 package）**不同**；engine 只列文件名（`listProjectReferenceFiles`），**不做** markdown schema 校验 |

- **`_default` 回退**：无项目流程（未指定 project id 的 plan / 单 plan / hotfix）落到 **`projects/_default/`**（engine `_DEFAULT_PROJECT`）。项目归属由 plan 的 project id 决定；未归属即 `_default`。
- 本 skill 的 schema 事实与 **`packages/engine/src/project.ts`** 逐字一致（`validateRoadmap` / `validateProjectRegister` / `findingsCleanupGate`）；技能文本是语义 SSOT，engine 是确定性校验。

## Roadmap 编写约定（`projects/<id>/roadmap.md`）

### Frontmatter schema（machine-checkable；engine `validateRoadmap`）

```markdown
---
project_id: <id>
title: <title>
status: active | paused | completed
created_at: YYYY-MM-DD
milestones: [ ... ]        # optional
residuals_ref: residuals.json  # optional
---

# <title>

## Direction
...
```

| 字段 | 必填 | 规则 |
|------|------|------|
| `project_id` | 是 | 非空字符串 |
| `title` | 是 | 非空字符串 |
| `status` | 是 | 枚举 `active | paused | completed`（其他值 = violation） |
| `created_at` | 是 | `YYYY-MM-DD` |
| `milestones` | 否 | 非空字符串列表（空 `milestones:` 视同缺省） |
| `residuals_ref` | 否 | 非空字符串（指向 register 文件，如 `residuals.json`） |

### Body 约定（warnings only —— 永不翻转 `ok`）

- 应有 **`## Direction`** 小节陈述项目方向。
- 目标项以 markdown task-list 列出：`- [ ]` 计划/进行中，`- [x]` 已交付。
- **无 residual→goal 自动链接**（本迭代 Non-Goal）：goal items 不携带 register id；residual 与目标的对齐是人工约定，不是硬门禁。

> **Engine check (when available):** import `validateRoadmap` from `@mstar-harness/engine` in a host hook（无 CLI 命令）校验 `projects/<id>/roadmap.md`。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

## Issue capture（`{HARNESS_DIR}/store.db`）

**本节是 capture duty 的唯一权威**：下方两段是 issue-store contract §6 的规范文本（逐字）；其余 skill（`mstar-artifacts` / `mstar-audit` / `mstar-review-qc` / `mstar-audit/references/pr-review.md` / `mstar-harness-core`）只做指针引用，**不复述**本契约。引文中的 §4 / §7 指该契约的「Lifecycle and closure authority」与「Migration, activation and retirement」两节。

> A confirmed finding becomes an issue in `{HARNESS_DIR}/store.db` at the moment it is confirmed — before, and independently of, any decision to plan it. Capture records **evidence** (source identity, location, observed behaviour, discovery time) and never a disposition; **disposition is a separate authorized act** per §4. A recurrence of a confirmed finding **appends an occurrence** to the existing issue — deduplication is by source identity + root cause, never by title — and never opens a second issue. Issues are plan-independent: they exist before, during and after any plan; only the closure authorities in §4 retire one.

**授权（谁捕获）**

> The seat that owns the confirmed outcome captures it: the PM seat (dispatch/consolidation, QC tri, iteration close) and the main agent of a PR-review round at Stage 3 synthesis. Leaf audit/QC/QA seats **return evidence and never write the store** (survey §7 step 4). Capture goes through the `mstar issue` verbs; flags live in `--help` and are never restated in skill texts.

- 计划内捕获走 `mstar plan issue-add`（活跃 plan session），计划外确认发现走 `mstar issue add`；同一 finding 再次出现用 `mstar issue occurrence` 追加 occurrence —— **不**新开第二个 issue。动词与标志以各命令组 `--help` 为准，本 skill 不复述标志。
- **捕获 ≠ 处置**：关闭是独立授权动作，只由契约 §4 的关闭权威执行（`mstar issue close | waive | duplicate | supersede`，计划内 `mstar plan issue-close`）；捕获席位**不**自授关闭权。
- **激活边界**：store 接受普通捕获/查询、并作为唯一权威，以契约 §7 的 activation 完成为准 —— staged store 会被拒（`store.not-active`）。live 切换（apply → activate → retire）归 cutover plan 的授权 ops 任务，skill 文本不代替该门禁。
- issue 与 plan 解耦（plan 外的确认发现同样可捕获）；store 的路径与权威分界 → **`mstar-conventions`**。

## Register 生命周期（`projects/<id>/residuals.json`）

> **本节的定位**：register 是**迁移历史**，open item 的 SSOT 是 **issue store**（→ 上文 § Issue capture）——`mstar status backlog-register` / `backlog-close` 已退役并指向 issue 动词。下面的字段与生命周期规则保留为契约 §7 的**迁移映射来源**（preview / apply / retire 按此把 register 行映射为 issue）。

### 文档形状、必填字段与枚举（单址 → `mstar-artifacts`）

Register 文档形状（`entries[<plan-id>]` 数组 JSON）、**9 个必填字段**（`id`/`title`/`severity`/`source`/`scope`/`decision`/`owner`/`target`/`tracking`，engine `RESIDUAL_REQUIRED_FIELDS`）与 **severity / decision / lifecycle 枚举**的逐字 schema → **`mstar-artifacts`** `references/status-and-residuals.md`（「Basic structure · project register」+「Residual findings: severity」）。本 skill 只承载编写约定与生命周期规则，**不重复字段全文**。

- `entries[<plan-id>]` 值是**数组** —— v1 `residual_findings[plan-id]` 多 finding 语义逐字保留（一个 plan 可持 2+ open residual）。
- 每条 = v1 residual entry **逐字** + provenance 字段。

### 生命周期：open → verified close（in place）

- **open**：缺省状态；`lifecycle` 缺省/`false`/`null` = `open`。
- **close（唯一关闭路径）**：在 register **in place** 置 `lifecycle`（≠ `open`）+ `closed_at`（`YYYY-MM-DD`）+ `closure_note`；推荐 `closure_evidence`。v1 的 `archived/residuals/` 归档路径与 `status archive-residuals` 已移除（该命令现为报错桩，指向 register 状态变更）。
- **closed 完整性**：`lifecycle` ≠ `open` 时缺 `closed_at` / `closure_note` = violation。
- **谁更新**：捕获在确认后按 § Issue capture 走 issue 动词（计划内 `mstar plan issue-add`，计划外 `mstar issue add`），以 issue id 标识；关闭由契约 §4 的关闭权威执行（`mstar issue close | waive | duplicate | supersede`，计划内 `mstar plan issue-close`）——`QA gate: mandatory` 时 `qa-engineer` 验证后关闭；`pm-acceptance` 时 PM 验收清单完成后关闭。本条的 R# / `lifecycle` 描述只适用于**迁移后的 register 记录**（契约 §7 映射/激活边界），register **不再**是写入目标。
- close 协议全文 → **`mstar-artifacts`** `references/status-and-residuals.md`（「Residual findings lifecycle」）。

### Provenance（register 专属字段）

| 字段 | 规则 |
|------|------|
| `source_plan` | 必填非空字符串；**必须等于其 entries key**（不匹配 = 损坏的 provenance，violation） |
| `registered_at` | 必填 `YYYY-MM-DD` |
| `lifecycle_id` | 可选非空字符串（迭代拥有该 plan 时的 workflow id） |

### Findings cleanup（与 Assignment 联动）

- Assignment **`Findings cleanup: zero-residual | allow-residual`** 是唯一 mode 来源（`metadata.findings_cleanup` mirror 已删）；迭代 Phase 2 默认 `allow-residual`。
- `allow-residual`（默认）：仅 unresolved **critical** 阻止 Approve；离 InReview 前须把每条剩余 open finding 捕获为**本 plan 的 linked open issue**（machine-enum `severity`），并在各决策面披露（issue id + severity + 跟踪位置；close 面另含 blocker-defer 标记）—— 捕获与披露职责全文 → **`mstar-artifacts`**「Findings cleanup modes」。
- `zero-residual`（显式 opt-in）：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap + `target`（`critical` 不属 defer —— 定义 → **`mstar-artifacts`**「Findings cleanup modes」）；`nit` 必须当场修或删；waived/risk-accepted 必须关闭，不得留 open。
- mode 全文与 enforcement → **`mstar-artifacts`** `references/status-and-residuals.md`（「Findings cleanup modes」+ 其 engine check）。

## Workflow

1. 确定项目归属：plan 的 project id（无 → `_default`）。
2. 写/审 roadmap：frontmatter 过 `validateRoadmap`（schema violations 决定 `ok`；body 约定缺失只出 warnings）。
3. 捕获 finding：走 § Issue capture 的 issue 动词（计划内 `mstar plan issue-add`，计划外 `mstar issue add`）；register 是迁移历史，**不再**是写入目标。
4. 关闭：由契约 §4 的关闭权威执行（`mstar issue close | waive | duplicate | supersede`，计划内 `mstar plan issue-close`）。
5. 汇总：`mstar status tech-debt` 打印 store 的 open-issue rollup（`total_open` / `by_severity` / `by_project`）。

## Decision Rules

- **只写 v2 地址**：register 是迁移历史（v1 根级 `residual_findings` 仅 legacy 只读，`mstar migrate` 一次性迁移）；新捕获只写 issue store（→ § Issue capture），**禁止双写**。
- **fail-loud handoff**：捕获前必须过 engine 校验；malformed → reject + rewrite，绝不静默降级写入。
- **severity 是机器字段**：QC 报告的 Critical / Warning / Suggestion 是**章节标题**，不得逐字抄入 JSON `severity`。
- **`_default` 不豁免校验**：无项目流程同样走 issue store（`project_id = _default`），字段与关闭权威不变。

## Evidence

正确结果 = 可复核产物：`projects/<id>/roadmap.md` 过 `validateRoadmap`（0 violations；warnings 可接受）、register 迁移文档过 `validateProjectRegister`、`mstar status findings-cleanup <plan-id>` 按 Assignment mode 绿、`mstar status tech-debt` 输出与 store 的 open issues 一致。拒绝「仅对话声称」。

## References

- **`mstar-artifacts`**（`references/status-and-residuals.md`）— 字段语义 SSOT：severity 含义与门禁关系、findings cleanup modes 全文、close 协议、engine-check 查询示例
- **`mstar-conventions`** — `{PROJECT_DIR}` / `{WORKFLOW_DIR}` 路径符号、`.mstarc` 声明、gitignore 策略
- **`mstar-review-qc`** — PM QC 编排与 findings 捕获 / QC gate（PM 同轮必读）