@mstar-harness/dsh 2.4.1 → 3.0.1

package/dist/service.d.ts

@@ -7,7 +7,7 @@
  * @module @mstar-harness/dsh
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import type { EnforcementFlag, FindingsCleanupMode, GateResult, ResolveHarnessDirOptions, ResidualEntry, StatusDoc } from '@mstar-harness/engine';
+import type { EnforcementFlag, FindingsCleanupMode, GateResult, ProjectRegisterDoc, ResolveHarnessDirOptions, ResidualEntry, StatusV2Doc } from '@mstar-harness/engine';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Morning Star engine service provided by `@mstar-harness/dsh`. */
@@ -45,24 +45,29 @@ export declare class DshMstar extends Service {
     readonly harnessDir: string | null;
     constructor(ctx: Context, options: DshMstarOptions);
     /**
-     * Validate a status.json document or file path.
-     * @param docOrPath - parsed status document or path to a status.json file.
+     * Validate a status.json document or file path (the v2 root schema —
+     * engine `validateStatus` = `validateStatusV2`; a v1 document fails with
+     * `status.migration-required` carrying the `mstar migrate` hint).
+     * @param docOrPath - parsed v2 status document or path to a status.json file.
      */
-    validateStatus(docOrPath: StatusDoc | string): GateResult;
+    validateStatus(docOrPath: StatusV2Doc | string): GateResult;
     /**
      * Validate one residual entry (status-and-residuals.md § Basic structure).
-     * @param entry - the residual entry as parsed from status.json.
+     * @param entry - the residual entry as parsed from a project register.
      */
     validateResidual(entry: ResidualEntry | unknown): GateResult;
     /**
      * Findings cleanup gate for one plan (status-and-residuals.md § Findings
-     * cleanup modes). Mode resolution: explicit `opts.mode` → `plans[].metadata.
-     * findings_cleanup` → `allow-residual`.
-     * @param doc - the parsed status document.
+     * cleanup modes; v3 relocation — the input is the project register
+     * `projects/<id>/residuals.json`, entries keyed by plan id; the v1
+     * `plans[].metadata.findings_cleanup` mirror is deleted — explicit
+     * `opts.mode` or `allow-residual`). Every OPEN register entry of the plan
+     * is checked.
+     * @param register - the parsed project register document.
      * @param planId - the plan whose open residuals are checked.
      * @param opts - explicit cleanup-mode override.
      */
-    findingsCleanupGate(doc: StatusDoc, planId: string, opts?: {
+    findingsCleanupGate(register: ProjectRegisterDoc, planId: string, opts?: {
         mode?: FindingsCleanupMode;
     }): GateResult;
     /**

package/dist/types.d.ts

@@ -77,7 +77,7 @@ export interface IterationGateView {
 export interface MstarIterationGateView {
     /** Iteration id whose steering compass was evaluated. */
     readonly iterationId: string;
-    /** Control-path `{HARNESS_DIR}/status.json` evaluated. */
+    /** The evaluated workflow snapshot path (`workflows/<id>/snapshot.json` — v3, the gate's first doc). */
     readonly statusPath: string;
     /** The steering `{ITERATION_DIR}/<id>/delivery-compass.md` evaluated. */
     readonly compassPath: string;
@@ -135,6 +135,52 @@ export interface HarnessLeaseView {
     readonly holder: string;
     readonly worktreePath: string | null;
 }
+/**
+ * The additive project rollup section of the workspace-state digest (compass
+ * v3.0.0 AC-4 / AC-P3 — the panel's fifth zone surface; additive, the four
+ * existing ZoneView shapes stay byte-compatible): roadmap milestones +
+ * open-residual severity counts from the PROJECT layer
+ * (`projects/<id>/roadmap.md` frontmatter `milestones[]` and
+ * `projects/<id>/residuals.json` registers — the v1 root
+ * `residual_findings` home is gone). Always-present (lossless JSON): no
+ * roadmaps → `milestones: []`; no registers / no open entries →
+ * `openResiduals: []` — same advisory pattern as `residuals`.
+ */
+export interface MstarHarnessProject {
+    /** Roadmap milestones across ALL project registers (frontmatter `milestones[]`, roadmap order, projects dir order). */
+    readonly milestones: readonly string[];
+    /** Open residual counts by severity across ALL project registers (non-zero severities only — same vocabulary as `state.residuals`). */
+    readonly openResiduals: readonly HarnessResidualView[];
+}
+/**
+ * The catalog's workflow selection result (compass v3.0.0 § Catalog
+ * selection rule): the lifecycle the state section aggregates.
+ * `active` = the root v2 `workflows[]` first entry (with a structured
+ * warning when multiple active lifecycles — no silent pick); `terminal` =
+ * the latest terminal snapshot by mtime (history view); `error` = a clear
+ * selection failure (v1/unmigrated root, no snapshots) — never a root v1
+ * read. Structured and panel-renderable (not only a log line).
+ */
+export type WorkflowSelectionView = {
+    readonly kind: 'active';
+    /** The selected active lifecycle id (root v2 `workflows[]` first entry). */
+    readonly workflowId: string;
+    /** Harness-relative workflow dir (e.g. `workflows/<id>`). */
+    readonly dir: string;
+    /** Present when multiple active lifecycles — the first was picked (no silent pick). */
+    readonly warning?: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly kind: 'terminal';
+    readonly workflowId: string;
+    readonly dir: string;
+} | {
+    readonly kind: 'error';
+    readonly code: string;
+    readonly message: string;
+};
 /**
  * The workspace-state digest section of the unified engine-status row: the
  * plan registry, open residual counts, branch/policy anchors, active
@@ -145,10 +191,26 @@ export interface HarnessLeaseView {
  * `buildCatalogSources`).
  */
 export interface MstarHarnessState {
-    /** Registered plan rows (`plan_id`/`id` + `status`), status.json order. */
+    /**
+     * The selected workflow lifecycle (compass v3.0.0 § Catalog selection
+     * rule): active `workflows[]` first → latest terminal snapshot by mtime →
+     * clear error. The state section aggregates the SELECTED lifecycle only;
+     * a selection error carries the operator-visible reason (never a root v1
+     * read).
+     */
+    readonly selection: WorkflowSelectionView;
+    /** Registered plan rows (`plan_id`/`id` + `status`), snapshot plans[] order. */
     readonly plans: readonly HarnessPlanView[];
     /** Open `residual_findings` counts by severity (non-zero only). */
     readonly residuals: readonly HarnessResidualView[];
+    /**
+     * The additive project rollup (compass v3.0.0 AC-4 — the panel's fifth
+     * zone): roadmap milestones + open-residual severity counts from the
+     * project layer (`projects/<id>/roadmap.md` / `projects/<id>/residuals.json`).
+     * Always-present (lossless) — empty arrays when the project layer is
+     * absent.
+     */
+    readonly project: MstarHarnessProject;
     /**
      * Open residual findings detail (planId + R# + severity + title), severity
      * ordered (critical→nit) and capped at 10. Null when the

package/harness-agents/code-reviewer.md

@@ -29,14 +29,6 @@ permission:
     ".worktrees/**/.mstar/plans/**/*.md": allow
     ".worktrees/**/.agents/plans/*.md": allow
     ".worktrees/**/.agents/plans/**/*.md": allow
-    ".harness/sdd/*.md": allow
-    ".harness/sdd/**/*.md": allow
-    ".harness/plans/*.md": allow
-    ".harness/plans/**/*.md": allow
-    ".worktrees/**/.harness/sdd/*.md": allow
-    ".worktrees/**/.harness/sdd/**/*.md": allow
-    ".worktrees/**/.harness/plans/*.md": allow
-    ".worktrees/**/.harness/plans/**/*.md": allow
   bash:
     "*": deny
     # Git inspection (read-only) — L2 diff review + audit recon; no test/build/lint CLIs

package/harness-skills/mstar-branch-worktree/SKILL.md

@@ -13,7 +13,7 @@ description: "Morning Star 业务仓 Git 功能分支、worktree 隔离（L1 跨
 
 - **仅 PM 决定分支**；其他可写角色不得自行新开分支或切回 `main`。
 - **Assignment 须含其一**：`Working branch: <existing>` | `create <new> from <base>` | `Branch policy: direct on <branch> — <reason>`。
-- **L1（跨 plan / 迭代 Phase 2）**：control worktree（`metadata.control_worktree_path`，检出 `spec_integration_branch`）+ 每 plan 独立 feature worktree（`execution_lease.worktree_path` **≠** control 路径）+ lease；见 **「Worktree isolation layers」**。
+- **L1（跨 plan / 迭代 Phase 2）**：control worktree（snapshot `control_worktree_path`，检出 `spec_integration_branch`）+ 每 plan 独立 feature worktree（`execution_lease.worktree_path` **≠** control 路径）+ lease；见 **「Worktree isolation layers」**。
 - **L2（同 plan 内 ≥2 可写并发）**：派发 **前** 完成 **`references/parallel-writable-pre-dispatch.md`**（含 `git worktree`、绝对 **`Worktree path`**；**N 次并行 invoke ≠ 已隔离**）。单 plan 多轨时 **L1 不替代 L2**。
 - **QC/QA 前**：待审提交归并到 **单一 `Working branch` `HEAD`**；三审 + QA 共用一套 **`Review cwd` + `plan_id` + `Review range` / `Diff basis`**（逐字相同）。
 
@@ -106,38 +106,38 @@ Two complementary **worktree** isolation layers coexist. Do **not** conflate the
 
 | Layer | Scope | When | Mechanism |
 |-------|-------|------|-----------|
-| **L1** | Cross-plan (iteration Phase 2) | Multiple plans may implement concurrently in one iteration | **Control worktree** + per-plan **feature worktrees** + `plans[].execution_lease` |
+| **L1** | Cross-plan (iteration Phase 2) | Multiple plans may implement concurrently in one iteration | **Control worktree** + per-plan **feature worktrees** + `plans[].execution_lease` (workflow snapshot `workflows/<id>/snapshot.json`) |
 | **L2** | Within-plan | Same `plan_id`, same business repo, **≥2 concurrent writable implement tracks** | **`references/parallel-writable-pre-dispatch.md`** — distinct absolute **`Worktree path`** per track |
 
 **Stacking rules**
 
 - Default **L1** capacity is **one writable track per plan**. If one plan runs **≥2** concurrent writable tracks, each track **also** satisfies **L2**; L1 does **not** replace L2.
 - **L1** applies under iteration commands with Phase 2 control-worktree defaults (unless explicit `Worktree mode: waived` this turn). Single-plan waves without iteration leases still require **L2** when **≥2** parallel writable tracks share one repo.
-- Cross-plan **integration merge** into `spec_integration_branch` remains **serial** (`metadata.integration_merge_lease`) even when L1 feature implementation runs in parallel.
+- Cross-plan **integration merge** into `spec_integration_branch` remains **serial** (snapshot top-level `integration_merge_lease`) even when L1 feature implementation runs in parallel.
 
 ### Control worktree vs feature worktree (iteration / L1)
 
 Established at iteration **Phase 2 entry** (Phase 1 Review & Edit may stay on the primary checkout). Normative field names and claim/release/merge protocol → **`mstar-iteration`** `references/phase-2-worktree-lease.md` and maintenance ADR `2026-07-22-iteration-worktree-plan-lease.md`. **Do not invent alternate lease field names in this skill.**
 
-| Worktree role | Checked-out branch | Path recorded in `status.json` | Writable product edits |
+| Worktree role | Checked-out branch | Path recorded in workflow snapshot | Writable product edits |
 |---------------|-------------------|-------------------------------|------------------------|
-| **Control worktree** | Resolved `spec_integration_branch` (same across active plans) | `metadata.control_worktree_path` — canonical **repository root** (not `{HARNESS_DIR}`) | **Forbidden** — harness coordination SSOT + serial integration merge only |
-| **Feature worktree** (per plan) | Plan `Working branch` / feature branch from integration | `plans[].execution_lease.worktree_path` | **Required cwd** for that plan's product/source edits |
+| **Control worktree** | Resolved `spec_integration_branch` (same across active plans) | `control_worktree_path` (snapshot top-level) — canonical **repository root** (not `{HARNESS_DIR}`) | **Forbidden** — harness coordination SSOT + serial integration merge only |
+| **Feature worktree** (per plan) | Plan `Working branch` / feature branch from integration | `plans[].execution_lease.worktree_path` (snapshot plan row) | **Required cwd** for that plan's product/source edits |
 
 ### Harness path SSOT under default gitignore (L1)
 
-Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `notes.json`, `archived/`) are **gitignored** (`mstar-plan-conventions`「Git 跟踪策略」). `git worktree add` does **not** copy them into a new feature checkout. They live on the **control worktree filesystem** (the checkout of `spec_integration_branch`), not as Git blobs on that branch.
+Default process artifacts (`plans/`, `iterations/`, `status.json`, `workflows/`, `projects/`, `sdd/`) are **gitignored** (`mstar-plan-conventions`「Git 跟踪策略」). `git worktree add` does **not** copy them into a new feature checkout. They live on the **control worktree filesystem** (the checkout of `spec_integration_branch`), not as Git blobs on that branch.
 
 | Path role | Resolve from |
 |-----------|--------------|
 | **Control harness root** | `<control_worktree_path>/{HARNESS_DIR}/` |
-| **Process / coordination SSOT** (read + write) | Absolute under control harness root: `status.json`, `plans/`, `iterations/`, `sdd/<plan-id>/`, `notes.json`, `archived/` |
+| **Process / coordination SSOT** (read + write) | Absolute under control harness root: `status.json` (v2 root), `workflows/<id>/snapshot.json`, `projects/<id>/residuals.json`, `plans/`, `iterations/`, `sdd/<plan-id>/` |
 | **Tracked results** (`AGENTS.md`, `knowledge/`, `specs/`) | Available in any worktree via Git; absolute control paths in Assignment are still fine |
 | **Product / source edits** | Feature worktree only (`execution_lease.worktree_path`) |
 
 **Hard rules**
 
-- `execution_lease.worktree_path` **MUST** differ from `metadata.control_worktree_path`.
+- Snapshot `control_worktree_path` **MUST** differ from `execution_lease.worktree_path` (never reuse the control checkout for product edits).
 - A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT — **never** treat it as the source of plans/status/SDD, and **never** bootstrap a second plans/status/SDD tree there.
 - Absolute **`Worktree path`** (feature) MUST appear in the writable Assignment and in `execution_lease.worktree_path` before first writable implement dispatch for that plan.
 - When L1 lease gate is active (not `Worktree mode: waived`), Assignment **`Plan Path`** and **`SDD dir`** MUST be **absolute paths under the control harness root** (not relative `.mstar/...` resolved from the feature cwd). Prefer also writing **`Control harness root: <control_worktree_path>/{HARNESS_DIR}`**.
@@ -149,11 +149,11 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 
 **Naming conventions (PM / ops; examples only — paths MUST be canonical absolute)**
 
-1. **Control worktree** — usually the primary checkout or a PM-designated path on `spec_integration_branch`; record once in `metadata.control_worktree_path`.
+1. **Control worktree** — usually the primary checkout or a PM-designated path on `spec_integration_branch`; record once in snapshot `control_worktree_path`.
 2. **Feature worktree (per plan)** — one distinct subdirectory under the workspace root **`.worktrees/`** per active `plan_id` (e.g. `.worktrees/<plan-id>-<slug>`; AGENTS.md「Local scratch layout」), gitignored by the repo convention; Assignment **`Worktree path`** must match lease `worktree_path`.
 3. **L2 track worktrees (within-plan)** — additional distinct directories per parallel implement track under the **same** plan (see **`references/parallel-writable-pre-dispatch.md`**), each with its own PM-approved **`Working branch`**.
 
-> **Engine check (when available):** run `mstar worktree check <plan-id>` (L1) / `mstar worktree check --l2 --tracks <json>` (L2) (or `import { l1PreDispatchCheck, l2PreDispatchCheck, assertControlVsFeaturePath, assertBranchAlignment } from "@mstar-harness/engine"` in a host hook) to verify the L1/L2 isolation rules above (lease worktree ≠ control path; checked-out branch matches `Working branch`). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar worktree check <plan-id> --workflow <id>` (L1) / `mstar worktree check --l2 --tracks <json>` (L2) (or `import { l1PreDispatchCheck, l2PreDispatchCheck, assertControlVsFeaturePath, assertBranchAlignment } from "@mstar-harness/engine"` in a host hook) to verify the L1/L2 isolation rules above (snapshot lease worktree ≠ control path; checked-out branch matches `Working branch`). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## 同仓并发写入与 Git worktree（强制）
 
@@ -184,7 +184,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 
 - **`Review cwd` / `Worktree path`**：**优先**沿用开发 Completion Report 回报的业务仓实现检出路径（该 feature 的 worktree）**当且仅当**该路径检出分支 `HEAD` 已含本轮待审全部提交（含曾发生在其他并行 worktree、现已归并到该分支的变更）。否则**必须**改用集成完成后的 `Working branch` 与对应检出路径（或在该分支上**另开**只读审查 worktree）。开发未用 worktree → 写明单一业务仓根路径。
 - **`Working branch`**：含全部待审提交的那条分支（常见 plan 集成分支）。
-- **`plan_id`**：与 `{SDD_DIR}` `<plan-id>` 段、主 Plan Path、`status.json.plans[].id` 一致；无 `{PLAN_DIR}` 流程时写 **`plan_id: N/A`** + 一行 **`Feature / scope label`**（不可歧义，足以与并行其它 feature 区分）。
+- **`plan_id`**：与 `{SDD_DIR}` `<plan-id>` 段、主 Plan Path、workflow snapshot `plans[].id` 一致；无 `{PLAN_DIR}` 流程时写 **`plan_id: N/A`** + 一行 **`Feature / scope label`**（不可歧义，足以与并行其它 feature 区分）。
 - **`Review range` / `Diff basis`**：审查的 diff/提交范围（例如 `merge-base: <target_branch-or-base-ref>` + `tip: HEAD`；或 `rev-range: <full-40>..<full-40>`；或一句 `equivalent to: git diff <merge-base>...HEAD`，以团队可复现为准）。
 - **逐字对齐（强制）**：三份 QC Assignment 与 QA Assignment 间 **`plan_id`** 与 **`Review range` / `Diff basis`**（连同 `Review cwd` / `Working branch`）**必须完全相同**；**`qa-engineer`** 验证同一 feature 时**复用同一组字段**。**热修 / QC 单审**路径也须含**同一组字段**，仅承接方份数为 1。
 - 三审并行时三名 reviewer **共用同一组**字段（对业务仓**只读 diff 审查**）；一般不必为每位 reviewer 各开 worktree，除非宿主/环境要求进程级隔离。
@@ -199,7 +199,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 
 **推荐默认编排（plan 集成分支先行）**——同仓、同一 plan、**≥2 条可写并行轨**时降低 QC/QA 误用单一开发目录风险。**不是唯一合法 Git 拓扑**；其它拓扑仍须满足上文对齐字段 + 本节**强制**条款（派发前 worktree 隔离 + 派 QC 前**单一**待审 `HEAD` + 一套对齐字段）：
 
-1. **先起集成分支（再挂 worktree）**：派发各轨**实现** Assignment 前，PM 与用户确认 **`Branch policy`**，建立 **plan 集成分支**（Assignment 用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 必须 PM 明确记录，例如 root `metadata.iteration_base_branch`、现有 feature 分支、远程跟踪分支或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**（`feature/<plan-id>-integrate`、`integrate/<plan-id>` 仅为命名示例，**非强制**）。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支语义即 **Spec 集成分支**；各 Plan feature 线 merge 回此线，**全部 Plans 完成后**向显式 `target_branch` **走 PR**（见 `mstar-plan-conventions` SKILL.md「Spec 驱动的分支模型」）。
+1. **先起集成分支（再挂 worktree）**：派发各轨**实现** Assignment 前，PM 与用户确认 **`Branch policy`**，建立 **plan 集成分支**（Assignment 用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 必须 PM 明确记录，例如 snapshot `branch.base`（`iteration_base_branch`）、现有 feature 分支、远程跟踪分支或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**（`feature/<plan-id>-integrate`、`integrate/<plan-id>` 仅为命名示例，**非强制**）。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支语义即 **Spec 集成分支**；各 Plan feature 线 merge 回此线，**全部 Plans 完成后**向显式 `target_branch` **走 PR**（见 `mstar-plan-conventions` SKILL.md「Spec 驱动的分支模型」）。
 2. **再挂各轨 worktree**：每条并行轨分配**独立** `git worktree` + **`Worktree path`**；各轨 `Working branch` 一般为**从集成分支出**的 topic 分支（`create <topic-i> from <plan-integration-branch>`）或 PM 书面约定等价结构（例如从同一 `<base>` 出 topic、但**书面指定**合并时**以集成分支为靶**）。**禁止**承接方擅自把未授权功能提交直接堆在 `main`/`master`。
 3. **进 QC 之前**：将全部**须同一轮三审覆盖**的提交**归并**（merge / rebase / cherry-pick，以 PM 指定团队方式）到同一条将作 QC **`Working branch`** 的分支 **`HEAD`**（**通常即 plan 集成分支**；PM 已重命名/快进为最终 `feature/*` 则以 Assignment 为准）。**在此**解决冲突；**勿**在 QC Assignment 仍指向「只含部分轨」旧 `HEAD` 时派三审。
 4. **QC/QA 的 `Working branch` 与合并主线**：`Working branch` 即上一步**已含全部待审提交**的那条分支（常见 plan 集成分支）。`Review range` / `Diff basis` 通常相对**尚未合并 feature 的**显式目标/base 参照（例如 `merge-base: <target_branch-or-base-ref>` + `tip: HEAD`），审的是 **「feature 线 vs 目标线」** 差异；**默认不要求** QC **通过前**已把该分支 merge 进目标分支（除非 **`Branch policy`** 或用户明确 trunk 式例外）。
@@ -212,7 +212,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 ### QC / QA 执行约束
 
 - **并行 QC 禁止**在共享检出跑 **test / build / install / lint / typecheck** 等争用缓存或锁的命令（否则 peer QC 易 `Blocked`）。L3 默认手段：`git diff` / `git log` / `git show` / Read / Grep。运行时验证留给 **L1 证据**与 **`qa-engineer`（L4）** — 见 `mstar-review-qc/references/review-responsibility-boundaries.md`。
-- QC **报告落盘**默认仅限 Assignment 指定的 `{SDD_DIR}/review/`；上述约定保证 `git diff`、`git log` 与所读文件与**待合并 feature** 一致。PM 另行提交主 plan gate summary / `status.json` residual changes as durable artifacts。
+- QC **报告落盘**默认仅限 Assignment 指定的 `{SDD_DIR}/review/`；上述约定保证 `git diff`、`git log` 与所读文件与**待合并 feature** 一致。PM 另行提交主 plan gate summary / project-register residual changes as durable artifacts。
 - **`qa-engineer`**（仅 **`QA gate: mandatory`**）Assignment 用 QC 逐字相同的对齐字段（QC 已写清则 QA 照抄）；执行业务仓命令前须核对检出与分支；Report-only 且无路径依赖时回报须说明验证环境，否则 `Blocked`。
 - 若 **QA 与同仓其他可写角色并发**提交测试代码，仍须遵守上文「同仓并发写入」**worktree** 规则（可为 QA 单开一条写入 worktree，**同一 `Working branch`**，由 PM 在 Assignment 写明）。
 

package/harness-skills/mstar-branch-worktree/references/parallel-writable-pre-dispatch.md

@@ -6,8 +6,8 @@ This reference is **L2** worktree isolation: **same `plan_id`**, **same business
 
 **L1 (cross-plan)** is separate and stacks on top when iteration Phase 2 defaults apply:
 
-- A **control worktree** on `spec_integration_branch` (`metadata.control_worktree_path`) holds status/SDD SSOT and serial integration merge.
-- Each concurrently active plan uses a **distinct feature worktree** (`execution_lease.worktree_path` **≠** `control_worktree_path`) with verified `plans[].execution_lease` before writable dispatch.
+- A **control worktree** on `spec_integration_branch` (snapshot `control_worktree_path`) holds status/SDD SSOT and serial integration merge.
+- Each concurrently active plan uses a **distinct feature worktree** (`execution_lease.worktree_path` **≠** `control_worktree_path`) with a verified snapshot `plans[].execution_lease` before writable dispatch.
 - Claim/hold/release/merge rules → **`mstar-iteration`** `references/phase-2-worktree-lease.md` (not repeated here).
 
 When **one plan** runs **≥2** concurrent writable tracks, **L2 still applies** inside that plan even if L1 leases already isolate plans from each other. Run this checklist **per plan** that has multiple parallel implement tracks.

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

@@ -80,7 +80,7 @@ In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 3. **Write** — path + frontmatter（SSOT `references/schema.yaml`）+ body（`assets/resolution-template.md`）+ YAML validate
 4. **Discoverability** — 若 root `AGENTS.md`/`CLAUDE.md` 未提 `{KNOWLEDGE_DIR}`，提议最小补充（需用户同意；拒绝则仅跳过该编辑，doc 仍写）
 5. **CONCEPTS.md** — 项目特定领域词满足 qualifying bar 时提议入 `CONCEPTS.md`（规则见 `references/concepts-vocabulary.md`）；全仓 bootstrap 归 `mstar-compound-refresh`
-6. **Indexes** — `{KNOWLEDGE_DIR}/README.md` 加行（Document / Source Plan / Description / Status）；可选 `status.json` `knowledge_refs`。**iteration-close gate**：每篇新 doc 必须 Phase 6
+6. **Indexes** — `{KNOWLEDGE_DIR}/README.md` 加行（Document / Source Plan / Description / Status）；可选 workflow snapshot plan 行 `metadata.knowledge_refs`（`{WORKFLOW_DIR}/<id>/snapshot.json`）。**iteration-close gate**：每篇新 doc 必须 Phase 6
 7. **Refresh trigger** — 新知识暗示旧 doc 过时 → 推荐 `/pm compound-refresh <scope>`（不自动跑，仅 flag）
 
 > **Engine check (when available):** run `mstar compound validate <doc-path> [--knowledge-dir <dir>]` (or `import { validateSchemaYaml, assertIndexRows } from "@mstar-harness/engine"` in a host hook) to validate the frontmatter against `references/schema.yaml` (Phase 3 Write) and assert every doc has its `{KNOWLEDGE_DIR}/README.md` index row (Phase 6 Indexes). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
@@ -92,7 +92,7 @@ In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 ## Skill dependencies
 
 - **`mstar-plan-conventions`** — path symbols（`{KNOWLEDGE_DIR}`、`{HARNESS_DIR}`）
-- **`mstar-plan-artifacts`** — `status.json` linking、index maintenance
+- **`mstar-plan-artifacts`** — workflow snapshot / project register linking、index maintenance
 - **`mstar-compound-refresh`** — capture 后知识维护；CONCEPTS.md 全仓 bootstrap
 
 ## NOT to do

package/harness-skills/mstar-compound/references/compound-workflow.md

@@ -51,7 +51,7 @@ Understand:
 - What the working solution was
 - Why the solution works (root cause)
 - Which files/modules were involved
-- The plan_id if applicable (link to `status.json`)
+- The plan_id if applicable (link to the workflow snapshot plan row)
 
 If `{KNOWLEDGE_DIR}/README.md` exists, scan its index for related existing documents.
 
@@ -92,7 +92,7 @@ date: YYYY-MM-DD
 problem_type: <enum value>
 category: <directory name>
 severity: critical|high|medium|low
-plan_id: <optional, link to status.json>
+plan_id: <optional, link to the workflow snapshot plan row>
 tags: [<keywords>]
 ---
 ```
@@ -156,7 +156,7 @@ If `CONCEPTS.md` doesn't exist yet, ask whether to seed it. A seed populates the
 1. Add a row to `{KNOWLEDGE_DIR}/README.md` index table (create if missing):
    - Document (link), Source Plan (`plan_id`), Description, Status (`Active`)
 
-2. If `plan_id` was provided, optionally update `status.json` metadata to reference this doc under `knowledge_refs`.
+2. If `plan_id` was provided, optionally update the workflow snapshot plan row (`workflows/<id>/snapshot.json` → `plans[].metadata`) to reference this doc under `knowledge_refs`.
 
 **iteration-close gate**: `mstar-iteration` §3.2 #5 — **each** new doc in the compound round must complete this phase; do not skip for lightweight captures.
 

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

@@ -15,7 +15,7 @@ Knowledge documents in `{KNOWLEDGE_DIR}` age. Code changes, conventions evolve,
 
 ## 产物与操作路径
 
-**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。本 skill 仅操作 `{HARNESS_DIR}/knowledge/**/*.md` + `{HARNESS_DIR}/knowledge/README.md` + `<repo-root>/CONCEPTS.md` + `{HARNESS_DIR}/status.json`（引用更新）。**禁止**操作 `docs/`、`{PLAN_DIR}/`、`{ITERATION_DIR}/`、`{SPECS_DIR}/`。
+**SSOT**: `mstar-plan-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.
 
@@ -51,7 +51,7 @@ For each candidate document, classify into one of five outcomes:
 | **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: `.mstar/plans/20260815-mstar-knowledge-prose-folds.md` `## Review Gate Summary` → Task evidence); length proved not to be a criterion.
+> **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
 
@@ -105,7 +105,7 @@ Classify each doc → Keep / Update / Consolidate / Replace / Delete. Apply chan
 ### Phase 4: Update indexes
 
 1. Update `{KNOWLEDGE_DIR}/README.md` index table — update Status column, add/remove rows.
-2. If doc was linked from `status.json` metadata, update references.
+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
 
@@ -146,7 +146,7 @@ Read that file from the mstar-compound skill directory before Phase 6.
 
 ## Evidence
 
-正确结果 = 每篇候选文档有明确 verdict（Keep / Update / Consolidate / Replace / Delete）并落到产物：文档改动 + `{KNOWLEDGE_DIR}/README.md` 索引更新（Phase 4）+ `status.json` 引用同步 + 维护报告（Phase 5：reviewed / kept / updated / consolidated / replaced / deleted / flagged）+ `CONCEPTS.md` 对账（Phase 6）。
+正确结果 = 每篇候选文档有明确 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
 

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

@@ -36,7 +36,7 @@ Check what already exists and note its condition:
 | `{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? | `absent` / `present` |
+| `{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.
 

package/harness-skills/mstar-dispatch-gates/SKILL.md

@@ -91,13 +91,13 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 
 - 独立模块可并行 **implement 轨道**（不同 dev Assignment）；**同仓 ≥2 可写并发** → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**（先于 invoke；同 plan 多轨 = L2）。
 - **SDD 单 plan 内**：task / implementer **仍串行**（`mstar-sdd`）；**禁止**同一 plan 内并行 SDD implementer（写冲突）。
-- **跨 plan（迭代 Phase 2）≠ 单 plan 内并行**：不同 `plan_id` 的 feature implement **允许** lease 门控并行（每 plan 独立 verified `plans[].execution_lease` + feature worktree，L1）**仅当** coordination 路径 same-host 独占写锁可用且每次协调变更持锁 → **`mstar-iteration`** §2.0 #5 · **`mstar-plan-artifacts`**。**跨主机 / 无共享 flock** → 默认 **`Plan parallelism: serial`** 或 Assignment 仍写并行 → **Blocked**（用户本轮 `Cross-host lease race: accepted` + audit `notes` 除外）。**无 flock 不豁免** control/feature worktree 或 lease。**`Worktree mode: waived` 不豁免**跨 plan 并行安全闸。**禁止**因默认 gitignore 导致 feature 缺 plans 而 waive worktree（harness 经 control 绝对路径）→ **`mstar-branch-worktree`**。**禁止**无 lease 的跨 plan 可写派发（lease 闸未 waive 时）。
+- **跨 plan（迭代 Phase 2）≠ 单 plan 内并行**：不同 `plan_id` 的 feature implement **允许** lease 门控并行（每 plan 独立 verified snapshot `plans[].execution_lease` + feature worktree，L1）**仅当** coordination 路径 same-host 独占写锁可用且每次协调变更持锁 → **`mstar-iteration`** §2.0 #5 · **`mstar-plan-artifacts`**。**跨主机 / 无共享 flock** → 默认 **`Plan parallelism: serial`** 或 Assignment 仍写并行 → **Blocked**（用户本轮 `Cross-host lease race: accepted` + audit `notes` 除外）。**无 flock 不豁免** control/feature worktree 或 lease。**`Worktree mode: waived` 不豁免**跨 plan 并行安全闸。**禁止**因默认 gitignore 导致 feature 缺 plans 而 waive worktree（harness 经 control 绝对路径）→ **`mstar-branch-worktree`**。**禁止**无 lease 的跨 plan 可写派发（lease 闸未 waive 时）。
 - **`integration_merge_lease`**：`spec_integration_branch` 上的 merge **始终串行**（一次仅一 holder）→ **`mstar-iteration`** · **`mstar-plan-artifacts`**。
 - **`Plan parallelism: serial`**：仅强制跨 plan implement **调度串行**；**不** waive control worktree / `execution_lease` / `integration_merge_lease`（`Worktree mode: waived` 才是 lease/worktree 豁免）→ **`mstar-iteration`** §2.0 #5。
 - **Plan QC tri** after SDD task loop（`Execution mode: sdd`）；**单席**仅 `inline` / hotfix。共用 `Review cwd` / `Working branch` / `plan_id` / `Review range`（**`mstar-branch-worktree`**）。
 - **Tri 同消息规则**：plan QC tri（SDD 或 Assignment 显式 `QC mode: full tri-review`）时三席 **同一条消息**、**同一套** scope 字段。
 
-> **Engine check (when available):** run `mstar worktree check <plan-id>` (L1) / `mstar worktree check --l2 --tracks <json>` (L2) (or `import { l1PreDispatchCheck, l2PreDispatchCheck } from "@mstar-harness/engine"` in a host hook) to verify the 同仓写隔离 gate above (per-track feature worktree, branch alignment) before parallel dispatch. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar worktree check <plan-id> --workflow <id>` (L1) / `mstar worktree check --l2 --tracks <json>` (L2) (or `import { l1PreDispatchCheck, l2PreDispatchCheck } from "@mstar-harness/engine"` in a host hook) to verify the 同仓写隔离 gate above (per-track feature worktree, branch alignment) before parallel dispatch. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## Specialist review-and-edit dispatch
 

package/harness-skills/mstar-engine-legacy/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: mstar-engine-legacy
+description: Morning Star 条件契约档案（engine-absent fallback）。宿主无 engine 能力（无 `mstar` CLI、无 engine import、engine 约束未激活）时需要被 engine 校验接管的 contract 全文时使用：status v1→v2 字段历史、lease claim 协议全文、各宿主 QC 座次 N=3/N=1 重述、反递归完整清单、Engine-check 样板说明。engine 约束激活（或宿主含 engine 能力）时不加载；运行时 skills 的 engine-check 指针为权威契约。
+---
+
+# mstar-engine-legacy（条件契约档案 / Engine-absent fallback）
+
+## Load Order
+
+- 先 Read **`mstar-harness-core`**（SKILL.md；冲突时以 core 为准）。
+- **条件加载**：仅当宿主**无 engine 能力**时读取本 skill 及其 references —— 无 `mstar` CLI、无 engine import、engine 约束未激活。engine 约束激活（或宿主含 engine 能力）时**不加载**：此时运行时 skills 的 engine-check 指针 + 短契约文本为权威（见 core 索引行）。
+- 本 skill 是**单一条件归档**：承接因 engine 校验而从运行时 skills 中移除的 contract 全文，engine-absent 宿主在此找回完整文本。
+
+## Scope
+
+- 归档**被承接的完整契约散文**（Task 2 displaced prose 的单一收容处）：
+  1. `status.json` v1→v2 字段历史表（字段、severity、lifecycle、jq/flock 示例）
+  2. lease claim 协议全文（claim-before-InProgress、hold/release/override、integration merge、orphan recovery、waiver）
+  3. 各宿主 QC 座次 N=3/N=1 重述（omp / opencode / cursor / codex / kimi / zcode / dsh）
+  4. 反递归完整清单（leaf executor checklist、红线、NEVER 规则）
+  5. Engine-check 样板含义（运行时 skills 中 `Engine check (when available)` blockquote 的语义与 fallback 规则）
+- 运行时 skills 只保留短指针 + engine-check 命令；完整全文一律在本 skill 的 `references/` 中（避免全仓重复）。
+
+## Workflow
+
+1. 确认触发条件：宿主**无 engine**（无 CLI / import；约束未激活）。满足才继续。
+2. 按需打开对应 reference（见下表），把其中的完整契约文本作为 fallback 应用。
+3. engine 恢复后回到运行时 skills 的指针契约，停止使用本文件作为权威。
+
+| 需要 | 打开 |
+|------|------|
+| status 字段 / severity / lifecycle / 迁移 / jq-flock 示例 | `references/status-field-history.md` |
+| lease claim 协议全文（claim / hold / merge / orphan / waiver） | `references/lease-protocol.md` |
+| 各宿主 QC 座次 N=3/N=1 重述 | `references/qc-seat-n-restatements.md` |
+| 反递归完整清单（leaf checklist + 红线） | `references/anti-recursion-checklists.md` |
+| Engine-check 样板含义与 fallback 规则 | `references/engine-check-boilerplate.md` |
+
+## Decision Rules
+
+- **不加载条件**：engine 约束激活，或宿主含 engine 能力（`mstar` CLI / engine import 可用）→ 本 skill 不加载。
+- **归档唯一性**：完整契约文本只存在于本文件；不得同时在运行时 skills 重复维护全文（运行时只放指针 + engine-check）。
+- **权威性**：engine-absent 时，本文件的完整文本是行为权威；engine-present 时，运行时 skills + engine 校验是权威，本文件不是。
+- **不改契约语义**：承接文本必须逐字保留（字段名、severity 枚举、lease 规则、N 规则、反递归清单）；只做整理与归档，不重写规则。
+
+## Evidence
+
+- 正确结果 = references 中的完整文本可独立支撑 engine-absent 宿主操作；`bun run validation:drift` 绿（skill corpus lint 通过）；`mstar skill lint skills/mstar-engine-legacy` 绿。
+- 回归 = grep 验证运行时 skills 已不再携带被承接的全文（原全文位置只剩指针 / engine-check）。
+
+## References
+
+- 本 skill 的 references（见 When Workflow 表）。
+- 权威运行时契约（engine-present 时读）：`mstar-plan-artifacts`（status v2 / register）、`mstar-iteration`、`mstar-dispatch-gates`、`mstar-host`。

package/harness-skills/mstar-engine-legacy/references/anti-recursion-checklists.md

@@ -0,0 +1,58 @@
+# Anti-recursion full checklists (archived)
+
+> Engine-absent fallback: the complete anti-recursion checklists. Engine-present hosts read `mstar-dispatch-gates` (red lines) + `mstar-roles/references/` role NEVER rules; this file is the consolidated full checklist text.
+
+## 1. Leaf executor dispatch checklist (full)
+
+> **First**: read the `**IDENTITY**` and `**CAPABILITY BOUNDARY**` blocks at the top of your Assignment. Those tell you who you ARE and what tools are NOT yours. Then read the `**You are a leaf executor. You MUST NOT:**` prohibitions. Those anti-patterns are customized for your specific role+context and are the authoritative dispatch boundaries for this assignment.
+
+**Preamble — internalize before any action:**
+
+I am a leaf executor. I personally complete all work. Task/subagent is NOT my tool. If I think about dispatching, I stop and return to my direct work or write `Blocked`.
+
+Before any Task/subagent call (if I somehow forget the preamble):
+
+1. What is my **`Execute as`**?
+2. Does the Assignment include **`Delegation: allowed (...)`**? If no → **no** Task/subagent.
+3. Is my next step a Task/subagent invoke? If yes without (2) → **stop**; use Read/Write/Shell/Edit in-session or **`Blocked`**.
+4. Is `subagent_type` equal to my `Execute as`? If yes → **forbidden** (recursive dispatch).
+5. Am I treating plain `role-id` mentions, Handoff, QA gate, Completion Report roles, or multi-plan/multi-track **design text** as invoke commands? If yes → **stop**; deliver in-session.
+6. Am I invoking because the tool exists? **Available ≠ authorized.**
+7. Need parallel work or PM-only dispatch? → **`Blocked`**; PM dispatches on the next round.
+
+If blocked, report: `## Blocked — recursive dispatch refused (<which NEVER or reason>)`.
+
+## 2. 承接方反递归红线 (NEVER / DO NOT; leaf executor 必读)
+
+下列行为易触发递归误派；`project-manager` 之外的角色一旦命中，须立即停止并改为本会话内可交付物，或 **`Blocked`** 回报 PM。**禁止**以「更高效」「Assignment 像 PM 编排」等理由绕开：
+
+- **NEVER** 在本会话内调用 Task / subagent，且其 `subagent_type` **等于**你当前的 **`Execute as`** 角色 id。
+- **NEVER** 把 Assignment 里出现的 **任何** plain `role-id` 提及、反引号 `` `<role-id>` ``、**Handoff**、**QA gate**、**Completion Report** 模板里的角色名、路由表下游角色当成「立刻 invoke」的指令；这些是**叙事 / 路由文档 / 后续 PM 编排意图**，不是命令。
+- **NEVER** 把「分解为多个计划 / 多 phase / 多 track」等**设计产物层面**的并行或拆分读成「应 invoke 与子会话数量对应的多个 subagent」。**纸面产物**由本会话写盘完成；并行**调度**由 PM 在后续轮次决定。
+- **NEVER** 因宿主**暴露**了 `Task` 或若干 `subagent_type` 名称就推断可以调用。**工具可用 ≠ 授权使用**；授权只来自 **`Delegation: allowed (...)`**。
+- **NEVER**（非 PM）主动执行 parallel-agent dispatch 来分派子代理；需要并行时回报 PM。
+- **DO NOT** 在 Assignment 缺少 `Execute as` / `Delegation` / `Who runs this turn` 时自行「补齐」为 PM；缺字段时按 **leaf executor** 解释：亲自完成或 **`Blocked`**。
+- **DO NOT** 用「Assignment 太长 / 像编排稿」当作分派依据；先交付本会话任务再回报，分派由 PM 下一轮决定。
+
+**自检（动手前）**：
+
+1. 我此刻的 **`Execute as`** 是什么？
+2. Assignment 是否写了 **`Delegation: allowed (...)`**？没有 → **禁止**任何 Task / subagent。
+3. 下一动作是不是「Task / subagent_type=…」？是 → 停手，改为 Read / Write / Shell / Edit，或 **`Blocked`**。
+4. 命中任一 NEVER → 写 `## Blocked — recursive dispatch refused (<which NEVER>)` 回报 PM，**不**继续 invoke。
+
+**Assignment 顶部反模式块**：每个 PM Assignment 开头均有 **`**You are a leaf executor. You MUST NOT:**`** 块（含 IDENTITY + CAPABILITY BOUNDARY + prohibitions），PM 按该 Assignment 的角色+上下文定制反模式清单。leaf executor 收到 Assignment 后须 **首先** 阅读该块；命中任一条 → **停止**（亲自完成或 `Blocked`）。
+
+## 3. 身份断言（leaf executor）
+
+- **你就是** `Execute as` 写的那个角色。你**不是 PM**，不是调度者，不是 parallel-agent dispatch 的使用者。
+- Task/subagent 工具即使在你的工具列表里出现，它**不属于你**。把它当作你没见过的工具 —— 不是"不能用"，是"你没有"。
+- 所有工作由你**本人**在当前会话内完成（Read / Write / Edit / Shell / Grep / Glob）。任何"这样做更高效"的想法都不构成 dispatch 的理由。
+- 遇到超出能力范围的需求 → 写 `## Blocked` 回报 PM，**不是**尝试 dispatch。Blocked 是你能发出的正确信号，dispatch 不是。
+
+## 4. Non-recursive dispatch rule (shared shape, all leaf executors)
+
+- Complete assigned work in this session.
+- Do not recursively dispatch sibling roles unless explicitly authorized via `Delegation: allowed (...)`.
+- `Execute as: {role_id}` is identity lock, not orchestration permission.
+- If required inputs are missing or prerequisites unmet, return `Blocked` to PM rather than inventing delegation.

package/harness-skills/mstar-engine-legacy/references/engine-check-boilerplate.md

@@ -0,0 +1,26 @@
+# Engine-check boilerplate explanation (archived)
+
+> Engine-absent fallback: explains what the `Engine check (when available)` blockquotes in runtime skills mean, and how the fallback rule works when the engine is absent.
+
+## What the boilerplate says
+
+Runtime skills carry short contract pointers shaped as blockquote runs that open with a bold marker reading `Engine check (when available)` followed by a colon, then give a runnable verification form, then a fail clause, then the standalone guarantee sentence:
+
+1. **Marker + command form.** The blockquote states a `mstar` CLI command or an engine-import form that validates the contract in that section. The import form references the engine package inside a host hook; the CLI form is `mstar <subcommand> <args>`. Illustrative shape (engine-present hosts only):
+
+```text
+// Engine check (when available) — import form example
+import { validateStatus } from "@mstar-harness/engine";
+```
+2. **Fail clause.** `On fail -> do not proceed; fix and re-run.` A failed engine check means the contract is violated: the operator must fix the underlying state (not paper over the violation) and re-run the check before continuing.
+3. **Standalone guarantee.** The blockquote closes with "Skill text below remains authoritative when the runtime is absent." — i.e. when the engine is not available in the host (no CLI, no import), the skill text itself (including this archive's full prose) is the contract; when the engine is available, the engine check is the authoritative enforcer and the prose is the fallback reference.
+
+## Why the archive exists
+
+When engine validators enforce a contract (status schema, lease fields, QC seat N, role binding, anti-recursion gates, path resolution, …), the runtime skills no longer need to carry the full contract prose — they keep the short pointer + the engine check. `mstar-engine-legacy` is the **single conditional archive** of that displaced full prose: engine-absent hosts read it here; engine-present hosts never load it (`mstar-harness-core` load condition).
+
+## Reading the boilerplate when the engine is absent
+
+- See the marker → read the surrounding runtime-skill text for the short contract, and open this skill's matching reference for the full prose (status fields → `status-field-history.md`; leases → `lease-protocol.md`; QC seats → `qc-seat-n-restatements.md`; anti-recursion → `anti-recursion-checklists.md`).
+- The fail clause means the same discipline applies manually: verify the artifact satisfies the contract before proceeding.
+- The standalone guarantee is why this archive is authoritative for you — the runtime skills deliberately defer the full text here.