@mstar-harness/engine 3.6.3 → 3.7.1

package/dist/sdd.d.ts

@@ -1,3 +1,4 @@
+import { type GateResult } from "./core.js";
 /**
  * Error carrying the ported script exit code so the CLI can map validation
  * failures to identical non-zero exits.
@@ -18,17 +19,41 @@ export type SddWorkspaceOptions = {
     /** Working directory for git probes; default `process.cwd()`. */
     cwd?: string;
 };
-/** Options for `taskBrief` (mirrors `$SDD_DIR` for the default out path). */
+/**
+ * Options for `taskBrief` (mirrors `$SDD_DIR` for the default out path).
+ *
+ * Bound mode (spec A3): passing
+ * `context` makes the destination an artifact gate check (before any
+ * mkdir/write), defaults the destination to `{context.sddDir}/task-N-brief.md`
+ * and returns/emits an absolute path. Without `context` the legacy helper
+ * stays explicitly UNBOUND — a context-less call has no protection claim
+ * (A3: "context-less legacy helper calls remain explicitly unbound").
+ */
 export type TaskBriefOptions = {
     sddDir?: string;
+    /** Resolved SDD execution context — binds the artifact write (A3). */
+    context?: SddExecutionContext;
+    /** Observed invocation cwd for the artifact gate; default `process.cwd()`. */
+    cwd?: string;
 };
-/** Options for `reviewPackage` (mirrors `$SDD_DIR` + git probe cwd). */
+/**
+ * Options for `reviewPackage` (mirrors `$SDD_DIR` + git probe cwd).
+ *
+ * Bound mode (spec A3): passing `context` makes the destination an artifact
+ * gate check (before any mkdir/write), defaults the git probe cwd to the
+ * context's feature worktree ("feature Git cwd, control artifact out") and
+ * returns/emits an absolute path. Without `context` the legacy helper stays
+ * explicitly UNBOUND — no protection claim.
+ */
 export type ReviewPackageOptions = {
     sddDir?: string;
+    /** Git probe cwd; bound mode defaults to `context.featureCwd`. */
     cwd?: string;
+    /** Resolved SDD execution context — binds the artifact write (A3). */
+    context?: SddExecutionContext;
 };
 /**
- * Git capture ceiling for `gitOut` / `reviewPackage` (qc3 W-2): Node's
+ * Git capture ceiling for `gitOut` / `reviewPackage` : Node's
  * default 1 MiB `maxBuffer` ENOBUFS'd on large review ranges. 64 MiB keeps
  * realistic iteration-close ranges working while bounding memory; captures
  * beyond that fail as SddScriptError via the CLI.
@@ -39,13 +64,13 @@ export declare const GIT_CAPTURE_MAX_BYTES: number;
  * the absolute path). Resolution order:
  *
  * 1. fail-closed FIRST: a linked worktree without a control root never
- *    resolves or creates any SDD tree under the feature checkout (refuses a
- *    second SDD tree; no override or probe may bypass this guard);
+ * resolves or creates any SDD tree under the feature checkout (refuses a
+ * second SDD tree; no override or probe may bypass this guard);
  * 2. explicit harness-root override (`opts.harnessDir` / `MSTAR_HARNESS_DIR`)
- *    — plan finding 2026-08-08: covers repos the status.json probe misses;
- *    resolved relative to the established root;
+ * — plan finding 2026-08-08: covers repos the status.json probe misses;
+ * resolved relative to the established root;
  * 3. `.mstarc` `[config] harness_dir` at `root` (repo-declared root;
- *    resolved against the config file's directory);
+ * resolved against the config file's directory);
  * 4. `status.json` probe at root (`.mstar` → `.agents`);
  * 5. fallback: existing `.mstar`/`.agents` dir, else `.mstar`.
  *
@@ -61,6 +86,14 @@ export declare function sddWorkspace(planId: string, opts?: SddWorkspaceOptions)
  * EOF for the last task) — a later Task heading resets the section. A
  * missing task writes an empty file then fails with exit-3
  * (`SddScriptError.exitCode === 3`).
+ *
+ * Bound mode (`opts.context`, spec A3): the artifact destination is gated
+ * with `checkSddAction` BEFORE any mkdir/write — a refused destination
+ * writes nothing — and the returned path is absolute. The INPUT is bound
+ * too: the plan file must canonicalize to the context's `planFile`, and a
+ * mismatch is refused (exit 1) before any read or write — a foreign plan's
+ * content must never land in this plan's SDD dir. Context-less calls
+ * keep the legacy unbound behavior (no protection claim).
  */
 export declare function taskBrief(planFile: string, taskN: number, outFile?: string, opts?: TaskBriefOptions): string;
 /**
@@ -69,6 +102,14 @@ export declare function taskBrief(planFile: string, taskN: number, outFile?: str
  * Both refs are validated with `git rev-parse --verify --quiet` (any ref
  * the original accepted is accepted here; the SHA-only guard is
  * `assertBaseSha`).
+ *
+ * Bound mode (`opts.context`, spec A3): the review range is probed in the
+ * context's feature worktree (feature Git cwd) while the package lands in
+ * the plan's control artifacts — gated with `checkSddAction` BEFORE any
+ * mkdir/write (a refused destination writes nothing). The returned path is
+ * absolute. Context-less calls keep the legacy unbound behavior (no
+ * protection claim); an explicit `opts.cwd` still overrides the git probe
+ * cwd in both modes.
  */
 export declare function reviewPackage(base: string, head: string, outFile?: string, opts?: ReviewPackageOptions): string;
 /**
@@ -130,3 +171,152 @@ export type StickyRulesResult = {
  * resume — that rule lives in the PM flow, not the session ledger.
  */
 export declare function implementerSessionStickyRules(input: StickyRulesInput): StickyRulesResult;
+/**
+ * Resolved SDD execution context (spec A3): where control artifacts live,
+ * where feature source edits happen, and which branch the feature checkout
+ * must be on. All paths normalized absolute (canonicalized on resolve);
+ * `planFile` / `sddDir` must resolve within the control harness and match
+ * `planId`; the feature branch/worktree must match the verified lease when
+ * an active workflow supplies one (standalone non-iteration contexts remain
+ * possible under the existing branch policy — no new global lease mandate).
+ * A declared control root is authoritative: it is never re-inferred from
+ * the feature cwd (mstar-branch-worktree «Harness path SSOT»).
+ */
+export type SddExecutionContext = {
+    planId: string;
+    /** Control harness dir (`<control-worktree>/{HARNESS_DIR}`), absolute. */
+    controlHarnessRoot: string;
+    /** Feature worktree — the required cwd for product/source edits, absolute. */
+    featureCwd: string;
+    /** Assignment Working branch checked out at `featureCwd`. */
+    workingBranch: string;
+    /** Control plan file (`{PLAN_DIR}/<plan-id>.md`), absolute. */
+    planFile: string;
+    /** Control `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/`, absolute. */
+    sddDir: string;
+};
+/** One action seam to gate with `checkSddAction` (spec A3). */
+export type SddAction = {
+    /**
+   * Observed invocation cwd — the real cwd at the seam, never an Assignment
+   * echo. Relative `target` values resolve from this cwd.
+   */
+    cwd: string;
+    /** Path the action would touch; optional for source/launch, required for artifact. */
+    target?: string;
+    kind: SddActionKind;
+};
+/** Action seam kinds (spec A3): feature source write, control artifact write, child-process launch. */
+export type SddActionKind = "source" | "artifact" | "launch";
+/**
+ * Resolve and validate a declared SDD execution context (spec A3) into a
+ * canonical context. Read-only — resolves/validates, never writes.
+ *
+ * Validation (reusing the existing machinery — never duplicated here):
+ * - shape: all paths absolute, `planId` a single safe path component
+ * (`assertSafePathComponent`);
+ * - `controlHarnessRoot` exists (declared root is authoritative — never
+ * re-inferred from the feature cwd);
+ * - `planFile` identity (basename stem = `planId`) + placement via
+ * `assertPlanWritingPath` (inside `{PLAN_DIR}` of the control harness,
+ * symlink escape checked against the canonical path);
+ * - `sddDir` canonicalizes (nearest existing ancestor on BOTH sides) to the
+ * same path as `resolveSddDir(controlHarnessRoot, planId)` — the path
+ * SSOT composition, `.mstarc` overrides included; equivalent string forms
+ * of one physical destination are valid. Composition equality on the
+ * canonical pair subsumes the escape case — a declared sddDir cannot
+ * equal the canonical composition and escape at the same time — so
+ * divergence is classified at one decision point: divergence because the
+ * declared path physically canonicalizes OUTSIDE the control harness
+ * (symlinked sdd segment routing out) is environmental →
+ * `sdd.context.sdd-dir-escape` gate fail (exit 1); any other divergence
+ * (wrong declaration) is usage (exit 2). A context matching a
+ * `.mstarc`-declared sdd base is honored wherever the repo's own path
+ * SSOT composes it — the engine never second-guesses a composition it
+ * would itself produce (`resolveSddDir` is authoritative);
+ * - `featureCwd` exists and never nests with the control checkout
+ * (`featureCwd` inside the control checkout, or the control harness
+ * inside the feature checkout, are both refused — L1 hard rules);
+ * - branch/lease: when the control harness's workflow snapshots supply a
+ * plan row from a REGISTERED ACTIVE workflow (v2 root `status.json`
+ * `workflows[]`; a retained terminal snapshot never satisfies lease
+ * enforcement, and a plan claimed by multiple active workflows fails
+ * closed), its lease is verified (`verifyPlanExecutionLease`) and the
+ * L1 checklist runs (`l1PreDispatchCheck` with the control checkout);
+ * the context must then match the verified lease exactly. Without an
+ * active lease (no row, or a non-InProgress row without lease), the
+ * standalone branch policy applies (`assertBranchAlignment`) — an
+ * InProgress row without lease is the orphan refusal.
+ *
+ * Throws `SddScriptError` — exit 2 when the declared context itself is
+ * malformed (non-absolute path, identity/composition mismatch, missing plan
+ * file), exit 1 when the environment fails the gate (missing dirs, branch
+ * mismatch, lease/orphan refusal, symlink escape). A rejected context never
+ * reaches an action check.
+ */
+export declare function resolveSddExecutionContext(input: SddExecutionContext): SddExecutionContext;
+/**
+ * Gate one action seam against a resolved context (spec A3). Read-only —
+ * a refused action performs no write and the check itself never writes.
+ *
+ * - `kind: "source"` — the observed `cwd` must sit inside the feature
+ * worktree (nested directories allowed); a relative `target` resolves from
+ * that actual cwd. Targets outside the feature — traversal, absolute
+ * elsewhere, wrong-cwd, or symlink escape — are refused before mutation.
+ * - `kind: "artifact"` — the `target` must stay inside the plan's control
+ * `sddDir` or equal the declared `planFile`; legitimate control artifact
+ * edits are allowed while arbitrary control source edits are not. A
+ * nonexistent leaf canonicalizes through its nearest existing ancestor
+ * (`canonicalizeNearestExisting`); symlink escapes are refused.
+ * - `kind: "launch"` — verifies the resolved launch destination
+ * `featureCwd` (exists + on `workingBranch` via the reused
+ * `assertBranchAlignment`); the parent's own cwd is not gated, because a
+ * launch may legitimately run from control/main — its purpose is to bind
+ * the child's starting cwd to the feature worktree. An optional `target`
+ * is checked as a source target relative to `featureCwd` (where the child
+ * will start).
+ *
+ * Violations minted here carry the `sdd.context.*` prefix; violations from
+ * the reused branch/lease helpers keep their own codes (`worktree.*`,
+ * `lease.*`, `plan-path.*`) — the rules stay single-sourced. A3 limits
+ * apply: this is a snapshot check, not a future-write lock, and offers no
+ * protection against a concurrent hostile symlink swap.
+ *
+ * API contract (task-1 review Minor 2): `context` must be a
+ * `resolveSddExecutionContext`-produced (or equivalently already-validated)
+ * context. This function gates the action seam only and does NOT
+ * re-validate the context declaration — identity, branch, lease and
+ * control/feature nesting checks run at resolve time — so a hand-assembled
+ * structurally-valid context gets no protection claim from this check
+ * alone.
+ */
+export declare function checkSddAction(context: SddExecutionContext, action: SddAction): GateResult;
+/**
+ * Bound argv launcher (spec A3):
+ * resolve + gate the context, then spawn a DIRECT executable argv — never
+ * a shell (no command-string interpolation; the argv array reaches the
+ * child literally, spaces/`$()`/backticks unchanged) — with
+ * cwd = the resolved feature worktree, inherited stdio and the inherited
+ * process environment unchanged (no HOME/CODEX_HOME edits, no credential
+ * copies). The parent's own cwd is deliberately not gated: a launch may
+ * run from control/main, and the `launch` seam validates the resolved
+ * launch destination (featureCwd + workingBranch) instead.
+ *
+ * Exit contract (Task 2 CLI mapping):
+ * - empty/invalid argv → `SddScriptError` exit 2 (usage);
+ * - context/gate failure → `SddScriptError` exit 1 (usage-class declaration
+ * errors from resolution keep their own exit 2);
+ * - spawn-not-found (ENOENT) → resolves 127;
+ * - numeric child exit → resolved unchanged (exit 7 returns 7);
+ * - child killed by signal n → resolves 128+n (SIGTERM → 143, SIGINT → 130).
+ *
+ * SIGINT/SIGTERM are forwarded to the running child; the listeners are
+ * removed once the child settles — the launcher leaves no handlers behind.
+ *
+ * A3 limits apply unchanged: the launcher binds the child's STARTING cwd;
+ * it is not a sandbox — a child can later chdir, pass an overriding cwd
+ * flag, write absolute paths elsewhere, or use host edit tooling. Other
+ * spawn errors (e.g. EACCES) reject; the CLI maps them to exit 1 with the
+ * cause in the message.
+ */
+export declare function runInSddContext(context: SddExecutionContext, argv: readonly string[]): Promise<number>;

package/dist/skill-authoring.d.ts

@@ -6,14 +6,14 @@
  * Source skills (semantic SSOT — this module implements their deterministic
  * rules, it never redefines them; roadmap §8.5 C2):
  * - `mstar-skill-authoring` SKILL.md § Frontmatter Contract — `name` stable
- *   lowercase-hyphen; `description` is the trigger contract (not a workflow
- *   summary), third person.
+ * lowercase-hyphen; `description` is the trigger contract (not a workflow
+ * summary), third person.
  * - `mstar-skill-authoring` SKILL.md § Body 必须回答的 5 问 + § 默认 Body
- *   结构 — a SKILL.md body answers five questions via key sections (Load
- *   Order, Workflow, Decision Rules, Evidence, References).
+ * 结构 — a SKILL.md body answers five questions via key sections (Load
+ * Order, Workflow, Decision Rules, Evidence, References).
  * - `mstar-skill-authoring` SKILL.md § Skill-relative script and asset
- *   paths ("skill `my-skill` → scripts/do-thing") + `mstar-host` SKILL.md
- *   § Resolve loaded skill root (per-host resolution).
+ * paths ("skill `my-skill` → scripts/do-thing") + `mstar-host` SKILL.md
+ * § Resolve loaded skill root (per-host resolution).
  *
  * The SkillsBench six principles and trigger-contract reasoning stay prompt.
  */
@@ -46,10 +46,37 @@ export declare function stripFrontmatter(text: string): string;
  * or `runtime` (canonical plus the locked `RUNTIME_HEADING_ALIASES` table
  * — shipped `mstar-*` topic skills). */
 export type FiveQuestionMode = "authoring" | "runtime";
+/** Skill-lint profile kind (spec A4): `core` = the `mstar-harness-core` hub
+ * (five-question exempt), `runtime` = shipped `mstar-*` topic skills, and
+ * `authoring` = the standard plus every non-`mstar-*`/unknown input. */
+export type SkillLintKind = "core" | "runtime" | "authoring";
+/** Classification result: the profile kind plus the five-question mode to
+ * apply — `null` mode means the five-question check is skipped entirely
+ * (core exemption only; every other check stays active). */
+export type SkillLintProfile = {
+    kind: SkillLintKind;
+    mode: FiveQuestionMode | null;
+};
+/**
+ * One lint-classification policy (spec A4
+ * the single profile SSOT the CLI, dsh and drift Guard 5 consume.
+ * Semantics preserve the CLI `skill lint` selection verbatim:
+ * - exact `mstar-harness-core` → `core` / `null` (five-question exempt by
+ * design — hub headings; frontmatter + ephemeral checks still run);
+ * - exact `mstar-skill-authoring` → `authoring` (the standard's own
+ * definition stays strict despite the `mstar-` prefix);
+ * - any other `mstar-*` → `runtime` (locked alias table applies);
+ * - unknown / non-`mstar-*` / missing identity → `authoring` (strict
+ * default — greenfield inputs are never loosened).
+ * The `skillId` is the resolved target directory basename at the CLI and
+ * dsh configured skill-root boundaries — never an arbitrary YAML `name`
+ * alone (a misleading frontmatter name must not select a looser profile).
+ * These are lint profiles only: not authorization, not trusted origin.
+ */
+export declare function classifySkillLint(skillId: string | undefined): SkillLintProfile;
 /**
- * Locked runtime alias table (plan 20260816-audit-001-five-question-runtime-
- * alignment, Step 2): heading synonyms that answer the same question for
- * shipped topic skills, verified against the corpus at `81480e7`. Tokens are
+ * Locked runtime alias table: heading synonyms that answer the same question
+ * for shipped topic skills, verified against the shipped-skill corpus. Tokens are
  * case-insensitive heading substrings (any heading level); the `decision-rules`
  * breadth is bounded by the corpus regression test pinning current state.
  * `load-order` has no aliases — the canonical label covers 15/16 skills and

package/dist/status.d.ts

@@ -14,7 +14,7 @@ export type StatusDoc = {
     [key: string]: unknown;
 };
 /**
- * v2 root status document (`{HARNESS_DIR}/status.json`, plan Task 3 — hard
+ * v2 root status document (`{HARNESS_DIR}/status.json`( — hard
  * cutover): `version`, `updated_at`, `workflows[]` only. The list holds
  * ACTIVE (non-terminal) lifecycles; terminal writers unregister AFTER the
  * snapshot write (removal-at-terminal).
@@ -96,7 +96,7 @@ export declare function validatePlanRow(row: unknown): GateResult;
  */
 export declare function validateResidual(entry: unknown): GateResult;
 /**
- * Validate one v2 root `workflows[]` entry (plan Task 3): required `id`,
+ * Validate one v2 root `workflows[]` entry (): required `id`,
  * `type` (plan | iteration), `started_at`, `dir` — harness-relative, never
  * absolute and never containing `..`. The removal-at-terminal invariant
  * (snapshot exists and is non-terminal) is checked at document level by
@@ -104,7 +104,7 @@ export declare function validateResidual(entry: unknown): GateResult;
  */
 export declare function validateWorkflowEntry(entry: unknown): GateResult;
 /**
- * Validate a v2 status.json document (plan Task 3 — hard cutover). Accepts a
+ * Validate a v2 status.json document ( — hard cutover). Accepts a
  * parsed document or a file path (malformed JSON yields a
  * `status.invalid-json` violation, never a throw). v1 or unknown-version
  * inputs — including v1-shaped documents carrying a root `plans[]` — fail
@@ -122,14 +122,14 @@ export declare function validateWorkflowEntry(entry: unknown): GateResult;
  * root holds active lifecycles only, and terminal writers unregister AFTER
  * the snapshot write. The snapshot must also PHYSICALLY live under the
  * harness: a symlinked `workflows/<id>/` (or snapshot file) resolving
- * outside the harness dir is rejected fail-closed (QC wave-1 S-f). Doc
+ * outside the harness dir is rejected fail-closed . Doc
  * input without a harness dir is structure-only.
  */
 export declare function validateStatusV2(docOrPath: StatusV2Doc | string, opts?: {
     harnessDir?: string;
 }): GateResult;
 /**
- * Relocated v2 root validator (plan Task 3 — hard cutover, no dual path):
+ * Relocated v2 root validator ( — hard cutover, no dual path):
  * the v1 `validateStatus` implementation was deleted in the same task that
  * introduced the v2 surface; the public export name survives so external
  * consumers (CLI, host hooks — cut over in P2) keep compiling and now fail
@@ -158,14 +158,14 @@ export declare const validateStatus: typeof validateStatusV2;
  * Async-only (architect-locked 2026-08-27): the durable write goes through
  * `getArtifactStore().put({ kind: "status", key: "root", ... })` inside the
  * caller's lock — the store is the persist backend, never a second lock.
- * Fails loud (qc3 F-201) when the active FsStore would resolve its
+ * Fails loud when the active FsStore would resolve its
  * `status.json` to a path other than `statusPath` — callers whose root
  * differs from the active store's root MUST
  * `setArtifactStore(createFsStore(root))` first.
  */
 export declare function registerWorkflowEntryLocked(statusPath: string, entry: WorkflowEntry): Promise<StatusV2Doc>;
 /**
- * Register one active workflow entry in the v2 root file (plan Task 3).
+ * Register one active workflow entry in the v2 root file ().
  * Idempotent upsert by entry `id` under the root-file `withStatusWriteLock`,
  * bumping root `updated_at`. A missing/empty root file is initialized from
  * the v2 template (never a v1 tree); a v1 root is refused with the
@@ -178,7 +178,7 @@ export declare function registerWorkflowEntryLocked(statusPath: string, entry: W
  */
 export declare function registerWorkflow(root: string, entry: WorkflowEntry): Promise<StatusV2Doc>;
 /**
- * Remove one workflow entry from the v2 root file (plan Task 3). Idempotent:
+ * Remove one workflow entry from the v2 root file (). Idempotent:
  * removing an absent id is a no-op with no write; a missing/empty root file
  * is a no-op that never creates the file. Runs under the root-file
  * `withStatusWriteLock`, bumping root `updated_at` only when an entry was
@@ -186,7 +186,7 @@ export declare function registerWorkflow(root: string, entry: WorkflowEntry): Pr
  * invariant included) before the write — a v1 root is refused with the
  * `mstar migrate` hint.
  *
- * Fails loud (qc3 F-201) when the active FsStore would resolve its
+ * Fails loud when the active FsStore would resolve its
  * `status.json` to a path other than the caller's root — the no-op branches
  * below never mask a store/path mismatch.
  */
@@ -199,8 +199,7 @@ export declare function unregisterWorkflow(root: string, id: string): Promise<St
  * frontmatter declares `enforcement: hard` hardens the gate in this repo.
  * A COMPLETED (or status-less/archived) iteration's compass NEVER hardens:
  * D2 rollback = unset the flag in the ACTIVE compass, and that must work
- * while older completed compasses still declare hard (qc1 F-001 / qc2 F-002).
- * A counting compass declaring a non-hard value, or no compass at all,
+ * while older completed compasses still declare hard. * A counting compass declaring a non-hard value, or no compass at all,
  * leaves the flag unset (`source: none`) — hard gates are never the default
  * and the flag is inert when the engine is absent. Frontmatter is
  * `---`-fenced; hard declarations in the compass BODY do not count (the

package/dist/store.d.ts

@@ -1,5 +1,4 @@
-/** JSON coordination-doc kinds the store persists (spec SP2). */
-export type ArtifactKind = "status" | "snapshot" | "residuals" | "review" | "json";
+/** JSON coordination-doc kinds the store persists */ export type ArtifactKind = "status" | "snapshot" | "residuals" | "review" | "json";
 /** Stable key inside the kind. Workflow id, project id, or review id;
  * `kind: "status"` always uses key `"root"`. */
 export type ArtifactRef = {
@@ -23,14 +22,13 @@ export interface ArtifactStore {
     get<T = unknown>(ref: ArtifactRef): Promise<T | undefined>;
     delete?(ref: ArtifactRef): Promise<void>;
     /** Enumerate refs of `kind`, sorted by key ascending (spec D4). Uniform
-     * rule: report what exists — missing backing dir/file → `[]`; every
-     * listed key round-trips through `get`. `json` is not enumerable. */
+   * rule: report what exists — missing backing dir/file → `[]`; every
+   * listed key round-trips through `get`. `json` is not enumerable. */
     list?(kind: ArtifactKind): Promise<ArtifactRef[]>;
 }
-/** Map an artifact ref to its file path under `harnessRoot` (spec SP2
- * FsStore path table — the single kind→path mapping, shared with SP3;
- * SP3 never re-implements or extends it). Exported (qc1 S-002) so SP3
- * imports the contract instead of re-deriving it textually. */
+/** Map an artifact ref to its file path under `harnessRoot` (the store contract — the single kind→path
+ * mapping). Exported so host adapters import the contract instead of
+ * re-deriving it textually. */
 export declare function resolveArtifactPath(harnessRoot: string, ref: ArtifactRef): string;
 /** Default local adapter: maps kinds to the existing `.mstar/` paths.
  * `put` uses the sync `writeJson` (atomic temp+rename unchanged) and
@@ -39,7 +37,7 @@ export declare function resolveArtifactPath(harnessRoot: string, ref: ArtifactRe
  * malformed JSON → throw with the path in the message. The returned store
  * also exposes its resolved `root` so the routed writers can fail loud
  * when a caller's explicit target path diverges from the store-resolved
- * path (qc3 F-201); `root` is not part of the `ArtifactStore` contract.
+ * path ; `root` is not part of the `ArtifactStore` contract.
  * `list` enumerates per the D4 table: report what exists — missing
  * backing dir/file → `[]`, `json` throws, keys sorted ascending. */
 export declare function createFsStore(harnessRoot: string): ArtifactStore & {
@@ -52,7 +50,7 @@ export declare function setArtifactStore(store: ArtifactStore | undefined): void
  * `resolveHarnessSubdir` — never a silent cwd fallback. */
 export declare function getArtifactStore(): ArtifactStore;
 /**
- * Fail-loud path-agreement guard for the routed writers (qc3 F-201): when
+ * Fail-loud path-agreement guard for the routed writers : when
  * `store` is an FsStore, resolve the path the store would compute for
  * `ref` and require it to equal `expectedPath` (the caller's explicit
  * target). A divergence means the caller's path lives outside the active
@@ -62,8 +60,7 @@ export declare function getArtifactStore(): ArtifactStore;
  * Cheap: pure path resolution, no I/O.
  */
 export declare function assertFsStorePath(store: ArtifactStore, ref: ArtifactRef, expectedPath: string): void;
-/** Load a store module from a filesystem path (spec SP2 § Injection 2–3,
- * SP2-AC6 / SP2-AC7). Resolves against cwd; rejects empty values and any
+/** Load a store module from a filesystem path (the store module-loading trust boundary). Resolves against cwd; rejects empty values and any
  * URI scheme before `import()`; throws when the file is missing. Accepts a
  * `createArtifactStore` named export, a default-exported factory, or a
  * default-exported object; the result is structurally verified (`put` +

package/dist/workflow.d.ts

@@ -1,18 +1,18 @@
 import type { GateResult } from "./core.js";
 import { type IntegrationMergeLease } from "./lease.js";
 import { type PlanRow } from "./status.js";
-/** Snapshot file name inside `workflows/<id>/` (plan Task 2 — writer contract). */
+/** Snapshot file name inside `workflows/<id>/` ( — writer contract). */
 export declare const WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
-/** Lifecycle status enum (plan Task 2 — terminal set = completed|failed|stopped). */
+/** Lifecycle status enum ( — terminal set = completed|failed|stopped). */
 export declare const WORKFLOW_LIFECYCLE_STATUSES: readonly ["running", "paused", "completed", "failed", "stopped"];
 /** Terminal statuses: snapshot must carry `ended_at` and no dangling leases. */
 export declare const WORKFLOW_TERMINAL_STATUSES: readonly ["completed", "failed", "stopped"];
-/** Lifecycle type enum (plan Task 2 — id reuses the orchestration id). */
+/** Lifecycle type enum ( — id reuses the orchestration id). */
 export declare const WORKFLOW_LIFECYCLE_TYPES: readonly ["plan", "iteration"];
 export type WorkflowLifecycleStatus = (typeof WORKFLOW_LIFECYCLE_STATUSES)[number];
 export type WorkflowLifecycleType = (typeof WORKFLOW_LIFECYCLE_TYPES)[number];
 /**
- * First-class lifecycle execution policy (plan Task 2 — keys copied from root
+ * First-class lifecycle execution policy ( — keys copied from root
  * `metadata` at migrate; values accepted-but-opaque this iteration, no
  * semantic gate).
  */
@@ -21,7 +21,7 @@ export type WorkflowExecutionPolicy = {
     worktree_mode?: unknown;
     push_policy?: unknown;
 };
-/** Iteration branch anchors (plan Task 2 — from root metadata anchors). */
+/** Iteration branch anchors ( — from root metadata anchors). */
 export type WorkflowBranchAnchors = {
     base?: string;
     integration?: string;
@@ -29,11 +29,11 @@ export type WorkflowBranchAnchors = {
 };
 /**
  * v3 workflow snapshot (`workflows/<id>/snapshot.json`) — final schema
- * (plan Task 2). `plans[]` rows are the legacy PlanRow shape verbatim;
+ * (). `plans[]` rows are the legacy PlanRow shape verbatim;
  * per-row `execution_lease` stays on the row, `integration_merge_lease` is
  * top-level.
  *
- * Notes dual-home SSOT (qc wave-1 S-e): a plan row's `notes` array is the
+ * Notes dual-home SSOT: a plan row's `notes` array is the
  * LEGACY VERBATIM copy preserved at migrate time — the RUNTIME ledger is
  * `notes.jsonl` in the workflow dir (`migrate.ts` NOTES_LEDGER_FILE). New
  * notes append to the ledger only; row `notes` is read-only legacy and is
@@ -57,7 +57,7 @@ export type WorkflowSnapshot = {
     compass_ref?: string;
 };
 /**
- * Validate a v3 workflow snapshot document (plan Task 2 — final schema):
+ * Validate a v3 workflow snapshot document ( — final schema):
  * enum/type/id checks, `schema_version: 1`, required timestamps, `plans[]`
  * rows validated by the legacy `validatePlanRow` with row-level
  * `execution_lease` shape delegated to `validateExecutionLease`,
@@ -70,16 +70,16 @@ export type WorkflowSnapshot = {
 export declare function validateWorkflowSnapshot(doc: unknown): GateResult;
 /**
  * Write a workflow snapshot as a whole-rewrite of `dir/snapshot.json` under
- * `withStatusWriteLock(snapshotPath)` (plan Task 2 — the `.status-write.lockdir`
+ * `withStatusWriteLock(snapshotPath)` ( — the `.status-write.lockdir`
  * lands inside `workflows/<id>/`, dirname of the snapshot; no harness-root
  * pollution). The snapshot is validated first — an invalid snapshot throws
  * and nothing is written. `dir` is created recursively. The durable write
- * routes through the active `ArtifactStore` (spec SP2: snapshot →
+ * routes through the active `ArtifactStore` (the store contract: snapshot →
  * `{ kind: "snapshot", key: <workflow id> }`) inside the existing lock — the
  * default FsStore resolves `{WORKFLOW_DIR}/<key>/snapshot.json`, identical
  * to `join(dir, WORKFLOW_SNAPSHOT_FILE)` for canonical callers. The write
  * fails loud when the active FsStore would resolve a different path than
- * the caller's `join(dir, WORKFLOW_SNAPSHOT_FILE)` (qc3 F-201) — callers
+ * the caller's `join(dir, WORKFLOW_SNAPSHOT_FILE)`  — callers
  * whose target root differs from the active store's root MUST
  * `setArtifactStore(createFsStore(root))` first.
  */

package/dist/worktree.d.ts

@@ -38,8 +38,7 @@ export type BranchProbeOptions = {
     /**
      * Git probe timeout in ms (default 10s; `MSTAR_GIT_PROBE_TIMEOUT_MS` env
      * overrides; per-call value wins). On timeout the probe fails closed into
-     * `branch-probe-failed` — never hangs, never guesses a branch (qc3 F-4).
-     */
+     * `branch-probe-failed` — never hangs, never guesses a branch.   */
     timeoutMs?: number;
 };
 /**
@@ -56,6 +55,27 @@ export type QcSnapshotAssignment = QcAlignmentAssignment & {
     /** Precomputed review HEAD (full SHA preferred) for that assignment. */
     head?: string;
 };
+/**
+ * True when `candidatePath` is a Git checkout DISTINCT from `controlPath` —
+ * the canonical per-worktree git dirs differ. A linked worktree from
+ * `git worktree add` (nested inside the control checkout or a sibling) has
+ * its own git dir and is distinct; the same checkout, a plain subdirectory
+ * of it, or a symlink alias of it resolves to the same git dir and is NOT
+ * distinct. Everything unprovable — a non-repo path or a probe failure —
+ * is NOT distinct: fail closed, never guess an identity.
+ */
+export declare function isDistinctCheckout(controlPath: string, candidatePath: string, opts?: BranchProbeOptions): boolean;
+/**
+ * Probe the repository top-level (worktree root) of a checkout via
+ * `git -C <path> rev-parse --show-toplevel` — bounded exactly like
+ * `probeBranch` / `probeCheckout`, fail-closed (null on any failure). The
+ * canonical top-level is the checkout root regardless of where inside it
+ * the probed path sits — a `.mstarc`-declared nested harness dir like
+ * `<control>/state/.mstar` included — so callers never infer the checkout
+ * root from `dirname(harness)` (a layout assumption that only holds when
+ * the harness sits directly under the checkout).
+ */
+export declare function probeCheckoutRoot(path: string, opts?: BranchProbeOptions): string | null;
 /**
  * L1 cross-plan pre-dispatch checklist (mstar-branch-worktree L1 table +
  * Harness path SSOT hard rules): control path recorded, feature worktree
@@ -75,11 +95,15 @@ export declare function l1PreDispatchCheck(input: L1PreDispatchInput, opts?: Bra
 export declare function l2PreDispatchCheck(input: L2PreDispatchInput, opts?: BranchProbeOptions): GateResult;
 /**
  * L1 hard rule (Harness path SSOT): `execution_lease.worktree_path` MUST
- * differ from `metadata.control_worktree_path`. String equality on the two
- * paths — canonical absolute paths are the caller's contract (the lease
- * validator already requires `worktree_path` to be absolute).
+ * be a Git checkout DISTINCT from `metadata.control_worktree_path` — the
+ * same checkout, a plain subdirectory, or a symlink alias of the control
+ * checkout is refused (checkout identity via the canonical per-worktree
+ * git dir; probe failure fails closed). Both-empty stays a match (nothing
+ * recorded, per the lease validator contract); one empty has nothing to
+ * compare and passes (the lease validator's absolute-path requirement owns
+ * empty lease paths).
  */
-export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string): GateResult;
+export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string, opts?: BranchProbeOptions): GateResult;
 /**
  * Assert the branch checked out at `worktreePath` matches `expectedBranch`
  * (the Assignment Working branch). Probe = `git -C <path> branch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.6.3",
+  "version": "3.7.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {