Mstar Conventions

Load order（必读顺序）

首次 Read 本 skill 前：必须先 Read mstar-harness-core（SKILL.md）。 本 skill 只约定 目录与路径；不突破状态机与门禁。冲突时 以 mstar-harness-core 为准。

Workflow

主链：按「路径符号」+「{HARNESS_DIR} 解析顺序」确定目录（默认 .mstar/，兼容 .agents/）→ 按「初始化 Plan 目录」建 plans/ / status.json 并追加 gitignore 进程产物集（进程本地、结果共享）→ 多 Plan · 同一 Spec 时按「Spec 驱动的分支模型」登记 iteration base / spec 集成分支 / 各 Plan 实现分支 / PR target → 主 plan 写入 {PLAN_DIR}（Plan-Writing Path Gate，不引入外部默认 plan 目录）。未启用 plan 时 → 对话追踪，门禁（QC/QA）照常。

路径符号（SSOT）

Engine check (when available): import resolveHarnessDir / resolvePlanDir / resolveSddDir / resolveIterationDir / resolveKnowledgeDir / resolveSpecsDir / resolveWorkflowDir / resolveProjectDir from @mstar-harness/engine in a host hook — or run mstar path resolve [path] (--json for machine output) to print the resolved dirs — to confirm the resolution below. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

{HARNESS_DIR} 解析顺序（找到即停；探测永不越过工作区根——CLI=start 的 git top-level（非 git→start 自身）；dsh=会话工作区）

1. 显式 override：opts.harnessDir / MSTAR_HARNESS_DIR（全权优先，短路一切探测与配置文件）
2. 否则 .mstarc [config] harness_dir=<dir>（仓库本地声明，见下「.mstarc 格式」；find-first-stop 向上找最近文件，不越过工作区根）
3. 否则 .mstar/ → {HARNESS_DIR}=.mstar/, {PLAN_DIR}=.mstar/plans/
4. 否则 .agents/ → legacy {HARNESS_DIR}=.agents/, {PLAN_DIR}=.agents/plans/
5. 否则 .plans/ 或 plans/ → 遗留同目录 {HARNESS_DIR}={PLAN_DIR}
6. 皆无 → 未启用 plan；进度走对话与 Completion Report

并存时 .mstar/ 优先；仅当项目已有 .agents/ 且无 .mstar/ 时继续沿用 .agents/。

.mstarc 格式（INI 子集；默认 gitignored，见下「Git 跟踪策略」）

[config]
harness_dir=.custom_dir
plan_dir=planning
sdd_dir=process/sdd
iteration_dir=process/iterations
knowledge_dir=knowledge
specs_dir=specs/custom
workflow_dir=process/workflows
project_dir=process/projects
enforcement=hard

• # / ; 注释；[section] 头；key=value（去空白）。仅读 [config] 段，未知键忽略（向前兼容）。
• 目录键：harness_dir（{HARNESS_DIR}）、plan_dir（{PLAN_DIR}）、sdd_dir（{SDD_DIR} 的 per-plan 基目录，<plan-id> 仍会追加）、iteration_dir（{ITERATION_DIR}）、knowledge_dir（{KNOWLEDGE_DIR}）、specs_dir（{SPECS_DIR}，权威——声明后不再走候选链）、workflow_dir（{WORKFLOW_DIR}）、project_dir（{PROJECT_DIR}）。全部相对 .mstarc 所在目录解析（绝对路径亦可）；无需目录已存在（可后续 scaffold；v3 的 workflows/ / projects/ 子目录由 engine writers 按需创建）。
• enforcement=hard|soft：仓库级硬门禁策略（hard 硬门禁、soft 本地回滚；其他值忽略）。优先级：显式 Config > Assignment Enforcement: hard 头标记（仅派发闸门）> .mstarc > 迭代 compass frontmatter > 默认 warn-only。.mstarc soft 可回滚 hard compass；.mstarc hard 硬化无标记的派发与各闸门。
• 子目录键与 enforcement 由 engine resolvePlanDir / resolveSddDir / resolveIterationDir / resolveKnowledgeDir / resolveSpecsDir / resolveWorkflowDir / resolveProjectDir / resolveRepoEnforcement 读取：从 harness 目录与其父目录（仓库根，.mstarc 的文档化位置）向上找最近配置文件。
• 优先级：显式 override > .mstarc > 探测。非默认布局的仓库写一个 .mstarc 即可程序化解目录问题，无需逐宿主设置 env / config。

无 engine 时的手工解析（runtime 缺席，技能文本为权威）：

1. 从当前目录向上找最近的 .mstarc（find-first-stop），不越过工作区根（CLI=git top-level，非 git=start 自身；dsh=会话工作区）。
2. 读 [config] 段：key=value（去空白），#/; 注释与空行忽略；同一键最后一次出现生效。
3. harness_dir 存在 → 相对该 .mstarc 所在目录解析（绝对路径直接用），即 {HARNESS_DIR}；无需目录已存在。
4. 其余键（plan_dir / sdd_dir / iteration_dir / knowledge_dir / specs_dir / workflow_dir / project_dir）从 {HARNESS_DIR} 或其父目录（仓库根）向上找最近 .mstarc 读取；值同样相对配置文件目录解析；specs_dir 声明后直接采用（跳过「{SPECS_DIR} 解析」候选链与空目录规则），sdd_dir 只替换基目录（<plan-id> 仍追加），workflow_dir / project_dir 直接替换默认子目录名。
5. 未声明的键回落默认组合：{HARNESS_DIR}/plans/、{HARNESS_DIR}/sdd/<plan-id>/、{HARNESS_DIR}/iterations/、{HARNESS_DIR}/knowledge/、{HARNESS_DIR}/workflows/、{HARNESS_DIR}/projects/、{SPECS_DIR} 候选链。

{SPECS_DIR} 解析（找到非空目录即停）

1. {HARNESS_DIR}/specs/（默认 .mstar/specs/）
2. docs/specs/
3. specs/（仓库根）

空目录规则：候选路径存在但无任何文件 → 视为不存在，继续下一候选。

创建默认：全部缺失或皆空 → 创建并使用 {HARNESS_DIR}/specs/（统一落在 .mstar/ 下）。禁止在 greenfield init 时优先创建裸仓库根 specs/。

Legacy 兼容读：若以上皆无内容，但 {HARNESS_DIR}/designs/ 或仓库根 designs/ 非空，可作 {SPECS_DIR} 使用；init 时不新建 designs/。

Engine check (when available): import resolveSpecsDir from @mstar-harness/engine in a host hook — or run mstar path resolve (prints the resolved specs dir) — to confirm the candidate order (empty-dir-as-absent included). On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

可选项目选择：部分 spoke 仓库另跟踪 {HARNESS_DIR}/roadmap.md — 非默认 tracked；仅在项目 opt-in 时提及。

内容边界（摘要）

单 plan 的 QC/QA 原始过程报告默认进入 {SDD_DIR}/review/（gitignored review bundle），非 docs/，也不默认进入 {PLAN_DIR}。主 plan 仅保留 durable gate summary；R# open 状态以 {PROJECT_DIR}/<id>/residuals.json 为 SSOT（根 status.json v2 仅 workflows 注册表）。细则 → mstar-artifacts。

Issue/catalog store 路径与权威分界

Issue 身份、证据、影响、处置、occurrences、关系与 provenance，以及 project/iteration/plan/document catalog 身份与关系，权威在 {HARNESS_DIR}/store.db（激活后）。执行路由、lease、session 凭证与冻结执行输入仍是根 status.json / workflow snapshot 等 JSON（ArtifactStore / 默认 FsStore）——不是 SQLite，也不把 ArtifactStore 改成通用 SQLite 后端。

Catalog 字段权威（contract §1）

store.db 是进程本地（默认 gitignored），执行路由/lease/session 与冻结输入不进 SQLite。激活前 legacy 索引仍是权威；store 未初始化/未激活时 catalog 查询拒绝（store.not-initialized / store.not-active），不读作「空 catalog」；切换由 cutover plan 的 activation 负责。

Markdown 索引退役（contract §4）

{ITERATION_DIR}/README.md 的迭代行、<iteration-id>/README.md 的 Documents 表、{SPECS_DIR}/README.md / {KNOWLEDGE_DIR}/README.md 的登记表与 {PLAN_DIR} 目录索引不再是有待维护的登记面：README 与其它正文一样是散文（可留作导览），但没有任何「必须新增/维护一行」的义务；「某文档是否已登记、属于谁、什么类型、什么生命周期」一律查 catalog。

职责：discover / import / register / query

• discover — mstar catalog discover 只读提案：配置根的 tracked 正文 + legacy 索引行的 dry-run，写出 nothing，带 reviewed source hash、显式 unknowns 与拟退役索引节。
• import — mstar catalog import 应用已 review 的 mapping；冲突或 reviewed source 漂移整单拒绝；不创建 workflow session、不退役索引。
• register / update / link — 单行登记与元数据/关系变更走 catalog 域边界（mstar catalog register / mstar catalog update / mstar catalog link；identity 不可改，revision 守卫与可改字段见 help）。
• query — mstar catalog list / mstar catalog show。
• reconcile — 执行注册中断的收口（pending 状态 catalog.registration-pending，contract §3；只读列出见 help）。
• export — mstar catalog export 是版本化 transport，不是持续维护的文件权威（回灌用 mstar catalog import）。

动词、选项与标志一律以 mstar catalog --help（group help）为准，本文不复述；族名索引 → mstar-use-cli。

跨 clone 限制（contract §4）

store.db 是本地/进程产物，仅凭 tracked 正文无法重建本地 catalog 历史。catalog discover 枚举配置根的 tracked 正文并提取当前 title/path/content hash 与显式元数据作为候选证据，从不假设文件名编码 project/iteration 归属、归档状态、执行状态或 provenance——未声明的一律以显式 unknowns（identity / membership / document-kind / source-missing …）披露，需人工 review 后 import。新 clone 因此可以不依赖维护中的 Markdown 索引发现 tracked specs/knowledge；完整 catalog 恢复需要显式 catalog export + reviewed import。

Store 落在 control / process harness 根，不随 feature worktree cwd。Help / 普通 validator / engine import 不打开 SQLite。本 skill 只声明路径与权威分界；动词与标志以 mstar issue --help / mstar catalog --help 为准（mstar-use-cli 索引族名）。文档本身不证明打包兼容或激活就绪。

初始化 Plan 目录

PM 在需要持久化追踪时：

1. 建 .mstar/、plans/、status.json（v2 空模板见 mstar-artifacts/templates/status.empty.json：version: 2 + workflows: []）
2. 可选 knowledge/、iterations/、{HARNESS_DIR}/specs/、sdd/（空目录占位；运行时 per-plan 子目录由 mstar-sdd → mstar sdd workspace <plan-id> 创建；workflows/ 由 engine writers 按需创建，不预建）
3. 项目根 .gitignore 追加 Morning Star 进程产物忽略集（见下文「Git 跟踪策略」）— CLI init 可自动添加
4. Git：进程本地、结果共享 — 默认跟踪 {HARNESS_DIR}/AGENTS.md、{KNOWLEDGE_DIR}/**、{SPECS_DIR}/**；plans/、iterations/、status.json 等为本地会话 SSOT，默认 gitignored。跨 clone 持久 handoff = knowledge + specs + {HARNESS_DIR}/AGENTS.md（及根 CONCEPTS.md / STRATEGY.md 若使用）；须跨 clone 的 residual 须提升（compound）或写入 tracked results — 勿默认 git add status.json / plans/。

程序化初始化：scaffoldHarness（engine）与 mstar harness scaffold [path]（CLI）一次性完成上述 bootstrap —— 目录 + v2 status.json + projects/_default/ 预建（roadmap.md + 空 residuals.json）+ canonical gitignore snippet + 最小 {HARNESS_DIR}/AGENTS.md；幂等，重跑只补缺失件。 scaffold 遵循 .mstarc：harness_dir / project_dir 声明优先（写入解析后的目录）；解析出的 harness 目录名非 .mstar 时跳过 canonical gitignore snippet（自定义 harness 布局自行管理 ignore 规则）。

步骤与 {HARNESS_DIR}/AGENTS.md 分层 → references/harness-bootstrap-and-agents-layering.md。

Git 跟踪策略（进程 vs 结果）

原则：进程留在本地；结果与团队共享。

默认 tracked（{HARNESS_DIR} 下）：

• {HARNESS_DIR}/AGENTS.md
• {KNOWLEDGE_DIR}/**
• {HARNESS_DIR}/specs/（即解析后的 {SPECS_DIR} 在 harness 下的默认落点）

默认 gitignored（{HARNESS_DIR} 下）：

• archived/
• iterations/
• plans/
• sdd/
• status.json
• workflows/（v3 每 lifecycle 运行态：<id>/snapshot.json + <id>/notes.jsonl）
• projects/（v3 项目层：<id>/roadmap.md + <id>/residuals.json）
• store.db（issue/catalog SQLite；与 status.json 同属进程产物，默认随 {HARNESS_DIR} 忽略）

Legacy .agents/ 项目：将上表路径前缀 .mstar/ 换为 .agents/。

v3 运行时目录的 gitignore 说明（文档化；canonical snippet 零改动）：workflows/ 与 projects/ 都位于已被 .mstar/** 默认忽略的 {HARNESS_DIR} 之下——不需要在仓库根 .gitignore 增加任何条目，也不新增 re-include 条目（它们不是 tracked 结果）。projects/_default/ 由 scaffoldHarness / mstar harness scaffold 预建（roadmap.md + 空 residuals.json）；其余 project id 与 workflows/ 子目录由 engine writers 按需创建（writeWorkflowSnapshot / registerWorkflow / project-register 写入路径），不是 scaffoldHarness 的初始化产物。

多 worktree（iteration L1）：默认 gitignored 的进程产物不会随 git worktree add 进入新检出。进程 SSOT 固定在 control root = 主 checkout（main worktree），读写经 control 绝对路径（<main-repo-root>/{HARNESS_DIR}/…）；integration 分支检出在专属 integration worktree（snapshot integration_worktree_path，唯一 merge cwd）；产品代码改在 feature worktree。Gitignore 策略注：tracked-results 层（{KNOWLEDGE_DIR} / {SPECS_DIR} / {HARNESS_DIR}/AGENTS.md）随 Git 分支走，在采纳 canonical gitignore snippet 的仓库中对所有 worktree 可见——本仓库 .mstar/ 全量 gitignore 属仓库自身 ignore 规则的属性，非契约。三写域模型（process SSOT / tracked results / product source）的 SSOT 表 → mstar-branch-worktree「Harness path SSOT under default gitignore」；反模式（禁止因 feature 缺 plans 而 Worktree mode: waived）同见该表。

Canonical .gitignore snippet（skills 与 CLI init 对齐）：

# Morning Star harness (.mstar/)
# Principle: process stays local; results are shared with the team.
# Default-ignore everything under .mstar/, then re-include the tracked results.
.mstar/**
!.mstar/AGENTS.md
!.mstar/knowledge/
!.mstar/knowledge/**
!.mstar/specs/
!.mstar/specs/**
# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
.mstarc

Legacy .agents/ 等价：

# Morning Star harness (.agents/) — legacy
# Default-ignore everything under .agents/, then re-include the tracked results.
.agents/**
!.agents/AGENTS.md
!.agents/knowledge/
!.agents/knowledge/**
!.agents/specs/
!.agents/specs/**

Engine check (when available): import emitGitignoreSnippet / validateGitignore from @mstar-harness/engine in a host hook to emit or validate the canonical snippet above. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

Spec 驱动的分支模型（多 Plan · 同一 Spec）

• Iteration base branch：创建 Spec/iteration 集成分支的祖先分支或 ref；必须显式记录，不能默认 main / master。branch.base 是创建/merge 锚点，不是主 worktree 驻留事实——主 worktree（control root）的驻留分支在生命周期写入前由 PM 记录为 Main worktree branch（主 plan 头），全程不切换。
• Spec 集成分支：从 iteration_base_branch 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
• Plan 实现分支：每 plan_id 一条（PM 书面）。
• PR target：全部 Plans 与 iteration-close 完成后，向显式 target_branch 提 PR（窄例外见 Assignment Branch policy）。
• Standalone development plan：单 plan 交付不经迭代集成序列——交付分支上完成 compound disposition 后向显式 target 提交 PR，PR 身份（repo/head/target）在提交时记录；序列与语义 → mstar-artifacts/references/plan-workflow-lifecycle-contract.md（迭代序列不变，见上）。
• Git 操作与 QC 单一 HEAD → mstar-branch-worktree。
• workflow snapshot 登记顶层 branch.base（iteration_base_branch）/ branch.target（target_branch）/ branch.integration（spec_integration_branch），以及 plan 行 metadata.spec_integration_branch / merge_target → mstar-artifacts。

解析顺序（mstar-iteration §2.3）：workflow snapshot branch anchors → compass frontmatter → 向用户确认。禁止因仓库默认分支名为 main/master 就自动采用。

Plan-Writing Path Gate

Plans are written to {PLAN_DIR} when persistent plan tracking is enabled. Do not introduce external default plan directories.

Engine check (when available): import assertPlanWritingPath from @mstar-harness/engine in a host hook to enforce the gate above. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

状态与权限（摘要）

Todo | InProgress | InReview | Blocked | Done — Done 仅 PM 或 QA。字段与 residual → mstar-artifacts。主 plan checkbox → mstar-artifacts。

未启用 Plan 时

无 plan 目录：PM 用对话追踪；门禁（QC/QA）仍适用；复杂度上升时可建议初始化。

实现角色最小阅读

仅需路径符号与 plans[].metadata 的 primary_spec / spec_refs 时：读本 SKILL 至「路径符号」+ mstar-artifacts/references/knowledge-and-designs.md 即可，不必通读 status/residual 全文。

Evidence

正确结果 = 落盘产物可复核：{WORKFLOW_DIR}/<id>/snapshot.json 含对应 plan 行（状态 + metadata 分支字段；根 status.json v2 仅 workflows 注册表，无 plan 行），plan 文件存在于 {PLAN_DIR}，{HARNESS_DIR}/AGENTS.md 分层与 gitignore 与本文约定一致（进程本地 / 结果共享），mstar path resolve 输出与路径符号表一致，tracked 正文的 catalog 行（mstar catalog show / mstar catalog list）与其实际位置一致（store 激活后）。

References

• references/harness-bootstrap-and-agents-layering.md — 新仓 harness + AGENTS 分层
• references/effort-estimation.md — agent-oriented 工期（禁人天/FTE）
• references/artifact-storage-paths.md — 产物存储路径 SSOT（知识文档、CONCEPTS.md、STRATEGY.md 等落盘位置；mstar-compound、mstar-compound-refresh、mstar-strategy 等技能引用此表，不得本地重定义）

Plan 工件细则（主 plan、review bundle / durable summaries、status.json、residual、knowledge、Done 归档、templates/）→ skill mstar-artifacts（references/ 与 templates/）。