@mstar-harness/engine 3.9.2 → 3.9.4

package/dist/index.d.ts

@@ -9,7 +9,8 @@
  * the execution/merge lease state machines + same-host status write lock,
  * `dispatch` implements the Assignment field contract, default-branch
  * gate, QC seat mapping and tri-identity/anti-recursion prechecks, `lint`
- * implements marker/TDD-triple/plan-quality/frontmatter/STRATEGY checks,
+ * implements marker/TDD-triple/plan-quality/frontmatter/STRATEGY checks and
+ * ephemeral/provenance citation discovery,
  * `design-md` validates DESIGN.md token frontmatter + light/dark parity +
  * completeness levels, `audit` validates audit Status blocks, redacts
  * secrets and scaffolds audit-<date>/ plan dirs, and `compound` validates
@@ -70,8 +71,8 @@ export type { AuditCategory, AuditConfidence, AuditEffort, AuditFinding, AuditPr
 export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditStatusBlocks, } from "./audit.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
 export type { ReferenceCheckResult } from "./compound.js";
-export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
-export { assertSddTddTriple, findEphemeralCitations, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
+export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, ProvenanceCitation, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
+export { assertSddTddTriple, findEphemeralCitations, findProvenanceCitations, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
 export type { DevTrackParam, QcReviewerParam, RoleFamily, RoleMappingEntry, RoleMappingOptions, } from "./roles.js";
 export { DEV_TRACK_PARAMS, QC_REVIEWER_PARAMS, ROLE_MAPPING, SHARED_FAMILIES, lintLoadOrder, validateRoleMapping, } from "./roles.js";
 export type { DetectResult, HostAdapter, HostId, SkillRootPaths, ToolSignal } from "./host.js";
@@ -86,3 +87,5 @@ export type { ArtifactDoc, ArtifactKind, ArtifactRef, ArtifactStore } from "./st
 export { assertFsStorePath, createFsStore, getArtifactStore, loadStoreModule, resolveArtifactPath, setArtifactStore } from "./store.js";
 export { collectActiveLifecycleBranches, scanActiveLifecycleBranches, type ActiveLifecycleScan } from "./lifecycle-branches.js";
 export { WorkflowSnapshotValidationError } from "./workflow.js";
+export { CoordinationError, bindPlanSession, mutatePlanCoordination, readCoordinatedArtifact, readPlanCoordination, readSessionEnvelope, replaceCoordinatedArtifact, resolvePlanScope, resolveProcessHarnessDir, } from "./coordination.js";
+export type { BindPlanSessionInput, CoordinatedReplacement, CoordinationRequest, CoordinationResult, CoordinationRole, CoordinationSession, HandoffEvidence, PlanCoordinationOperation, PlanCoordinationView, PlanScopeInput, PrepareCoordinationRequest, ProgressCoordinationRequest, ResidualAddCoordinationRequest, ResidualCloseCoordinationRequest, ResidualInput, ResolvedPlanScope, VersionedArtifact, } from "./coordination.js";

package/dist/iteration.d.ts

@@ -157,7 +157,6 @@ export declare function parseCompassFrontmatter(filePath: string): Record<string
 /**
  * Parse flat-subset YAML frontmatter from raw file content — the single
  * shared parser core behind `parseCompassFrontmatter` (path wrapper) and
- * the roadmap validator (plan `20260819-workflow-engine-core.md` Task 4 —
- * extract/reuse the same parsing, no fork).
+ * the roadmap validator (extract/reuse the same parsing, no fork).
  */
 export declare function parseCompassFrontmatterText(content: string, filePath: string): Record<string, unknown>;

package/dist/lease.d.ts

@@ -42,7 +42,7 @@ export type ClaimLeaseFields = {
 export type LeaseTransition = {
     ok: boolean;
     row: PlanRow;
-    outcome?: "claimed" | "resumed" | "released";
+    outcome?: "claimed" | "resumed" | "released" | "transferred";
     violations: ValidationResult[];
 };
 /**
@@ -103,6 +103,18 @@ export declare function claimLease(row: PlanRow, holder: string, fields: ClaimLe
  * protocol); the caller enforces that ordering around the locked update.
  */
 export declare function releaseLease(row: PlanRow, holder: string): LeaseTransition;
+/**
+ * Holder transfer for the scoped coordination `accept` transition (spec §D):
+ * move an ACTIVE `execution_lease` to another holder verbatim — same
+ * `claimed_at`, `worktree_path`, `working_branch`, extra fields preserved;
+ * only `holder` changes. Deliberately NOT `claimLease`: there is no
+ * Todo/Blocked → InProgress transition and no steal path here. The locked
+ * coordination writer has already authenticated the receiving holder as the
+ * workflow's coordinator, so `from` must still match the stored holder — a
+ * mismatched `from` is `lease.transfer.other-holder` and leaves the row
+ * untouched.
+ */
+export declare function transferLease(row: PlanRow, from: string, to: string): LeaseTransition;
 /**
  * Same-holder resume check (status-and-residuals.md § Claim-before-`InProgress`
  * #2): `true` iff the stored lease `holder` equals the session `holder`.

package/dist/lint.d.ts

@@ -126,8 +126,8 @@ export type EphemeralCitation = {
  * concrete instance → reported (`task-2-report`, `task-1.diff`).
  * Placeholders (`task-N-brief`, `task-N-report`, `<plan-id>`,
  * `{SDD_DIR}/task-N-report.md`) never match.
- * - `.mstar/sdd/<segment>` / `.agents/sdd/<segment>` with a concrete first
- * segment (`20260815-x`) → reported; `<plan-id>` / `{SDD_DIR}` segments
+ * - `.mstar/sdd/<segment>` / `.agents/sdd/<segment>` with a concrete dated
+ * first segment → reported; `<plan-id>` / `{SDD_DIR}` segments
  * are template forms → never match.
  *
  * Discovery only — a finder returning an array, same shape as
@@ -137,6 +137,54 @@ export type EphemeralCitation = {
  * 1-based line order, source order within a line.
  */
 export declare function findEphemeralCitations(skillText: string): EphemeralCitation[];
+/**
+ * A provenance citation found in text: a dated plan/iteration id token, or a
+ * local-harness deeplink whose specificity comes from a dated instance
+ * segment. Both disclose local artifact provenance, which tracked code and
+ * docs must not carry (repo AGENTS.md "Git and local artifacts": tracked
+ * content must not disclose real plan/iteration ids or local deep paths;
+ * synthetic example forms and generic layout lines are exempt).
+ */
+export type ProvenanceCitation = {
+    /** 1-based line number of the citation. */
+    line: number;
+    /** The matched citation token (dated plan id or deeplink path). */
+    match: string;
+    /** `plan-id`: a dated-slug plan/iteration id token; `harness-path`: a
+     * local-harness deeplink containing a dated token. */
+    kind: "plan-id" | "harness-path";
+};
+/**
+ * Find provenance citations in text (repo AGENTS.md "Git and local
+ * artifacts": tracked code and docs must not depend on local harness
+ * artifacts or disclose their provenance with real plan/iteration ids or
+ * local deep paths).
+ *
+ * Discrimination (HARD — zero false positives on the skills corpus):
+ * - `plan-id`: a dated-slug token (`20991231-<slug>`; the dated token
+ *   inside `iter-20990101-<slug>` counts). Synthetic example
+ *   slugs (`20991231-example-plan`, `20260717-example`) are never reported;
+ *   a token followed by a `.digits` version segment (`20260908-v3.9.0`) is
+ *   a version, not a plan id; placeholder shapes (`task-N-*`, `<plan-id>`,
+ *   `{…}`) never match the digit-anchored form.
+ * - `harness-path`: a `.mstar/…` / `.agents/…` deeplink containing a
+ *   qualifying dated token — the dated instance segment carries the
+ *   specificity, so generic layout lines (`.mstar/plans/`,
+ *   `.mstar/status.json`, `.mstar/knowledge/<category>/`) are never
+ *   reported.
+ * - Attribution (single decision, shared with `findEphemeralCitations`):
+ *   sdd deeplinks (first segment `sdd`, the SDD_DEEPLINK_RE face) belong to
+ *   the ephemeral check exclusively; a dated token inside any harness path
+ *   is reported at most once — as `harness-path` for non-sdd paths, never
+ *   by this finder for sdd paths. Undated concrete path segments are out of
+ *   scope (shape ambiguity — prose/review territory, like merge SHAs).
+ *
+ * Discovery only — a finder returning an array, same shape as
+ * `findEphemeralCitations`; callers wrap findings into `ViolationResult`s.
+ * Citations are reported line by line in 1-based line order, source order
+ * within a line.
+ */
+export declare function findProvenanceCitations(text: string): ProvenanceCitation[];
 /**
  * Validate task report evidence: an explicit scoped-check declaration for
  * document/policy checks, otherwise the executable-change TDD triple.

package/dist/migrate.d.ts

@@ -84,6 +84,14 @@ export type MigratePlan = {
    */
     projectDir: string;
     dryRun: boolean;
+    /**
+     * Byte version (`sha256:…`, or `"absent"`) of the source `status.json` this
+     * plan was derived from (spec §C3 source-version CAS). The executor
+     * re-reads the source under the root lock before its first write and
+     * refuses a root whose bytes moved after planning — a still-v1 document
+     * changed by another writer is never silently replaced.
+     */
+    sourceVersion: string;
     /** Root status.json already at `version: 2` -> nothing to plan/apply. */
     alreadyMigrated: boolean;
     /** Human message (no-op reason when `alreadyMigrated`). */

package/dist/path.d.ts

@@ -1,4 +1,4 @@
-import { type ValidationResult } from "./core.js";
+import type { ValidationResult } from "./core.js";
 /**
  * Options for `resolveHarnessDir`.
  */
@@ -11,8 +11,8 @@ export type ResolveHarnessDirOptions = {
    */
     harnessDir?: string;
     /**
-   * Workspace-root stop boundary (roadmap §7c / plan
-   * 20260810-harness-root-boundary). The upward probe keeps walking only
+   * Workspace-root stop boundary (roadmap §7c). The upward probe keeps
+   * walking only
    * while `dir` is at or below this root — a harness dir above it is never
    * returned (the `~/.mstar` global-collision defect is the special case).
    * Resolved against `startDir` when relative. When omitted, the default
@@ -164,11 +164,20 @@ export declare function resolveScaffoldDirs(root: string): {
  * `.mstarc`-declared `project_dir`) with a valid `roadmap.md` + empty
  * `residuals.json` (plan-conventions § 初始化 Plan 目录;
  * mstar-project-governance § `_default` 回退). Idempotent: an existing
- * non-empty `status.json`, `roadmap.md`, or `residuals.json` is never
- * clobbered; re-running on an initialized tree only creates missing
- * pieces. Returns the absolute resolved harness dir.
- */
-export declare function scaffoldHarness(root: string): string;
+ * `roadmap.md` is never clobbered, and re-running on an initialized tree only
+ * creates missing pieces. Returns the absolute resolved harness dir.
+ *
+ * The two coordination documents (`status.json`, `_default/residuals.json`)
+ * are written create-only through the active `ArtifactStore` inside the
+ * private protected-write context, serialized on the target's
+ * `withStatusWriteLock` (spec §C4): a concurrent writer's bytes are never
+ * replaced, and an existing empty/malformed document fails validation instead
+ * of being silently reinitialized. Callers whose target root differs from the
+ * active store's root MUST `setArtifactStore(createFsStore(<harnessRoot>))`
+ * first (same contract as the other routed writers). No scoped session or
+ * coordination record is created here.
+ */
+export declare function scaffoldHarness(root: string): Promise<string>;
 /**
  * Harness kind for the gitignore fence — the canonical snippet is per
  * harness layout (plan-conventions § Git 跟踪策略): `.mstar/` (default) and

package/dist/project.d.ts

@@ -199,8 +199,8 @@ export declare function findingsCleanupGate(register: ProjectRegisterDoc, planId
  */
 export declare function techDebtRollup(projectDir: string): TechDebtRollup;
 /**
- * List theme-scoped research files under `<projectDir>/references/` (plan
- * 20260820-project-research-corpus Task 1 — compass ruling 1): top-level
+ * List theme-scoped research files under `<projectDir>/references/`
+ * (compass ruling 1): top-level
  * files plus files exactly one subdirectory deep; deeper nesting ignored;
  * directories never listed; regular files only (`Dirent.isFile()`). Returns
  * paths relative to the references root with `/` separators, sorted by code

package/dist/status.d.ts

@@ -63,6 +63,18 @@ export type PlanRow = {
     execution_lease?: unknown;
     [key: string]: unknown;
 };
+/**
+ * Every plan id a `plans[]` row can be addressed by (status-and-residuals.md
+ * § Compatibility: read accepts `id` or the legacy `plan_id`; write prefers
+ * `id`). Both non-empty keys are reported, in canonical-first order: a row
+ * whose two keys disagree is ambiguous (`status.plan-row.dual-id`), and an
+ * ownership guard keyed on one of them would let the other escape protection.
+ * Empty strings never count; a non-object or a row carrying neither key has
+ * no address.
+ */
+export declare function rowPlanIds(row: unknown): string[];
+/** The canonical single plan id of a row — `id`, else legacy `plan_id`. */
+export declare function rowPlanId(row: unknown): string | undefined;
 /**
  * Normalize a residual `severity` value for reading/rolling up
  * (status-and-residuals.md § severity 5 + rollup `norm_sev`):
@@ -156,6 +168,11 @@ export declare const validateStatus: typeof validateStatusV2;
  * an invalid entry would fail `validateStatusV2` anyway, but the explicit
  * gate keeps the pre-lock fail-fast contract of `registerWorkflow`).
  *
+ * Replacing an existing entry additionally takes that entry's snapshot lock
+ * (spec §C3 root → snapshot order, `withRegisteredSnapshotLock`) and holds it
+ * across the root write; callers must therefore hold the root lock only, not
+ * a snapshot lock.
+ *
  * 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.
@@ -185,7 +202,10 @@ export declare function registerWorkflow(root: string, entry: WorkflowEntry): Pr
  * `withStatusWriteLock`, bumping root `updated_at` only when an entry was
  * actually removed. The final document is validated (removal-at-terminal
  * invariant included) before the write — a v1 root is refused with the
- * `mstar migrate` hint.
+ * `mstar migrate` hint. Removing a registered entry additionally takes that
+ * entry's snapshot lock (spec §C3 root → snapshot order) and holds it across
+ * the root write, so the coordination check cannot be raced by a concurrent
+ * bind.
  *
  * Fails loud when the active FsStore would resolve its
  * `status.json` to a path other than the caller's root — the no-op branches

package/dist/workflow.d.ts

@@ -1,4 +1,5 @@
 import type { GateResult, ValidationResult } from "./core.js";
+import { type SnapshotCoordination } from "./coordination-write.js";
 import { type IntegrationMergeLease } from "./lease.js";
 import { type PlanRow } from "./status.js";
 /** Snapshot file name inside `workflows/<id>/` ( — writer contract). */
@@ -63,7 +64,17 @@ export type WorkflowSnapshot = {
     integration_worktree_path?: string;
     legacy_metadata?: Record<string, unknown>;
     compass_ref?: string;
+    /**
+     * Snapshot-level coordination block ( — scoped plan-PM coordination).
+     * Present only on a coordinated lifecycle: it carries the workflow's
+     * coordinator binding (session id + canonical envelope path). The block
+     * is validated strictly (`validateSnapshotCoordination`) and may only be
+     * changed by the locked coordination writer.
+     */
+    coordination?: SnapshotCoordination;
 };
+/** Stable JSON for change detection (sorted keys, recursive). */
+export declare function stableJson(value: unknown): string;
 /**
  * Validate a v3 workflow snapshot document ( — final schema):
  * enum/type/id checks, `schema_version: 1`, required timestamps, `plans[]`
@@ -114,8 +125,34 @@ export declare class WorkflowSnapshotValidationError extends Error {
 }
 export declare function readWorkflowSnapshot(dir: string): WorkflowSnapshotRead;
 /**
- * Write a workflow snapshot as a whole-rewrite of `dir/snapshot.json` under
- * `withStatusWriteLock(snapshotPath)` ( — the `.status-write.lockdir`
+ * Writer contract (spec §C4). `expectedVersion` is the CAS token — the exact
+ * on-disk artifact version (`sha256:<64 hex>`), or `"absent"` for
+ * create-only. `createOnly` is the locked `absent` shorthand used by the
+ * scaffold/migrate/audit writers: an existing document (even an empty or
+ * malformed one) is never silently replaced.
+ *
+ * Omitting `expectedVersion` means create-only, NOT "replace whatever is
+ * there": there is no missing-version compatibility fallback, so an existing
+ * snapshot still refuses with `coordination.expected-version-required`.
+ *
+ * The delta allowed here is `phase` + `updated_at` and nothing else — a
+ * coordinator persists its phase projection through this writer without ever
+ * gaining a backdoor to row owners, leases, lifecycle scalars or branch
+ * anchors. Lifecycle terminal changes belong to `closeWorkflow` (spec §C4).
+ */
+export type WriteWorkflowSnapshotOptions = {
+    expectedVersion?: string;
+    createOnly?: boolean;
+    /**
+     * Canonical coordinator session envelope path (spec §C4). Required when the
+     * stored snapshot is coordinated: only the snapshot's own bound coordinator
+     * may pass, and the `coordination` block itself is never part of the delta.
+     */
+    sessionPath?: string;
+};
+/**
+ * Write a workflow snapshot as a field-scoped update of `dir/snapshot.json`
+ * under `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
@@ -128,14 +165,26 @@ export declare function readWorkflowSnapshot(dir: string): WorkflowSnapshotRead;
  * whose target root differs from the active store's root MUST
  * `setArtifactStore(createFsStore(root))` first.
  */
-export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string): Promise<void>;
+export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string, opts?: WriteWorkflowSnapshotOptions): Promise<void>;
 /** Terminal enum predicate only; callers validate document shape separately. */
 export declare function isTerminalSnapshot(doc: WorkflowSnapshot): boolean;
 export type CloseWorkflowOptions = {
     endedAt: string;
+    /**
+     * Canonical coordinator session envelope path (spec §C4). Required when the
+     * stored snapshot is coordinated: the close writes the snapshot, so only the
+     * snapshot's own bound coordinator may pass. A missing/mismatched envelope
+     * refuses the close with `coordination.session-mismatch` before anything is
+     * written. Non-coordinated snapshots ignore it; an already-terminal snapshot
+     * is returned unchanged (no write, no authorization needed).
+     */
+    sessionPath?: string;
 };
 /**
  * Complete the latest snapshot under its write lock. Never releases leases.
  * A valid terminal snapshot is returned unchanged, including failed/stopped.
+ * A coordinated snapshot is closed only by its own bound coordinator
+ * (spec §C4) — the same envelope seam as `writeWorkflowSnapshot` — so a plan
+ * actor or a bare CLI call can never complete a lifecycle it does not own.
  */
 export declare function closeWorkflow(workflowId: string, dir: string, opts: CloseWorkflowOptions): Promise<WorkflowSnapshot>;

package/package.json

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