btspoony/mstar-harness/mstar-conventions

Load order（必读顺序）

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

Workflow

主链：按「路径符号」+「{HARNESS_DIR} 解析顺序」确定目录（默认 .mstar/，兼容 .agents/）→ 按「初始化 Plan 目录」以 `mstar harness scaffold` + `mstar store init` 建立 authored 目录与 ACTIVE store（唯一 bootstrap 路径），并追加 gitignore 进程产物集（未声明 harness 根规则时；进程本地、结果共享）→ 多 Plan · 同一 Spec 时登记 iteration base / spec 集成分支 / 各 Plan 实现分支 / PR target → 主 plan 写入 {PLAN_DIR}（Plan-Writing Path Gate）。未启用 plan 或无 ACTIVE store 时 → 对话追踪（no-plan mode），门禁（QC/QA）照常。

路径符号（SSOT）

Engine check: engine resolveHarnessDir / resolvePlanDir / resolveSddDir / resolveIterationDir / resolveKnowledgeDir / resolveSpecsDir / resolveAdrDir / resolveWorkflowDir / resolveProjectDir / resolveReviewDir — or run mstar path resolve [path], whose JSON envelope prints the resolved dirs (including specsDir, knowledgeDir, adrDir) — to confirm the resolution below. On fail, do not proceed — fix and re-run. Contract → `mstar-use-cli` references/checks-and-lints.md § Engine check callouts.

{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
adr_dir=docs/adr
workflow_dir=process/workflows
project_dir=process/projects
review_dir=process/reviews
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}，权威——声明后不再走候选链）、adr_dir（{ADR_DIR}，权威——同上）、workflow_dir（{WORKFLOW_DIR}）、project_dir（{PROJECT_DIR}）、review_dir（{REVIEW_DIR}）。全部相对 .mstarc 所在目录解析（绝对路径亦可）；无需目录已存在（可后续 scaffold；v3 的 workflows/ / projects/ / reviews/ 子目录由 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 / resolveAdrDir / resolveWorkflowDir / resolveProjectDir / resolveReviewDir / 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 / adr_dir / workflow_dir / project_dir / review_dir）从 `{HARNESS_DIR}` 或其父目录（仓库根）向上找最近 .mstarc 读取；值同样相对配置文件目录解析；specs_dir / adr_dir 声明后直接采用（跳过下方候选链与空目录规则），sdd_dir 只替换基目录（<plan-id> 仍追加），workflow_dir / project_dir / review_dir 直接替换默认子目录名。
5. 未声明的键回落默认组合：{HARNESS_DIR}/plans/、{HARNESS_DIR}/sdd/<plan-id>/、{HARNESS_DIR}/iterations/、{HARNESS_DIR}/workflows/、{HARNESS_DIR}/projects/、{HARNESS_DIR}/reviews/；{SPECS_DIR} / {KNOWLEDGE_DIR} / {ADR_DIR} 走下方候选链。

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

1. .mstarc specs_dir（权威：声明即采用，跳过本链）
2. {HARNESS_DIR}/specs/（默认 .mstar/specs/）
3. <repo-root>/.agents/specs/
4. docs/specs/
5. specs/（仓库根）
6. legacy 只读：{HARNESS_DIR}/designs/、仓库根 designs/（仅非空时可用；init 不新建）

空目录规则：候选路径存在但无任何文件 → 视为不存在，继续下一候选；候选按解析后路径去重（harness 根即 .agents/ 时第 3 项与第 2 项是同一目录）。

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

{KNOWLEDGE_DIR} / {ADR_DIR} 解析（找到非空目录即停）

• {KNOWLEDGE_DIR}：.mstarc knowledge_dir（权威）→ {HARNESS_DIR}/knowledge/ → <repo-root>/.agents/knowledge/（空目录视为不存在）→ 回退 {HARNESS_DIR}/knowledge/，需创建时创建（resolveKnowledgeDir 默认创建，{ create: false } 关闭）。
• {ADR_DIR}：.mstarc adr_dir（权威）→ {HARNESS_DIR}/adr/ → <repo-root>/.agents/adr/ → <repo-root>/docs/adr/（均按空目录规则）→ 回退 {HARNESS_DIR}/adr/，创建规则同上（resolveAdrDir）。

Engine check: engine resolveSpecsDir / resolveKnowledgeDir / resolveAdrDir — or run mstar path resolve (prints all three) — to confirm the candidate order (empty-dir-as-absent included). On fail, do not proceed — fix and re-run. Contract → `mstar-use-cli` references/checks-and-lints.md § Engine check callouts.

部分 spoke 仓库 opt-in 跟踪的 {HARNESS_DIR}/roadmap.md 仅是既有 Markdown 文件/可审导入候选，非项目内容权威；读写规则 → mstar-project-governance。

内容边界（摘要）

单 plan 的 QC/QA 原始过程报告默认进入 `{SDD_DIR}/review/`（gitignored review bundle），非 docs/，也不默认进入 {PLAN_DIR}。主 plan 仅保留 durable gate summary；open finding 以 {HARNESS_DIR}/store.db 的 linked issues 为 SSOT（mstar plan issue-add / mstar issue add）；project residual register 无条件退役为迁移历史。细则 → `mstar-artifacts`。

Issue/catalog store 路径与权威分界

Issue/catalog/roadmap and ACTIVE execution authority live in control-root {HARNESS_DIR}/store.db; roadmap/milestone rules → mstar-project-governance. ACTIVE root register, workflow/plan rows, coordinator sessions, registered inputs and workflow merge exclusion live in execution_* tables. Coordinator source metadata/configuration/progress/completion and merge exclusion are domain-written; no per-row session or sealed Assignment. Historical execution files are read-only direct mstar store upgrade inputs, preserving original bytes; no staging writer or runtime file-state fallback remains. Retained ordinary artifacts stay with ArtifactStore; notes and docs never become transactional authority.

Catalog 字段权威（contract §1）

Store is process-local and gitignored. Issue/catalog and execution domains retain their own authority boundaries. Missing stores refuse store.not-initialized rather than answering an empty catalog. Staged stores support ordinary read-only catalog list/show; catalog mutations require an active store and refuse store.not-active while staged. Staged catalog inspection does not activate execution authority, and ACTIVE execution reads never fall back to leftover root/snapshot/session files. Bootstrap/migration changes authority only through supported operator operations.

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

mstar catalog discover 是只读 dry-run 提案（配置根 tracked 正文 + legacy 索引行 → 候选证据，带 reviewed source hash、显式 unknowns 与拟退役索引节）；import 按当前语义 identity/path/revision 应用该映射（source hash 仅 provenance，reviewed 字节漂移不单独拒绝），不建 workflow session、不退休索引；register / update / link 是单行登记与元数据/关系变更（identity 不可改）；query = list / show；reconcile 收口注册中断（pending catalog.registration-pending，contract §3）；export 是版本化 transport，回灌用 import。

标志、revision 守卫与可改字段以 mstar catalog --help 为准（族名索引 → `mstar-use-cli`）。

跨 clone 限制（contract §4）

store.db 是本地/进程产物，仅凭 tracked 正文无法重建 catalog 历史。discover 只提取 tracked 正文的 title/path/content hash 与显式元数据作候选证据，从不假设文件名编码 project/iteration 归属、归档状态、执行状态或 provenance——未声明的一律以显式 unknowns（identity / membership / document-kind / source-missing …）披露，需人工 review 后 import；完整恢复需 catalog export + reviewed import。

Store 落在 control / process harness 根，不随 feature worktree cwd；Help / validator / engine import 不打开 SQLite。文档本身不证明打包兼容或激活就绪。

初始化 Plan 目录