@mstar-harness/omp 3.6.0-alpha.4

package/skills/mstar-compound/references/schema.yaml

@@ -0,0 +1,122 @@
+# Knowledge documentation schema for {KNOWLEDGE_DIR}
+# Canonical frontmatter contract. Two tracks: bug and knowledge.
+
+tracks:
+  bug:
+    description: "Defects, failures, and errors that were diagnosed and fixed"
+    problem_types:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - config_error
+  knowledge:
+    description: "Practices, patterns, conventions, decisions, and workflow improvements"
+    problem_types:
+      - best_practice
+      - documentation_gap
+      - workflow_issue
+      - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+      - api_design
+      - testing_pattern
+
+required_fields:
+  module:
+    type: string
+    description: "Module, component, or area affected"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date documented (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - config_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+      - api_design
+      - testing_pattern
+    description: "Primary category — determines track (bug vs knowledge)"
+
+  category:
+    type: string
+    description: "Directory name under {KNOWLEDGE_DIR} (see category-mapping.md)"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+track_rules:
+  bug:
+    required:
+      symptoms:
+        type: array
+        description: "Observable symptoms (errors, broken behavior)"
+      root_cause:
+        type: string
+        description: "Fundamental technical cause"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+        description: "Type of fix applied"
+  knowledge:
+    optional:
+      applies_when:
+        type: array
+        description: "Conditions or situations where this guidance applies"
+
+optional_fields:
+  plan_id:
+    type: string
+    description: "Link to status.json plans[].id"
+  tags:
+    type: array
+    max_items: 8
+    description: "Search keywords, lowercase, hyphen-separated"
+  last_updated:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date of last substantive update (added when updating an existing doc)"
+  related_components:
+    type: array
+    description: "Other components involved"

package/skills/mstar-compound-refresh/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: mstar-compound-refresh
+description: Morning Star 知识维护与项目知识 bootstrap —— 审查 `{KNOWLEDGE_DIR}` 文档是否仍准确、去重叠合并、清理过期知识；或从代码库提炼 CONCEPTS.md、基线 knowledge 脚手架（无/残旧/空白 knowledge）。STRATEGY.md 创建委托 **`mstar-strategy`**。触发：`mstar-compound` 发现可合并文档、定期维护、项目缺 CONCEPTS.md/{KNOWLEDGE_DIR}、stale knowledge scaffolding、显式 bootstrap 请求、或显式 refresh。产出：更新/合并/删除知识文档 + 维护报告；或 bootstrap 产物（CONCEPTS.md、基线 knowledge）。
+---
+
+# mstar-compound-refresh（知识维护）
+
+## Load order
+
+**Read `mstar-harness-core` first.** Path symbols → **`mstar-conventions`**. On conflict, **`mstar-harness-core` wins**.
+
+## Purpose
+
+Knowledge documents in `{KNOWLEDGE_DIR}` age. Code changes, conventions evolve, patterns become obsolete. `mstar-compound-refresh` audits the knowledge store against the current codebase and makes it trustworthy again.
+
+## 产物与操作路径
+
+**SSOT**: `mstar-conventions/references/artifact-storage-paths.md`。本 skill 仅操作 `{HARNESS_DIR}/knowledge/**/*.md` + `{HARNESS_DIR}/knowledge/README.md` + `<repo-root>/CONCEPTS.md` + `{HARNESS_DIR}/status.json`（引用更新；v2 中知识引用挂在 workflow snapshot plan 行 `metadata.knowledge_refs`，见下）。**禁止**操作 `docs/`、`{PLAN_DIR}/`、`{ITERATION_DIR}/`、`{SPECS_DIR}/`。
+
+> **Engine check (when available):** run `mstar compound validate <doc-path> --knowledge-dir <dir>` (or `import { scopeGuard, compoundRefreshScope } from "@mstar-harness/engine"` in a host hook) to resolve the allowed scope above (`{HARNESS_DIR}/knowledge/**`, `knowledge/README.md`, `<repo-root>/CONCEPTS.md`, `{HARNESS_DIR}/status.json`) and guard every write against it. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## When to use
+
+| Trigger | Example |
+|---------|---------|
+| `mstar-compound` detected overlapping docs | "Two docs cover N+1 queries — consider refresh" |
+| Scheduled maintenance | "It's been a quarter, let's audit knowledge" |
+| Domain refactored | After a major module rewrite |
+| Explicit user request | `/pm compound-refresh performance-issues` |
+| **Project knowledge bootstrap** | No/stale/partial `STRATEGY.md`, `CONCEPTS.md`, or `{KNOWLEDGE_DIR}` — see below |
+
+## Bootstrap vs refresh
+
+| Mode | When | Procedure |
+|------|------|-----------|
+| **Refresh** | `{KNOWLEDGE_DIR}` exists; audit accuracy, merge overlaps, delete stale docs | This skill § Process (Phases 1–6) |
+| **Bootstrap** | No knowledge scaffolding, or artifacts are absent/stale enough to warrant full distillation from codebase | **`references/project-knowledge-bootstrap.md`** (7-phase: survey → STRATEGY.md → CONCEPTS.md → baseline knowledge → indexing → harness init → commit) |
+
+Read the bootstrap reference on demand; do not paste its body into this SKILL.md.
+
+## Maintenance outcomes
+
+For each candidate document, classify into one of five outcomes:
+
+| Outcome | Meaning | Default action |
+|---------|---------|----------------|
+| **Keep** | Still accurate and useful | No edit; report reviewed |
+| **Update** | Core solution correct, references drifted | In-place edits (paths, module names, code snippets) |
+| **Consolidate** | Two+ docs overlap heavily, both correct | Merge unique content into canonical doc, delete subsumed |
+| **Replace** | Old doc is misleading; known better replacement exists | Create trustworthy successor, then delete old |
+| **Delete** | No longer useful, applicable, or distinct | Delete — git history preserves it |
+
+> **Guardrail — rejected approaches:** a captured rejected approach stays only while the losing idea remains a tempting, meaningful mistake; delete it once obsolete or no longer plausible.
+> **Calibration:** first real run of this axis — 9 size-divergent knowledge docs (36–78 lines) under `{KNOWLEDGE_DIR}/architecture-patterns/` classified at fold time, all kept by future value (evidence: the knowledge-prose-folds plan `## Review Gate Summary` → Task evidence); length proved not to be a criterion.
+
+## Core rules
+
+1. **Evidence over opinion.** Signals are inputs, not a scorecard. Use engineering judgment.
+2. **Prefer no-write Keep.** Do not update a doc just to leave a review breadcrumb.
+3. **Match docs to reality.** When code differs from doc, update the doc — not ask whether the code change was "intentional."
+4. **Be decisive.** When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
+5. **Avoid low-value churn.** Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
+6. **Delete, don't archive** — **except** formal **iteration-start** §1.6 corpus hygiene (`mstar-iteration/references/iteration-corpus-hygiene.md`), which **moves** superseded/redundant knowledge/specs to `{HARNESS_DIR}/archived/knowledge|specs/`. Outside that gate, git history is the archive; `git log --diff-filter=D -- <path>` finds deleted docs.
+   > **Not adopted:** frozen-archive seal machinery, `Archived:` triplets, or a verifier — they contradict rule 6 (delete, don't archive; git history is the archive); do not reintroduce.
+7. **Evaluate document-set design.** Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.
+
+## Scope selection
+
+### Default: user-guided
+
+1. Ask PM for scope: "All knowledge docs, a specific category, or a keyword?"
+2. If category: narrow to `{KNOWLEDGE_DIR}/<category>/`.
+3. If keyword: search frontmatter (`module:`, `tags:`, `problem_type:`) and filenames.
+
+### PM-directed: specific scope
+
+PM provides a scope hint (directory name, filename, module name, or keyword). Match in this order:
+1. Directory match under `{KNOWLEDGE_DIR}/`
+2. Frontmatter field match
+3. Filename match
+4. Content search
+
+## Process
+
+### Phase 1: Inventory
+
+1. List all `.md` files under `{KNOWLEDGE_DIR}/` (excluding `README.md` and index files).
+2. Read frontmatter of each candidate.
+3. Group by `category` / `module` for impact clustering.
+
+### Phase 2: Assess per doc
+
+For each doc, check:
+
+1. **Referenced code still exists?** — grep for file paths, class names, function names mentioned.
+2. **Referenced conventions still match?** — check against current `AGENTS.md`, `CONCEPTS.md`, lint configs.
+3. **Solution still the recommended approach?** — has a newer pattern superseded it?
+4. **Overlap with other docs?** — search for same module/tags to find duplicates.
+5. **Future decision value?** — rationale / alternatives considered / negative guarantees / reintroduction conditions that would still guide a future change → **Keep, regardless of length**. A completed decision whose body has no future leverage left (one-off fix detail, superseded mechanics) enters the Delete candidate pool. Word count and age remain discovery aids, never criteria.
+
+### Phase 3: Classify and act
+
+Classify each doc → Keep / Update / Consolidate / Replace / Delete. Apply changes.
+
+### Phase 4: Update indexes
+
+1. Update `{KNOWLEDGE_DIR}/README.md` index table — update Status column, add/remove rows.
+2. If a doc was linked from knowledge refs (workflow snapshot plan row `metadata.knowledge_refs` / v1 root `status.json` metadata), update the references.
+
+### Phase 5: Report
+
+Produce a maintenance report:
+- Docs reviewed (count)
+- Docs kept (count)
+- Docs updated (list with what changed)
+- Docs consolidated (list with which canonical doc merged into)
+- Docs replaced (list with successor path)
+- Docs deleted (list with reason)
+- Docs flagged for PM review (ambiguous cases)
+
+### Phase 6: CONCEPTS.md reconciliation
+
+If `CONCEPTS.md` exists, reconcile it with the refreshed knowledge:
+- Terms mentioned in updated/replaced docs may need updating in CONCEPTS.md
+- Terms no longer referenced may be candidates for removal
+
+If `CONCEPTS.md` doesn't exist but knowledge docs contain qualifying domain terms, propose bootstrapping it (full repo-wide seed). Use `references/concepts-vocabulary.md` from `mstar-compound` for rules (read on demand — cross-skill path resolution via skill directory).
+
+## Cross-skill coordination
+
+`mstar-compound-refresh` reads vocabulary rules from `mstar-compound`'s references. At runtime, resolve the path from the loaded skill directory:
+
+```
+The CONCEPTS.md vocabulary rules are in the mstar-compound skill at:
+references/concepts-vocabulary.md
+Read that file from the mstar-compound skill directory before Phase 6.
+```
+
+## NOT to do
+
+- Do not delete docs without checking for inbound links
+- Do not "archive" — delete instead
+- Do not ask PM about mechanical updates (path fixes, renamed modules)
+- Do not change code to match outdated docs — update docs to match code
+- Do not run without PM approval for destructive actions (Delete, Replace)
+
+## Evidence
+
+正确结果 = 每篇候选文档有明确 verdict（Keep / Update / Consolidate / Replace / Delete）并落到产物：文档改动 + `{KNOWLEDGE_DIR}/README.md` 索引更新（Phase 4）+ 知识引用同步（workflow snapshot plan 行 `knowledge_refs`；v1 根 `status.json` legacy 引用） + 维护报告（Phase 5：reviewed / kept / updated / consolidated / replaced / deleted / flagged）+ `CONCEPTS.md` 对账（Phase 6）。
+
+## References
+
+- 捕获侧规则与 CONCEPTS.md vocabulary 规则 → **`mstar-compound`**（Phase 6 前读 `references/concepts-vocabulary.md`）
+- 路径符号与产物存储 SSOT → **`mstar-conventions`**（`references/artifact-storage-paths.md`）

package/skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md

@@ -0,0 +1,164 @@
+# Bootstrap Project Knowledge
+
+Distill a coherent knowledge baseline from the current project — useful when the project has no `STRATEGY.md` / `CONCEPTS.md` / `{KNOWLEDGE_DIR}`, has partial or outdated ones, or has accumulated documentation debt.
+
+**Goal**: produce a minimal, accurate, opinionated knowledge foundation that future iteration-start and plan-work can ground in.
+
+## Load order (bootstrap)
+
+1. `mstar-harness-core`
+2. `mstar-compound-refresh` (this skill)
+3. `mstar-conventions`（路径符号）
+4. `mstar-strategy` → **§ STRATEGY.md structure** + **§ Creating STRATEGY.md**
+5. `mstar-compound` → **references/concepts-vocabulary.md**（CONCEPTS.md 规则）
+6. This reference — **§ Core rules** in `mstar-compound-refresh/SKILL.md`（知识维护基线）
+
+## Phase 1: Survey — understand what exists
+
+### 1.1 Codebase scan
+
+- Read `README.md` (if exists) to understand project purpose
+- Read `AGENTS.md` / `CLAUDE.md` (if exists) for conventions and maintenance rules
+- Glob for `**/package.json`, `**/pyproject.toml`, `**/go.mod`, `**/Cargo.toml` to identify tech stack
+- Glob for `**/src/`, `**/lib/`, `**/app/` to identify module structure
+- Scan top-level directory layout
+
+### 1.2 Existing knowledge inventory
+
+Check what already exists and note its condition:
+
+| Artifact | Check | Condition |
+|----------|-------|-----------|
+| `STRATEGY.md` | Exists? Is it current/accurate? | `absent` / `stale` / `partial` / `current` |
+| `CONCEPTS.md` | Exists? Covers core domain nouns? | `absent` / `stale` / `partial` / `current` |
+| `{KNOWLEDGE_DIR}/README.md` | Exists? Index populated? | `absent` / `empty` / `partial` / `current` |
+| `{KNOWLEDGE_DIR}/**/*.md` | Any knowledge docs? Are they still accurate? | `none` / `few` / `some` / `many` |
+| `{ITERATION_DIR}/README.md` | Exists? Any past iteration artifacts? | `absent` / `present` |
+| `{SPECS_DIR}/` or `designs/` | Any specs or ADRs? | `absent` / `present` |
+| `docs/` | Any architecture docs, design notes? | Count and note relevance |
+| `{HARNESS_DIR}/status.json` | Exists? Any historical plans / workflows (`workflows[]`, snapshots)? | `absent` / `present` |
+
+Report findings to the user: what exists, what's missing, what's stale.
+
+### 1.3 Deep read — extract knowledge from code
+
+For each primary module / package identified in 1.1:
+
+1. Read the module's exported interface (public classes, functions, APIs)
+2. Read key configuration files (database schema, routes, middlewares)
+3. Identify recurring patterns: error handling style, dependency injection, ORM usage, auth flow
+4. Note any README or docstrings that describe domain concepts
+
+**Output**: a mental model of the project's domain, architecture patterns, conventions, and tech choices.
+
+## Phase 2: Distill STRATEGY.md
+
+Use `mstar-strategy` skill to produce `<repo-root>/STRATEGY.md`.
+
+### If STRATEGY.md is absent
+
+1. Gather context from Phase 1 survey
+2. Ask the user the 5 interview questions（`mstar-strategy` § Phase 2）
+3. Draft and review: keep each section 1-3 sentences
+
+### If STRATEGY.md exists but is stale/partial
+
+1. Present specific findings: "Section X contradicts current code / is outdated because Y changed"
+2. Ask whether to update in-place or rewrite
+3. Apply edits, keeping the Decision Log for historical context
+
+### If STRATEGY.md is current
+
+Skip, note in report.
+
+## Phase 3: Seed CONCEPTS.md
+
+Use `mstar-compound/references/concepts-vocabulary.md` rules to produce `<repo-root>/CONCEPTS.md`.
+
+### Identify core domain nouns
+
+From the codebase survey and STRATEGY.md, extract terms that meet the qualifying bar:
+- Its meaning in this project is precise enough that a new engineer would need it defined
+- It is not general programming vocabulary
+
+**Source areas** to scan:
+- Database schema (table/column names that encode domain concepts)
+- Core model/type definitions
+- API endpoint naming patterns
+- Entity relationship structure
+- README / architecture docs
+- STRATEGY.md domain terms
+
+### Write entries
+
+Each entry: one-sentence definition + optional paragraph for behavioral rules.
+- Cluster by domain relationship
+- Add `*Avoid:*` aliases for retired synonyms
+- No implementation specifics (file paths, class names)
+- Add `## Flagged ambiguities` tail section if needed
+
+### If CONCEPTS.md already exists
+
+Reconcile: keep valid entries, add newly discovered terms, update stale definitions. Do not duplicate.
+
+## Phase 4: Generate baseline knowledge docs
+
+From the Phase 1 survey, identify patterns and conventions worth documenting as knowledge docs in `{KNOWLEDGE_DIR}/`.
+
+### Minimum docs to produce (if absent)
+
+| Knowledge doc | Content source | Category |
+|---------------|---------------|----------|
+| **Architecture overview** | Module structure, tech stack, component interactions | `architecture-patterns/` |
+| **Development conventions** | Linting, testing, commit format, code style from AGENTS.md / configs | `conventions/` |
+| **Project setup** | Dependencies, environment setup, build/run commands | `developer-experience/` |
+| **Key domain patterns** | ORM patterns, auth flow, error handling, API design | `best-practices/` |
+
+Each doc follows the Knowledge track template (`mstar-compound/assets/resolution-template.md`).
+
+### What NOT to generate
+
+- Do not guess implementation details you haven't verified from code
+- Do not document general framework knowledge (e.g., "how to use React")
+- Do not create docs for areas the user explicitly excludes
+
+### If knowledge docs already exist
+
+Apply `mstar-compound-refresh` logic:
+- Keep accurate docs
+- Update stale references
+- Consolidate overlapping docs
+- Delete docs for code that no longer exists
+- Add new docs only for genuinely undocumented patterns
+
+## Phase 5: Indexing & discoverability
+
+1. Create or update `{KNOWLEDGE_DIR}/README.md` index table
+2. Create or update `{ITERATION_DIR}/README.md` index table (if iteration artifacts exist)
+3. Check AGENTS.md references all knowledge artifacts:
+   - If missing `{HARNESS_DIR}/knowledge/` → propose adding
+   - If missing `STRATEGY.md` → propose adding
+   - If missing `CONCEPTS.md` → propose adding
+4. Ask for consent before editing AGENTS.md
+
+## Phase 6: Initialize harness (if absent)
+
+If `{HARNESS_DIR}/` does not exist:
+1. Initialize per `mstar-conventions`（`.mstar/` + subdirectories）
+2. Create empty `status.json` from template (`mstar-artifacts/templates/status.empty.json`)
+
+## Phase 7: Commit
+
+All bootstrap artifacts must be committed:
+
+```bash
+git add STRATEGY.md CONCEPTS.md AGENTS.md {HARNESS_DIR}/ {KNOWLEDGE_DIR}/
+git commit -m "chore: bootstrap project knowledge — STRATEGY.md, CONCEPTS.md, baseline knowledge docs"
+```
+
+Report a summary:
+- STRATEGY.md: created / updated / skipped
+- CONCEPTS.md: created / updated（<N> entries）/ skipped
+- Knowledge docs: <N> created, <N> updated, <N> deleted, <N> kept
+- Harness: initialized / already existed
+- AGENTS.md: updated / not modified

package/skills/mstar-conventions/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: mstar-conventions
+description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{SDD_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` / `{WORKFLOW_DIR}` / `{PROJECT_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs` 与 harness 子树边界、review bundle、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（显式 base / merge 靶 / PR target）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / review bundle / knowledge → **`mstar-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
+---
+
+## Load order（必读顺序）
+
+**首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md）。** 本 skill 只约定 **目录与路径**；不突破状态机与门禁。冲突时 **以 `mstar-harness-core` 为准**。
+
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-artifacts` | 主 plan、review bundle 摘要、`status.json`、residual、InReview/QC 波次、knowledge |
+| `mstar-project-governance` | `projects/<id>/roadmap.md` 编写约定 + `residuals.json` register 生命周期、`_default` 回退 |
+| `mstar-branch-worktree` | Assignment 写分支 / worktree / QC 检出 |
+| `mstar-review-qc` | 派 QC（PM 同轮必读；SDD 强制 tri） |
+| `mstar-sdd` | PM 执行 `Execution mode: sdd` 的 implement 波次 |
+
+## 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）
+
+| 符号 | 默认 |
+|------|------|
+| `{HARNESS_DIR}` | `.mstar/` |
+| `{PLAN_DIR}` | `{HARNESS_DIR}/plans/` |
+| `{SDD_DIR}` | `{HARNESS_DIR}/sdd/<plan-id>/`（SDD 运行时 scratch + review bundle；gitignored） |
+| `{ITERATION_DIR}` | `{HARNESS_DIR}/iterations/` |
+| `{KNOWLEDGE_DIR}` | `{HARNESS_DIR}/knowledge/`（默认；`.mstarc` `knowledge_dir` 声明时用声明值） |
+| `{SPECS_DIR}` | `{HARNESS_DIR}/specs/`（默认）；解析见下文「`{SPECS_DIR}` 解析」 |
+| `{WORKFLOW_DIR}` | `{HARNESS_DIR}/workflows/`（默认；`.mstarc` `workflow_dir` 声明时用声明值）——v3 每 lifecycle 一个 `workflows/<id>/`（`snapshot.json` + `notes.jsonl`） |
+| `{PROJECT_DIR}` | `{HARNESS_DIR}/projects/`（默认；`.mstarc` `project_dir` 声明时用声明值）——v3 项目层 `projects/<id>/roadmap.md` + `residuals.json` |
+
+> **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 跟踪策略」）
+
+```ini
+[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 时提及。
+
+## 内容边界（摘要）
+
+| 区域 | 内容 |
+|------|------|
+| `docs/` | 人类文档：安装、贡献 |
+| `{SPECS_DIR}` | 冻结规格 / ADR |
+| `{ITERATION_DIR}` | 迭代 package（compass + guides/specs） |
+| `{KNOWLEDGE_DIR}` | 实现 SSOT、可复用设计 |
+| `{PLAN_DIR}/` | 主 plan、durable gate summaries、可选 residual prose |
+
+单 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`**。
+
+## 初始化 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`）
+
+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` 进入 feature 检出。读写须经 **control worktree** 绝对路径（`<control_worktree_path>/{HARNESS_DIR}/…`）；产品代码改在 feature worktree。细则与反模式（禁止因 feature 缺 plans 而 `Worktree mode: waived`）→ **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」。
+
+**Canonical `.gitignore` snippet**（skills 与 CLI `init` 对齐）：
+
+```gitignore
+# 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/` 等价：
+
+```gitignore
+# 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`。
+- **Spec 集成分支**：从 `iteration_base_branch` 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
+- **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
+- **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
+- 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` 输出与路径符号表一致。
+
+## 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/`）。