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。
• Roadmap 正文的唯一权威是 {HARNESS_DIR}/store.db 中按 catalog project id 唯一定位的 project_roadmaps 记录；catalog 存项目身份与路径，不把文件路径或 Markdown 当正文权威。下述 frontmatter 与 body 约定仍由 engine 内容校验，读写/迁移走 roadmap 域边界。

Roadmap 内容权威与编写约定

• 读：先确定 catalog project id（未指定项目的流程使用 _default）；通过 roadmap 域读取该项目的内容、project revision、roadmap revision 与 hash。已知项目无 roadmap 记录是明确的 absence，不从 projects/<id>/roadmap.md、catalog 路径或其他文件静默回退；未知项目是拒绝，不当作空内容。
• Initial import: mstar roadmap import previews an absolute Markdown candidate read-only and saves a review containing provenance source hash and observed project/roadmap revisions. Apply rereads that reviewed path and imports its current valid content without source-byte drift refusal; project/roadmap numeric revision conflicts still refuse. Legacy v1 roadmap.md is a reviewable transport candidate, not an automatically effective seed; scaffold/migration presence does not redirect readers to it.
• 日常修改：先读 store 的当前内容与版本；有记录时用 mstar roadmap export 导出独立 Markdown 候选，无记录时明确创建候选并预期 absent。编辑、复核候选后用 mstar roadmap replace 做整份正文的 revision-guarded replacement（同时校验 project 与 roadmap revision）。冲突重新读权威并复核候选，绝不覆盖 live roadmap.md 代替写入。export 也可输出 JSON transport，供跨环境 handoff；导出文件不随写入自动同步，也不反向成为权威。具体命令选项与 payload → built mstar roadmap --help 及各动词 --help，本 skill 不复写 flags。
• 校验：engine 统一校验 import/replace 的 Markdown 正文；frontmatter project_id（非空且与目标 catalog project 一致）、title（非空）、status（active | paused | completed）、created_at（YYYY-MM-DD）为 machine-checkable；milestones 可选非空字符串列表（空字段按缺省），residuals_ref 可选非空字符串（如迁移 register 文件名）。正文宜有 ## Direction 与目标 task-list（- [ ] / - [x]）；缺少正文约定只报 warnings，不将 ok 翻成 false。目标与 residual 不自动关联；residuals_ref 只是迁移文件引用，不恢复 register 写权威。

projects/<id>/roadmap.md 的旧 frontmatter / milestones 与 body 格式是 import/export/historical Markdown 的表示法，不是文件写作协议，也不是 live milestone 机制（→ 下节）。项目归属和路径解析 → mstar-conventions；ACTIVE 执行态权威在 store.db 的 execution_* 表（可重建 workflow 视图）；snapshot 文件仅为迁移源（由保留的 mstar 迁移工具 engine 内部写入，runtime consumer 不读不写）；open findings → 下文 Issue capture。

Milestone（结构化路线目标）

• 唯一机制：项目路线的结构化目标是 {HARNESS_DIR}/store.db 的 project_milestones 记录 + issues.milestone_id 关联。mstar milestone add | update 写元数据（name / target / ordinal / status，CAS 于 store revision）；mstar milestone assign 是 issue assignment 的唯一写入面（同项目约束，explicit move / clear，走 issue 的特权 mutation 校验，不落 roadmap 的宽松 authoring 面）；issue 自身的项目不对时，先用 mstar issue move 把它移到目标项目（重算 project-scoped identity；项目变更会清除 milestone 关联——issues_milestone_project_update 不允许保留异项目 milestone——被清除的 milestone id 记在 move 收据的 clearedMilestoneId 上）再 assign——两侧必须同项目；list | status 只读并给出 open / resolved / other-retired rollup。动词与标志以 mstar milestone --help 为准，本 skill 不复写。
• roadmap 语句引用 milestone：Direction 与后续路线写 milestone ID + 关联 issue 的 acceptance / owner / dependency / trigger 证据；不用 roadmap.md stub 的 checkbox / frontmatter 名称表达目标状态。Direction 正文（project_roadmaps.content_markdown）与 milestone 是同一 read envelope 的两个组成，互不取代；已知项目无 roadmap 记录仍是明确 absence，milestone 数据不依赖 Markdown 正文存在。
• 交付判定：delivered 的必要条件是至少一个关联 issue 且零 open（同事务校验）；交付只经显式状态变更，从不自动触发，也从不关闭 issue。retired（waived / duplicate / superseded）≠ resolved，rollup 分列展示，不把退役计成已完成工作。
• export / dashboard 是 reporting transport：mstar roadmap export（JSON v2 / 分组 Markdown）与 dashboard 由同一 envelope 组合 Direction 与 milestones；import | replace | show 只改 Markdown 内容权威，从不修改 milestone 记录。

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。所有 mstar issue 写动词（包括 link）均为 actor-only store write（--actor + --operation-id）；每个写入都要求 payload（--payload 或 --file），而 triage、终态处置和 link 的 row-CAS 均要求 --expect（缺失时 issue.revision-conflict）；具体选项以各命令组 --help 为准。
• 捕获 ≠ 处置：关闭是独立授权动作，只由契约 §4 的关闭权威执行（mstar issue close | waive | duplicate | supersede，计划内 mstar plan issue-close）；捕获席位不自授关闭权。mstar issue link 的 plan/iteration target 作为来源标签记录，不做目标存在性校验。
• 激活边界：store 接受普通捕获/查询、并作为唯一权威，以契约 §7 的 activation 完成为准 —— staged store 会被拒（store.not-active）。live 切换（apply → activate → retire）归 cutover plan 的授权 ops 任务，skill 文本不代替该门禁。
• issue 与 plan 解耦（plan 外的确认发现同样可捕获）；store 的路径与权威分界 → mstar-conventions。

Payload authoring: consult mstar-harness schema CaptureInput for issue add, OccurrenceInput for recurrence, IssueTriage for triage, ClosureEvidence for each terminal disposition, and IssueLink for provenance/relation links. The schema lists required and disposition-specific fields; the verb's help supplies flags. Prepare complete JSON from observed evidence before writing, never guess a minimal payload through successive refusal messages. The actor and intended operation are not derivable from the payload and remain explicit.

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）。

Historical register fields and closure

Register shape, required fields/enums, provenance and historical in-place closure → mstar-engine-legacy references/migration-source-shapes.md; this is a migration mapping, never a live writer.

Live capture and closure use § Issue capture and the contract §4 closure authority; QA gate: mandatory requires QA verification, otherwise PM acceptance. Current severity, cleanup and issue closure → mstar-artifacts references/status-and-residuals.md.

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. 确定 catalog 项目归属（无项目 → _default）；从 roadmap 域读现有内容与版本，absence 不走文件 fallback。
2. 首次文件导入走 preview → review → apply；后续编辑走独立候选 → revision-guarded replace；文件只作为 transport。校验 frontmatter 及 body warnings 按上文。
3. 路线目标：结构化目标建 milestone 并显式关联 issue（§ Milestone）；roadmap 语句引用 milestone ID + 关联 issue 证据，不用文件 stub 表达状态。
4. 捕获 finding：走 § Issue capture 的 issue 动词（计划内 mstar plan issue-add，计划外 mstar issue add）；register 是迁移历史，不再是写入目标。
5. 关闭：由契约 §4 的关闭权威执行（mstar issue close | waive | duplicate | supersede，计划内 mstar plan issue-close）。
6. 汇总：mstar status tech-debt 打印 store 的 open-issue rollup（total_open / by_severity / by_project）。

Decision Rules

• Issue store only: new captures write issues (→ § Issue capture); historical registers remain read-only and must never be dual-written. Migration field history → mstar-engine-legacy references/migration-source-shapes.md.
• fail-loud handoff：捕获前必须过 engine 校验；malformed → reject + rewrite，绝不静默降级写入。
• severity 是机器字段：QC 报告的 Critical / Warning / Suggestion 是章节标题，不得逐字抄入 JSON severity。
• _default 不豁免校验：无项目流程同样走 issue store（project_id = _default），字段与关闭权威不变。

Evidence

正确结果 = roadmap 域读取当前内容或明确 absence；reviewed import / replacement 返回新 revision 与 hash（冲突拒绝，无 live 文件覆盖）；milestone 写入返回 receipt（同请求 replay 幂等、冲突/stale 拒绝且无变更），mstar milestone list | status 的 rollup 与 store 一致；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-engine-legacy references/migration-source-shapes.md — historical register shape, required fields/enums, provenance and closure mapping; no execution route or live writer
• mstar-conventions — {PROJECT_DIR} / {WORKFLOW_DIR} 路径符号、.mstarc 声明、gitignore 策略
• mstar-review-qc — PM QC 编排与 findings 捕获 / QC gate（PM 同轮必读）