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 声明时用声明值）：

• _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）

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

# <title>

## Direction
...

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 专属字段）

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 同轮必读）