@mstar-harness/engine 2.4.1 → 3.0.1

package/dist/host.d.ts

@@ -9,10 +9,10 @@
  *   cursor → opencode → omp → kimi → zcode → codex ("Order matters").
  * - `mstar-host` SKILL.md § Resolve loaded skill root — per-host skill-root
  *   resolution.
- * - `.harness/references/skill-programmatic-roadmap.md` §8.4 — the
+ * - roadmap §8.4 — the
  *   `HostAdapter` shared contract (all hooks optional; no concrete adapters
  *   in the engine; pi deferred).
- * - `.harness/references/dsh-adapter-roadmap.md` §4 D5 (this iteration) —
+ * - dsh-adapter roadmap §4 D5 (this iteration) —
  *   the dsh detection row + skill-root form; mirror text lands in the
  *   mstar-host skill when this module is upstreamed.
  *

package/dist/index.d.ts

@@ -23,11 +23,15 @@
 export type { GateResult, Severity, ValidationResult } from "./core.js";
 export { SEVERITY_ORDER, applyEnforcement, readHarnessVersion, readJson, resolveProjectRoot, writeJson } from "./core.js";
 export type { HarnessKind, ResolveHarnessDirOptions, ResolveSpecsDirOptions } from "./path.js";
-export { assertPlanWritingPath, emitGitignoreSnippet, resolveHarnessDir, resolveIterationDir, resolvePlanDir, resolveSddDir, resolveSpecsDir, scaffoldHarness, validateGitignore, } from "./path.js";
-export type { ArchiveResult, FindingsCleanupMode, PlanRow, ResidualEntry, StatusDoc, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./status.js";
-export { archiveResiduals, findingsCleanupGate, normalizeSeverity, resolveCompassEnforcement, techDebtRollup, validatePlanRow, validateResidual, validateStatus, } from "./status.js";
+export type { MstarcConfig } from "./mstarc.js";
+export { MSTARC_FILE, MSTARC_HARNESS_DIR_KEY, MSTARC_PROJECT_DIR_KEY, MSTARC_SECTION, MSTARC_WORKFLOW_DIR_KEY, findMstarc, parseMstarc, } from "./mstarc.js";
+export { assertPlanWritingPath, emitGitignoreSnippet, resolveHarnessDir, resolveIterationDir, resolveKnowledgeDir, resolvePlanDir, resolveProjectDir, resolveSddDir, resolveSpecsDir, resolveWorkflowDir, scaffoldHarness, validateGitignore, } from "./path.js";
+export type { PlanRow, ResidualEntry, StatusDoc, StatusV2Doc, WorkflowEntry, } from "./status.js";
+export { normalizeSeverity, registerWorkflow, resolveCompassEnforcement, resolveMstarcEnforcement, resolveRepoEnforcement, unregisterWorkflow, validatePlanRow, validateResidual, validateStatus, validateStatusV2, validateWorkflowEntry, } from "./status.js";
 export type { ClaimLeaseFields, ExecutionLease, ExecutionLeaseLocations, IntegrationMergeLease, LeaseTransition, LeaseVerifyResult, } from "./lease.js";
 export { canSteal, claimLease, planExecutionLeaseLocations, releaseLease, sameHolderResume, validateExecutionLease, validateIntegrationMergeLease, verifyPlanExecutionLease, withStatusWriteLock, } from "./lease.js";
+export type { WorkflowBranchAnchors, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, } from "./workflow.js";
+export { WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
 export type { AssignmentBranchForms, AssignmentFields, ComposeDispatchGateOptions, ComposeDispatchGateResult, DefaultBranchOptions, EnforcementFlag, EnforcementSource, ExecutionModeToNOptions, ExecutionModeToNResult, ValidateAssignmentFieldsOptions, } from "./dispatch.js";
 export { antiRecursionPrecheck, assertDefaultBranchProtected, assertTriIdentity, assignmentHeaderRegion, composeDispatchGate, executionModeToN, isReadOnlyAssignmentRole, parseAssignmentBranchForms, parseAssignmentFields, parseBranchPolicyDirectOnBranch, parseEnforcementFlag, validateAssignmentFields, } from "./dispatch.js";
 export type { BranchProbeOptions, L1PreDispatchInput, L2PreDispatchInput, QcAlignmentAssignment, QcSnapshotAssignment, WorktreeTrack, } from "./worktree.js";
@@ -35,7 +39,11 @@ export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, l
 export type { ImplementerSessionLedger, ReviewPackageOptions, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
 export { SddScriptError, assertBaseSha, implementerSessionStickyRules, readProgressLedger, reviewPackage, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
 export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
-export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
+export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
+export type { FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
+export { PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, findingsCleanupGate, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
+export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, MigrateResult, MigrateRoadmap, MigrateRootV2, MigrateSnapshot, MigrateStep, } from "./migrate.js";
+export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";
 export { assertLightDarkParity, completenessLevel, parseDesignFrontmatter, validateDesignTokenFrontmatter, } from "./design-md.js";
 export type { AuditCategory, AuditEffort, AuditFinding, AuditPriority, AuditRisk, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, SecretFinding, } from "./audit.js";

package/dist/iteration.d.ts

@@ -1,5 +1,21 @@
 import type { GateResult, ValidationResult } from "./core.js";
-import { type StatusDoc } from "./status.js";
+/**
+ * Loose shape of a parsed workflow snapshot (`workflows/<id>/snapshot.json`).
+ * All fields are `unknown` because documents come from JSON at runtime;
+ * validators narrow them. `plans[]` rows are the legacy PlanRow shape
+ * verbatim (plan Task 2) — `findPlanRow` accepts `id` or `plan_id`.
+ *
+ * Deliberate decoupling (qc wave-1 S-f): this is a loose LOCAL re-declaration,
+ * NOT an import of `WorkflowSnapshot` from workflow.ts. This module only
+ * reads `plans[].status`; importing the full schema would add a module edge
+ * to workflow.ts (which imports status.ts, which workflow.ts cycles back
+ * through — the call-time-safe loop family stays static-edge-free this
+ * way). Keep this shape in sync manually when the snapshot schema changes.
+ */
+export type SnapshotDoc = {
+    plans?: unknown;
+    [key: string]: unknown;
+};
 /**
  * Loose shape of a parsed delivery-compass.md frontmatter. All fields are
  * `unknown` because documents come from YAML at runtime; validators narrow
@@ -63,14 +79,20 @@ export type PhaseGateResult = {
 export declare function validateCompassFrontmatter(doc: unknown): GateResult;
 /**
  * Evaluate the Phase transition gates (mstar-iteration Phase transition
- * gates table): all compass-registered plans `Done` (per statusDoc plans[]
- * status) → Phase 3 required, with the checkable subsets of the §3.1 entry
- * and §3.5 exit checklists as missing-item violations.
+ * gates table): all compass-registered plans `Done` (per the workflow
+ * snapshot plans[] status) → Phase 3 required, with the checkable subsets
+ * of the §3.1 entry and §3.5 exit checklists as missing-item violations.
+ *
+ * v3 relocation: the first doc is the workflow snapshot
+ * (`workflows/<id>/snapshot.json`); the compass stays the second input.
+ * The §3.1 residual item relocated to the project-layer
+ * `findingsCleanupGate(register, planId)` — the snapshot carries no
+ * residuals (residual close is a project-register state change).
  *
  * Pure function — git probes (`currentBranch`, `specIntegrationBranch`,
  * `prBaseBranch`) come from the caller via `opts`.
  */
-export declare function evaluatePhaseGate(statusDoc: StatusDoc, compassDoc: CompassDoc, opts?: PhaseGateOptions): PhaseGateResult;
+export declare function evaluatePhaseGate(snapshotDoc: SnapshotDoc, compassDoc: CompassDoc, opts?: PhaseGateOptions): PhaseGateResult;
 /**
  * §5.1a push-cadence probe (HARD): never push the PR head while required CI
  * is still queued/in_progress or an AI/bot review wave is running. Pure
@@ -94,9 +116,18 @@ export declare function assertIndexRowObligations(iterationsDir: string): GateRe
  * iteration-compass-template.md` Fields guide); `validateCompassFrontmatter`
  * validates the parsed doc. The engine deliberately has no YAML dependency,
  * so this hand-rolled flat-subset parser lives here — the single shared
- * parser used by the CLI and the omp `mstar_iteration_gate` tool (no fork).
+ * parser used by the CLI, the omp `mstar_iteration_gate` tool, and the
+ * roadmap validator (no fork). Path wrapper over
+ * `parseCompassFrontmatterText`.
  *
  * Throws with the file path on structural errors (no fence / unterminated
  * fence / unsupported line) so callers can fail with a precise message.
  */
 export declare function parseCompassFrontmatter(filePath: string): Record<string, unknown>;
+/**
+ * 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).
+ */
+export declare function parseCompassFrontmatterText(content: string, filePath: string): Record<string, unknown>;

package/dist/lease.d.ts

@@ -1,8 +1,10 @@
 import type { GateResult, ValidationResult } from "./core.js";
 import type { PlanRow } from "./status.js";
 /**
- * `plans[].execution_lease` (v1) — see spec header. Extra fields (e.g. the
- * real control data's `base_sha`) are allowed and preserved.
+ * `plans[].execution_lease` on a workflow snapshot's plan row (v3 data
+ * home — the snapshot's `plans[]` rows are the legacy PlanRow shape
+ * verbatim) — see spec header. Extra fields (e.g. the real control data's
+ * `base_sha`) are allowed and preserved.
  */
 export type ExecutionLease = {
     holder: string;
@@ -13,7 +15,8 @@ export type ExecutionLease = {
     [key: string]: unknown;
 };
 /**
- * Root `metadata.integration_merge_lease` (v1) — see spec header. Absent =
+ * Snapshot top-level `integration_merge_lease` (v3 — relocated from the v1
+ * root `metadata.integration_merge_lease`) — see spec header. Absent =
  * unclaimed; writers delete the key on release (never `null`/tombstone).
  */
 export type IntegrationMergeLease = {
@@ -52,9 +55,9 @@ export type LeaseTransition = {
  */
 export declare function validateExecutionLease(lease: unknown): GateResult;
 /**
- * Validate one root `metadata.integration_merge_lease` object
- * (status-and-residuals.md § Root `metadata.integration_merge_lease` (v1)):
- * required `holder` / `claimed_at` / `plan_id` / `source_branch` /
+ * Validate one snapshot top-level `integration_merge_lease` object
+ * (status-and-residuals.md § Snapshot top-level `integration_merge_lease`
+ * (v3)): required `holder` / `claimed_at` / `plan_id` / `source_branch` /
  * `target_branch`; optional `session_label`. Absent = unclaimed; `null` and
  * tombstone objects are invalid (writers delete the key on release).
  * Integration merges into `spec_integration_branch` are serial — one holder
@@ -83,7 +86,8 @@ export declare function validateIntegrationMergeLease(lease: unknown): GateResul
  *   (the written lease must itself pass the validator).
  *
  * Pure: returns the resulting row; the caller performs the locked
- * read-check-replace-verify around `status.json` and persists it.
+ * read-check-replace-verify around `workflows/<id>/snapshot.json` (v3 data
+ * home) and persists the whole snapshot.
  */
 export declare function claimLease(row: PlanRow, holder: string, fields: ClaimLeaseFields): LeaseTransition;
 /**
@@ -118,46 +122,43 @@ export declare function sameHolderResume(lease: unknown, holder: string): boolea
 export declare function canSteal(lease: unknown, holder: string, opts?: {
     userOverride?: boolean;
 }): boolean;
-/** Execution lease locations found on one plan row (SSOT + legacy read-compat). */
+/** Execution lease location found on one plan row (SSOT). */
 export type ExecutionLeaseLocations = {
     /** SSOT location: `plans[].execution_lease`. */
     row: unknown;
-    /** Legacy/hand-written read-compat location: `plans[].metadata.execution_lease`. */
-    metadata: unknown;
 };
 export declare function planExecutionLeaseLocations(row: Record<string, unknown>): ExecutionLeaseLocations;
 export type LeaseVerifyResult = {
     ok: boolean;
     violations: ValidationResult[];
-    /** The lease chosen for validation (row-level wins) — absent when neither location has one. */
+    /** The lease chosen for validation (row-level) — absent when the row has none. */
     lease?: unknown;
 };
 /**
- * Verify a plan's `execution_lease` across its two possible locations
+ * Verify a plan's `execution_lease` at its SSOT location
  * (status-and-residuals.md § `plans[].execution_lease`; ADR
  * 2026-07-22-iteration-worktree-plan-lease.md A3 — the plan row is the
  * claim/hold/release SSOT):
- * - Row-level `plans[].execution_lease` only, valid → OK.
- * - Metadata-only (`plans[].metadata.execution_lease`) → high-severity
- *   `lease.verify.non-ssot-location`: the metadata location is a
- *   legacy/hand-written read-compat fallback, NOT equivalent to SSOT
- *   success. Always a FAIL (non-zero exit) with the lease shape still
- *   validated and reported.
- * - Both locations present → `lease.verify.dual-write`: the row-level lease
- *   wins and is validated; the metadata copy must be deleted.
+ * - Row-level `plans[].execution_lease` present, valid → OK.
  * - Neither present → `lease.verify.missing` (non-InProgress) /
  *   `lease.verify.orphan` (InProgress).
  *
+ * The v1-era legacy read-compat location (`plans[].metadata.execution_lease`)
+ * is deleted in the v3 cutover: the workflow snapshot is machine-written
+ * (whole-rewrite), so the hand-written fallback is a v1 dead path — no
+ * dual-track.
+ *
  * Kept in the engine so every host hook / CLI entry / Slice-2+ consumer
  * imports ONE gate (CLI `mstar lease verify` is a thin wrapper).
  */
 export declare function verifyPlanExecutionLease(row: Record<string, unknown>, planId: string): LeaseVerifyResult;
 /**
- * Same-host exclusive write lock around `status.json` coordination writes
- * (status-and-residuals.md § "Same-host exclusive write lock (control
- * status.json)"; phase-2-worktree-lease.md § "Same-host exclusive write
- * lock"). Lease mutations and plan-status transitions that touch leases MUST
- * run inside this lock for the full read-check-replace-verify sequence.
+ * Same-host exclusive write lock around coordination writes — the root
+ * `status.json` AND `workflows/<id>/snapshot.json` (status-and-residuals.md
+ * § "Same-host exclusive write lock (control status.json)";
+ * phase-2-worktree-lease.md § "Same-host exclusive write lock"). Lease
+ * mutations and plan-status transitions that touch leases MUST run inside
+ * this lock for the full read-check-replace-verify sequence.
  *
  * Acquires by atomic `mkdir` on `<status dir>/.status-write.lockdir/`
  * (success acquires; existing dir → another writer holds the lock). While

package/dist/lint.d.ts

@@ -1,8 +1,7 @@
 /**
  * Engine lint module — deterministic lint checks ported from skill prose.
  *
- * Roadmap: `.harness/references/skill-programmatic-roadmap.md` §8.2 `lint`
- * row + §4.5 Lint layer (`simplify:` / `temporary` marker presence; SDD TDD
+ * Roadmap §8.2 `lint` row + §4.5 Lint layer (`simplify:` / `temporary` marker presence; SDD TDD
  * triple in completion reports; plan-quality-bar checks; skill frontmatter
  * contract; STRATEGY.md required sections). Skill text stays the semantic
  * SSOT (roadmap D5) — this module implements the deterministic subset and

package/dist/migrate.d.ts

@@ -0,0 +1,134 @@
+import { type ProjectRegisterDoc } from "./project.js";
+import { type StatusV2Doc } from "./status.js";
+import { type WorkflowLifecycleStatus, type WorkflowLifecycleType, type WorkflowSnapshot } from "./workflow.js";
+/** Root status file name inside `{HARNESS_DIR}` (v1 input / v2 output). */
+export declare const MIGRATE_STATUS_FILE = "status.json";
+/** Legacy v1 root copy written by migration (never deleted without it). */
+export declare const ARCHIVED_STATUS_V1_FILE = "archived/status.v1.json";
+/** Notes ledger file name inside `workflows/<id>/` (schema v1 event kinds). */
+export declare const NOTES_LEDGER_FILE = "notes.jsonl";
+/** One planned apply step (kind + source -> destination labels for dry-run). */
+export type MigrateStep = {
+    kind: "archive-status-v1" | "write-snapshot" | "write-notes" | "write-register" | "write-roadmap" | "replace-root-v2";
+    source: string;
+    destination: string;
+};
+/** One planned workflow snapshot (id = plan id or iteration id). */
+export type MigrateSnapshot = {
+    id: string;
+    type: WorkflowLifecycleType;
+    status: WorkflowLifecycleStatus;
+    /**
+     * Canonical (default-layout) harness-relative snapshot path, e.g.
+     * `workflows/<id>/snapshot.json`. The actual write target derives from
+     * `MigratePlan.workflowDir` (Phase-5 F1 — a `.mstarc` custom
+     * `workflow_dir` is honored by the executor); this field keeps the
+     * default-layout rel name for display/provenance.
+     */
+    file: string;
+    /** Provenance label (compass file / status.json row). */
+    source: string;
+    data: WorkflowSnapshot;
+};
+/** One planned notes ledger (`workflows/<id>/notes.jsonl`). */
+export type MigrateNotesFile = {
+    /** Canonical (default-layout) rel path; actual target = `plan.workflowDir` + the suffix. */
+    file: string;
+    source: string;
+    /** Serialized JSON lines (each ends with `\n` when joined). */
+    lines: string[];
+};
+/** One planned project register document (`projects/<id>/residuals.json`). */
+export type MigrateRegister = {
+    /** Canonical (default-layout) rel path; actual target = `plan.projectDir` + the suffix. */
+    file: string;
+    source: string;
+    data: ProjectRegisterDoc;
+};
+/** One planned roadmap seed (`projects/<id>/roadmap.md`). */
+export type MigrateRoadmap = {
+    /** Canonical (default-layout) rel path; actual target = `plan.projectDir` + the suffix. */
+    file: string;
+    source: string;
+    content: string;
+};
+/** The root v2 replacement (commit point; empty `workflows[]` until re-registered). */
+export type MigrateRootV2 = {
+    file: string;
+    data: StatusV2Doc;
+};
+/** Planner options (plan Task 6 — `--dry-run` returns steps, zero writes). */
+export type MigrateOptions = {
+    dryRun?: boolean;
+    /** Project id for the register/roadmap home (default `_default`). */
+    projectId?: string;
+};
+/** Full migration plan: every write is described; the executor applies it. */
+export type MigratePlan = {
+    /** Resolved harness dir. */
+    root: string;
+    /**
+     * Resolved `{WORKFLOW_DIR}` (Phase-5 F1): the `.mstarc` `[config]
+     * workflow_dir` declaration wins, else `{HARNESS_DIR}/workflows`. The
+     * snapshot/notes `file` fields below keep the canonical default-layout
+     * rel names for display/provenance; the executor derives the actual
+     * write targets from this dir so a custom layout lands where the v3
+     * runtime reads.
+     */
+    workflowDir: string;
+    /**
+     * Resolved `{PROJECT_DIR}` (Phase-5 F1): the `.mstarc` `[config]
+     * project_dir` declaration wins, else `{HARNESS_DIR}/projects`. Same
+     * canonical-`file`-vs-actual-target split as `workflowDir` for the
+     * register/roadmap writes.
+     */
+    projectDir: string;
+    dryRun: boolean;
+    /** Root status.json already at `version: 2` -> nothing to plan/apply. */
+    alreadyMigrated: boolean;
+    /** Human message (no-op reason when `alreadyMigrated`). */
+    message: string;
+    snapshots: MigrateSnapshot[];
+    notesFiles: MigrateNotesFile[];
+    register: MigrateRegister | null;
+    roadmap: MigrateRoadmap | null;
+    rootV2: MigrateRootV2;
+    archive: {
+        file: string;
+        source: string;
+    };
+    /** Informational notes surfaced in dry-run output (never silent drops). */
+    migrationNotes: string[];
+    /** Ordered apply steps (additive-first; root v2 replacement last). */
+    steps: MigrateStep[];
+};
+/** Executor result. */
+export type MigrateResult = {
+    applied: boolean;
+    message: string;
+};
+/**
+ * Pure migration planner (plan Task 6): reads the v1 tree under `root` and
+ * returns the full v2 migration plan — snapshots, notes ledgers, project
+ * register, roadmap seeds, the archived v1 copy and the root v2
+ * replacement — with an ordered step list (source -> destination). ZERO
+ * writes; the caller applies via `applyMigratePlan`.
+ *
+ * A v2 root (`status.json` `version === 2`) yields an `alreadyMigrated`
+ * plan with no steps (idempotence); `opts.dryRun` marks the plan so apply
+ * is a no-op too.
+ */
+export declare function migrateHarnessTree(root: string, opts?: MigrateOptions): MigratePlan;
+/**
+ * Execute a migration plan (plan Task 6). Additive-first ordering: the v1
+ * root is archived, workflow snapshots/notes, the project register and the
+ * roadmap are written BEFORE the root v2 replacement — the LAST step, the
+ * commit point. A failure before it leaves the v1 tree intact (re-run
+ * applies the same deterministic plan). Re-running on a v2 root, or with a
+ * `dryRun` plan, is a no-op. Every destination stays inside the harness
+ * dir; every snapshot is validated fail-closed inside `writeWorkflowSnapshot`
+ * — the writer is the authoritative validator, so the apply loop does not
+ * pre-validate (qc wave-1 S-h: a gate here would run the same O(rows) pass
+ * twice per snapshot).
+ */
+export declare function applyMigratePlan(plan: MigratePlan): Promise<MigrateResult>;

package/dist/mstarc.d.ts

@@ -0,0 +1,72 @@
+/** Canonical config file name. */
+export declare const MSTARC_FILE = ".mstarc";
+/** INI section holding the harness config. */
+export declare const MSTARC_SECTION = "config";
+/** `[config]` key declaring the harness root. */
+export declare const MSTARC_HARNESS_DIR_KEY = "harness_dir";
+/** `[config]` key declaring `{PLAN_DIR}`. */
+export declare const MSTARC_PLAN_DIR_KEY = "plan_dir";
+/** `[config]` key declaring the `{SDD_DIR}` per-plan base. */
+export declare const MSTARC_SDD_DIR_KEY = "sdd_dir";
+/** `[config]` key declaring `{ITERATION_DIR}`. */
+export declare const MSTARC_ITERATION_DIR_KEY = "iteration_dir";
+/** `[config]` key declaring `{KNOWLEDGE_DIR}`. */
+export declare const MSTARC_KNOWLEDGE_DIR_KEY = "knowledge_dir";
+/** `[config]` key declaring `{SPECS_DIR}`. */
+export declare const MSTARC_SPECS_DIR_KEY = "specs_dir";
+/** `[config]` key declaring `{WORKFLOW_DIR}` (v3 workflow lifecycle layout). */
+export declare const MSTARC_WORKFLOW_DIR_KEY = "workflow_dir";
+/** `[config]` key declaring `{PROJECT_DIR}` (v3 project roadmap/register). */
+export declare const MSTARC_PROJECT_DIR_KEY = "project_dir";
+/** `[config]` key declaring the repo hard-gate policy (`hard` / `soft`). */
+export declare const MSTARC_ENFORCEMENT_KEY = "enforcement";
+/** Parsed `.mstarc` harness config (unknown sections/keys are ignored). */
+export type MstarcConfig = {
+    /** Declared harness root, relative to the `.mstarc` directory or absolute. */
+    harnessDir?: string;
+    /** Declared `{PLAN_DIR}`. */
+    planDir?: string;
+    /** Declared `{SDD_DIR}` base (the per-plan dir joins `<plan-id>`). */
+    sddDir?: string;
+    /** Declared `{ITERATION_DIR}`. */
+    iterationDir?: string;
+    /** Declared `{KNOWLEDGE_DIR}`. */
+    knowledgeDir?: string;
+    /** Declared `{SPECS_DIR}` (authoritative — skips the candidate chain). */
+    specsDir?: string;
+    /** Declared `{WORKFLOW_DIR}` (v3 workflow snapshots live under it). */
+    workflowDir?: string;
+    /** Declared `{PROJECT_DIR}` (v3 project roadmap + register live under it). */
+    projectDir?: string;
+    /** Declared hard-gate policy — `hard` or `soft` (anything else ignored). */
+    enforcement?: "hard" | "soft";
+};
+/**
+ * Parse `.mstarc` text — minimal INI subset: `#`/`;` comments, `[section]`
+ * headers, `key=value` pairs (trimmed). Only the `[config]` section is
+ * read; unknown keys are ignored (forward compatibility). The last
+ * occurrence of a key wins; an empty value is treated as unset.
+ */
+export declare function parseMstarc(text: string): MstarcConfig;
+/**
+ * Find the nearest `.mstarc` walking up from `startDir`, never above
+ * `boundary` (find-first-stop, mirroring the `{HARNESS_DIR}` probe stop
+ * rule — plan-conventions § {HARNESS_DIR} 解析顺序: a config above the
+ * workspace root is never adopted, same class as the `~/.mstar`
+ * global-collision defect). Returns the absolute file path, or `null`.
+ */
+export declare function findMstarc(startDir: string, boundary: string): string | null;
+/** A discovered `.mstarc` plus its parsed config. */
+export type LoadedMstarc = {
+    /** Absolute path of the `.mstarc` file. */
+    file: string;
+    /** Directory containing the `.mstarc` file — base for relative values. */
+    dir: string;
+    /** Parsed `[config]` contents. */
+    config: MstarcConfig;
+};
+/**
+ * Find + parse the nearest `.mstarc` at or below `boundary` from
+ * `startDir`. Returns `null` when no config exists in scope.
+ */
+export declare function loadMstarc(startDir: string, boundary: string): LoadedMstarc | null;

package/dist/path.d.ts

@@ -27,12 +27,17 @@ export type ResolveHarnessDirOptions = {
 };
 /**
  * Resolve `{HARNESS_DIR}` per plan-conventions § {HARNESS_DIR} 解析顺序
- * (find-first-stop): `.mstar/` → `.agents/` → `.plans/`/`plans/`, walking up
- * from `startDir` but NEVER above the workspace root (`opts.workspaceRoot`,
- * default = git top-level of `startDir`). Harness candidates are
- * dir-existence (the empty-dir rule applies to `{SPECS_DIR}` only). An
- * explicit override via `opts.harnessDir` or `MSTAR_HARNESS_DIR` wins over
- * probing and short-circuits before any boundary logic.
+ * (find-first-stop): `.mstarc` `[config] harness_dir` → `.mstar/` →
+ * `.agents/` → `.plans/`/`plans/`, walking up from `startDir` but NEVER
+ * above the workspace root (`opts.workspaceRoot`, default = git top-level
+ * of `startDir`). The `.mstarc` layer: the nearest config file at or below
+ * the boundary declares `harness_dir`, resolved against the config file's
+ * own directory — no dir-existence requirement (callers may scaffold) and
+ * no boundary check on the result (explicit layers keep authority; only
+ * the config discovery walk is bounded). Harness candidates from probing
+ * are dir-existence checks (the empty-dir rule applies to `{SPECS_DIR}`
+ * only). An explicit override via `opts.harnessDir` or `MSTAR_HARNESS_DIR`
+ * wins over both and short-circuits before any boundary logic.
  *
  * Returns the absolute harness dir, or `null` when no candidate exists
  * within the workspace boundary.
@@ -50,21 +55,26 @@ export type ResolveSpecsDirOptions = {
     create?: boolean;
 };
 /**
- * Resolve `{SPECS_DIR}` per plan-conventions § {SPECS_DIR} 解析: first
- * non-empty candidate wins — `{HARNESS_DIR}/specs/` → `docs/specs/` →
- * repo-root `specs/` (repo root = parent of the harness dir), then the
- * legacy read-only `designs/` candidates (`{HARNESS_DIR}/designs/` →
- * repo-root `designs/`, § {SPECS_DIR} 解析 Legacy — 兼容读 only, never
- * created by init). A candidate that exists but holds no files is treated
- * as absent (empty-dir rule, recursive). When all candidates are absent,
- * `{HARNESS_DIR}/specs/` is created and returned (unless `create: false`).
+ * Resolve `{SPECS_DIR}` per plan-conventions § {SPECS_DIR} 解析: a
+ * `.mstarc` `[config] specs_dir` declaration is authoritative — returned
+ * directly (resolved against the config file's directory; created when
+ * `create` is not false; no candidate chain, no empty-dir rule). Otherwise
+ * the first non-empty candidate wins — `{HARNESS_DIR}/specs/` →
+ * `docs/specs/` → repo-root `specs/` (repo root = parent of the harness
+ * dir), then the legacy read-only `designs/` candidates
+ * (`{HARNESS_DIR}/designs/` → repo-root `designs/`, § {SPECS_DIR} 解析
+ * Legacy — 兼容读 only, never created by init). A candidate that exists
+ * but holds no files is treated as absent (empty-dir rule, recursive).
+ * When all candidates are absent, `{HARNESS_DIR}/specs/` is created and
+ * returned (unless `create: false`).
  */
 export declare function resolveSpecsDir(harnessDir: string, opts?: ResolveSpecsDirOptions): string;
 /**
  * Compose `{PLAN_DIR}` from the harness dir (plan-conventions § 路径符号).
- * Legacy layout: when the harness root is a plans dir itself (`.plans/` or
- * `plans/`, resolution rung 3), `{HARNESS_DIR}={PLAN_DIR}` — the same
- * directory is returned.
+ * A `.mstarc` `[config] plan_dir` declaration wins (resolved against the
+ * config file's directory). Legacy layout: when the harness root is a plans
+ * dir itself (`.plans/` or `plans/`, resolution rung 3),
+ * `{HARNESS_DIR}={PLAN_DIR}` — the same directory is returned.
  */
 export declare function resolvePlanDir(harnessDir: string): string;
 /**
@@ -77,16 +87,46 @@ export declare function resolvePlanDir(harnessDir: string): string;
 export declare function assertSafePathComponent(value: string, what: string): void;
 /**
  * Compose `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/` (plan-conventions
- * § 路径符号). The per-plan directory is created by the sdd workspace flow,
- * not here. `planId` must be a single safe path component (traversal
- * guard) — see `assertSafePathComponent`.
+ * § 路径符号). A `.mstarc` `[config] sdd_dir` declaration replaces the
+ * `sdd` base (the `<plan-id>` segment is still appended). The per-plan
+ * directory is created by the sdd workspace flow, not here. `planId` must
+ * be a single safe path component (traversal guard) — see
+ * `assertSafePathComponent`.
  */
 export declare function resolveSddDir(harnessDir: string, planId: string): string;
 /**
  * Compose `{ITERATION_DIR}` = `{HARNESS_DIR}/iterations/` (plan-conventions
- * § 路径符号).
+ * § 路径符号). A `.mstarc` `[config] iteration_dir` declaration wins
+ * (resolved against the config file's directory).
  */
 export declare function resolveIterationDir(harnessDir: string): string;
+/**
+ * Compose `{KNOWLEDGE_DIR}` = `{HARNESS_DIR}/knowledge/` (plan-conventions
+ * § 路径符号). A `.mstarc` `[config] knowledge_dir` declaration wins
+ * (resolved against the config file's directory).
+ */
+export declare function resolveKnowledgeDir(harnessDir: string): string;
+/**
+ * Resolve `{WORKFLOW_DIR}` — default `{HARNESS_DIR}/workflows/`
+ * (v3 workflow lifecycle layout: snapshot.json + notes per workflow id).
+ * A `.mstarc` `[config] workflow_dir` declaration wins (resolved against
+ * the config file's directory). The dir need not exist — writers
+ * (`writeWorkflowSnapshot` / register paths) create it on demand.
+ *
+ * Deferred-by-design (qc1 S-3): the startDir-first signature is asymmetric
+ * with the harnessDir-first sibling resolvers — brief-mandated for the CLI
+ * consumer (it probes from the cwd). Revisit with a harness-dir-first
+ * variant when a third v3 subdir resolver appears.
+ */
+export declare function resolveWorkflowDir(startDir?: string, opts?: ResolveHarnessDirOptions): string;
+/**
+ * Resolve `{PROJECT_DIR}` — default `{HARNESS_DIR}/projects/` (v3 project
+ * layer: roadmap.md + residuals register per project id). A `.mstarc`
+ * `[config] project_dir` declaration wins (resolved against the config
+ * file's directory). Same deferred-by-design signature asymmetry as
+ * `resolveWorkflowDir` (qc1 S-3).
+ */
+export declare function resolveProjectDir(startDir?: string, opts?: ResolveHarnessDirOptions): string;
 /**
  * Initialize the harness directory under `root`: create `.mstar/` with
  * `plans/`, `iterations/`, `knowledge/`, `specs/`, `sdd/` and write