@mstar-harness/engine 3.6.3 → 3.7.1

package/dist/gates.d.ts

@@ -0,0 +1,69 @@
+import { type ValidationResult } from "./core.js";
+/** Target paths from a write/edit event: `input.path` (string) plus `input.paths` (array). */
+export declare function eventTargetPaths(input: unknown): string[];
+/** Gated harness coordination documents in v3 (compass ruling 7 — hard
+ * cutover): the root `status.json` (v2), workflow snapshots
+ * (`workflows/<id>/snapshot.json`) and project registers
+ * (`projects/<id>/residuals.json`). Each kind maps to its engine
+ * validator; everything else is not a gated coordination write. */
+export type HarnessDocKind = "status" | "snapshot" | "register";
+/**
+ * Classify `targetPath` as a canonical `{HARNESS_DIR}` coordination
+ * document: basename is `status.json` at the harness root, `snapshot.json`
+ * under `{WORKFLOW_DIR}/<id>/`, or `residuals.json` under
+ * `{PROJECT_DIR}/<id>/` (harness-relative, one path component each), AND
+ * the harness root resolves — marker probe first (custom-layout-aware
+ * Phase-5 F1), `resolveHarnessDir` as the declared-root fallback. The
+ * snapshot/register rel is computed against the RESOLVED layout dirs
+ * (`.mstarc` `workflow_dir`/`project_dir` honored, defaults
+ * `workflows`/`projects`), so a custom layout classifies at the same
+ * location the runtime writes. Everything else is not a gated write.
+ * Returns the harness dir + doc kind when gated.
+ */
+export declare function harnessDocKindOfTarget(targetPath: string): {
+    harnessDir: string;
+    kind: HarnessDocKind;
+} | null;
+export declare function violationLine(violation: ValidationResult): string;
+/**
+ * Size guard: content strings beyond ~2MB are skipped without
+ * parsing — a pathologically large write must not approach a host's
+ * handler timeout (which fails CLOSED even in soft mode). The oversized
+ * write passes silently; documented in the host gate contract.
+ */
+export declare const MAX_STATUS_CONTENT_LENGTH: number;
+/**
+ * Options for {@link validateStatusWriteDoc}.
+ */
+export interface ValidateStatusWriteDocOptions {
+    /**
+     * Behavior when the content (string form) or the on-disk gated document
+     * (edit form) exceeds `MAX_STATUS_CONTENT_LENGTH`. `"pass"` (default)
+     * keeps the documented silent-pass degradation; `"violate"` reports a
+     * `status.oversized` violation instead — for hosts whose block dialect
+     * makes the oversized write an enforceable refusal rather than a
+     * permission (the size check stays O(1), before any parse).
+     */
+    oversized?: "pass" | "violate";
+}
+/**
+ * Validate the document being written to a gated harness coordination
+ * document. `content` as a string is the new document: JSON.parse it
+ * and run the matching engine validator on the parsed doc — a parse failure
+ * is a violation (`status.invalid-json`, the same code/message shape the
+ * engine emits for an unparseable file). Parsed `null` / non-object / array
+ * content is a `status.invalid-json` violation too (the JSON
+ * literal `null` would otherwise slip through `validateStatus`'s
+ * destructuring into the outer catch's silent pass). Without a content
+ * string (edit-style events) the on-disk file is validated — unless it does
+ * not exist yet (fresh scaffold/init write): nothing to validate, silent
+ * pass. Never throws (the validators catch their own read errors).
+ */
+export declare function validateStatusWriteDoc(content: unknown, filePath: string, kind: HarnessDocKind, options?: ValidateStatusWriteDocOptions): ValidationResult[];
+/**
+ * Format the gate block reason: one `violationLine` per violation, each
+ * suffixed with the host's skill pointer (omp/ZCode parity: both hosts
+ * pass `skill: mstar-artifacts/references/status-and-residuals.md`),
+ * joined with newlines.
+ */
+export declare function formatStatusWriteBlockReason(violations: ValidationResult[], skillPointer: string): string;

package/dist/gates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -20,15 +20,18 @@
  * constants (mstar-audit pr-review.md § Tally and derived score), `host`
  * detects the active
  * host from tool shapes, resolves skill roots and defines the type-only
- * `HostAdapter` contract, and `skill-authoring` lints frontmatter +
+ * `HostAdapter` contract, `gates` is the host-neutral coordination-write
+ * gate core (target classification + content/edit validation + reason
+ * formatting, shared by the omp and ZCode host gates), and `skill-authoring`
+ * lints frontmatter +
  * 5-question bodies and resolves skill-relative asset paths.
  */
 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 type { HarnessKind, ResolveHarnessDirOptions, ResolveSpecsDirOptions, } from "./path.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, detectHarnessKind, emitGitignoreSnippet, resolveHarnessDir, resolveIterationDir, resolveKnowledgeDir, resolvePlanDir, resolveProjectDir, resolveScaffoldDirs, resolveSddDir, resolveSpecsDir, resolveWorkflowDir, scaffoldHarness, validateGitignore, } from "./path.js";
+export { assertPlanWritingPath, canonicalizeNearestExisting, detectHarnessKind, emitGitignoreSnippet, resolveHarnessDir, resolveIterationDir, resolveKnowledgeDir, resolvePlanDir, resolveProjectDir, resolveScaffoldDirs, 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";
@@ -38,13 +41,15 @@ export { WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHO
 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";
-export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, l1PreDispatchCheck, l2PreDispatchCheck, singleReviewSnapshot, } from "./worktree.js";
-export type { ImplementerSessionLedger, ReviewPackageOptions, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
-export { GIT_CAPTURE_MAX_BYTES, SddScriptError, assertBaseSha, implementerSessionStickyRules, readProgressLedger, reviewPackage, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
+export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, isDistinctCheckout, l1PreDispatchCheck, l2PreDispatchCheck, probeCheckoutRoot, singleReviewSnapshot, } from "./worktree.js";
+export type { ImplementerSessionLedger, ReviewPackageOptions, SddAction, SddActionKind, SddExecutionContext, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
+export { GIT_CAPTURE_MAX_BYTES, SddScriptError, assertBaseSha, checkSddAction, implementerSessionStickyRules, readProgressLedger, resolveSddExecutionContext, reviewPackage, runInSddContext, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
 export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
 export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
 export type { AppendProjectRegisterEntriesOpts, CloseProjectRegisterEntryOpts, FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
 export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, appendProjectRegisterEntries, closeProjectRegisterEntry, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
+export type { HarnessDocKind, ValidateStatusWriteDocOptions } from "./gates.js";
+export { MAX_STATUS_CONTENT_LENGTH, eventTargetPaths, formatStatusWriteBlockReason, harnessDocKindOfTarget, validateStatusWriteDoc, violationLine, } from "./gates.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";
@@ -59,8 +64,8 @@ export type { DevTrackParam, QcReviewerParam, RoleFamily, RoleMappingEntry, Role
 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";
 export { detectHost, resolveSkillRoot } from "./host.js";
-export type { FiveQuestionMode, FiveQuestionSection } from "./skill-authoring.js";
-export { FIVE_QUESTION_SECTIONS, RUNTIME_HEADING_ALIASES, lintFiveQuestion, lintFrontmatter, resolveAssetPath, stripFrontmatter, } from "./skill-authoring.js";
+export type { FiveQuestionMode, FiveQuestionSection, SkillLintKind, SkillLintProfile } from "./skill-authoring.js";
+export { classifySkillLint, FIVE_QUESTION_SECTIONS, RUNTIME_HEADING_ALIASES, lintFiveQuestion, lintFrontmatter, resolveAssetPath, stripFrontmatter, } from "./skill-authoring.js";
 export type { MergeClass, MstarReviewFinding, MstarReviewV1, PrReportTarget, PrReviewSeatPromptOptions, PrReviewSizing, PrReviewTier, PrTierKeyword, PrSizeBand, PrTallyInput, PrTallyResult, PrVerdict, ResolvePrReviewTierInput, ReviewChangesetMode, ReviewInlineComment, ReviewPostPlan, ValidateFindingDocOptions, } from "./prreview.js";
 export { MERGE_CLASSES, PR_REVIEW_TIER_BUDGETS, PR_VERDICTS, REVIEW_EMOJI, computePrTally, pickReviewBranchName, planReviewPost, preflightChangeset, prReviewReportPath, prReviewSeatPrompt, prReviewSizing, resolvePrReviewTier, synthesizeReview, validateFindingDoc, validateMstarReviewV1, validatePrReviewReport, } from "./prreview.js";
 export type { ArtifactDoc, ArtifactKind, ArtifactRef, ArtifactStore } from "./store.js";

package/dist/iteration.d.ts

@@ -3,9 +3,9 @@ import type { GateResult, ValidationResult } from "./core.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`.
+ * verbatim () — `findPlanRow` accepts `id` or `plan_id`.
  *
- * Deliberate decoupling (qc wave-1 S-f): this is a loose LOCAL re-declaration,
+ * Deliberate decoupling: 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
@@ -54,7 +54,7 @@ export type PhaseGateOptions = {
  *   required; missing items listed in `violations`).
  * - all plans Done and both checklists clean → `phase-4-pr-delivery`.
  *
- * Note (qc2 F-003): during the Phase-3 window `ok` is false because the
+ * Note : during the Phase-3 window `ok` is false because the
  * §3.4 close items (`status: completed` + `end_date`) are only written at
  * the END of close — the exit checklist gates Phase 4, not the Phase-3
  * entry, so callers (e.g. the CLI, which exits 1) must treat that as "close

package/dist/lint.d.ts

@@ -9,27 +9,27 @@
  *
  * Spec sources (each function cites the source section):
  * - simplify:/temporary markers: `mstar-coding-behavior` SKILL.md § Simplicity
- *   First → "Simplification markers": a deliberate shortcut with a known
- *   ceiling is marked with a `simplify:` comment naming the ceiling and the
- *   upgrade path; a workaround is labeled `simplify:` / `temporary`, explains
- *   why, and records the removal path in the plan/status artifact before the
- *   task is claimed complete.
+ * First → "Simplification markers": a deliberate shortcut with a known
+ * ceiling is marked with a `simplify:` comment naming the ceiling and the
+ * upgrade path; a workaround is labeled `simplify:` / `temporary`, explains
+ * why, and records the removal path in the plan/status artifact before the
+ * task is claimed complete.
  * - SDD TDD triple: `mstar-coding-behavior` SKILL.md § Integration Notes —
- *   completion evidence must include the TDD triple (test file(s), command,
- *   output) in `task-N-report.md`; `mstar-sdd/references/file-handoffs.md` —
- *   fix subagents append covering test file(s), command run, output.
+ * completion evidence must include the TDD triple (test file(s), command,
+ * output) in `task-N-report.md`; `mstar-sdd/references/file-handoffs.md` —
+ * fix subagents append covering test file(s), command run, output.
  * - Plan quality bar: `mstar-artifacts/references/plan-quality-bar.md`
- *   § Quality checklist + `templates/plan.main.md` self-review
- *   ("Placeholder scan: no TBD").
+ * § Quality checklist + `templates/plan.main.md` self-review
+ * ("Placeholder scan: no TBD").
  * - Skill frontmatter contract: `mstar-skill-authoring` SKILL.md § Frontmatter
- *   Contract — `name` stable lowercase-hyphen; `description` is the trigger
- *   contract (not a workflow summary), third person.
+ * Contract — `name` stable lowercase-hyphen; `description` is the trigger
+ * contract (not a workflow summary), third person.
  * - STRATEGY.md structure: `mstar-strategy` SKILL.md § STRATEGY.md structure —
- *   six required sections.
+ * six required sections.
  * - Ephemeral citations: knowledge `conventions/skill-content-porting-discipline.md`
- *   §3 ("No ephemeral citations in durable skill text") + session evaluation
- *   2026-08-16 discrimination contract — concrete task-artifact references
- *   and SDD deeplinks are ephemeral; placeholder forms are not.
+ * §3 ("No ephemeral citations in durable skill text") + session evaluation
+ * 2026-08-16 discrimination contract — concrete task-artifact references
+ * and SDD deeplinks are ephemeral; placeholder forms are not.
  *
  * Enforcement depth: roadmap §8.5 C4 — v1 lints are non-blocking
  * `ValidationResult`s; callers surface them as warnings.
@@ -112,8 +112,8 @@ export type EphemeralCitation = {
     /** The matched citation token (artifact name or deeplink prefix). */
     match: string;
     /** `task-artifact`: `task-<digits>-(brief|report|fix-report|diff)`;
-     * `sdd-deeplink`: `.mstar/sdd/` / `.agents/sdd/` + a concrete first
-     * segment. */
+   * `sdd-deeplink`: `.mstar/sdd/` / `.agents/sdd/` + a concrete first
+   * segment. */
     kind: "task-artifact" | "sdd-deeplink";
 };
 /**
@@ -123,12 +123,12 @@ export type EphemeralCitation = {
  *
  * Discrimination (HARD — zero false positives on the skills corpus):
  * - `task-<digits>-(brief|report|fix-report|diff)` with 1+ digits is a
- *   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.
+ * 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
- *   are template forms → never match.
+ * segment (`20260815-x`) → reported; `<plan-id>` / `{SDD_DIR}` segments
+ * are template forms → never match.
  *
  * Discovery only — a finder returning an array, same shape as
  * `findSimplifyMarkers`, NOT a GateResult; callers wrap findings into
@@ -151,17 +151,17 @@ export declare function findEphemeralCitations(skillText: string): EphemeralCita
  *
  * Heuristics (documented, conservative — tuned so prose alone never counts):
  * - tests: a `.test.<ext>` / `.spec.<ext>` path, or the phrase "test file(s)"
- *   (the handoff template's exact header). "I added tests" without a file or
- *   the phrase does not count.
+ * (the handoff template's exact header). "I added tests" without a file or
+ * the phrase does not count.
  * - command: a `$`-prefixed line, or a known runner invocation (bun/pnpm/
- *   npm/yarn/npx/bunx test|run|exec, npx/bunx exec, tsc/vitest/jest/mocha/
- *   pytest/go test/cargo test). Prose "run the tests" names no runner and
- *   does not count (plan-quality-bar marks it a weak step anyway).
+ * npm/yarn/npx/bunx test|run|exec, npx/bunx exec, tsc/vitest/jest/mocha/
+ * pytest/go test/cargo test). Prose "run the tests" names no runner and
+ * does not count (plan-quality-bar marks it a weak step anyway).
  * - output: check marks, PASS/FAIL tokens, counts ("12 pass"), `N ok` /
- *   TAP `ok N` / "all ok" verdicts, exit-code statements. Bare prose
- *   `OK`/`ERROR` ("OK, moving on") does NOT count — output evidence must
- *   look like output. Line-based and fence-insensitive: real output usually
- *   lives in fenced blocks, so fence content is scanned too.
+ * TAP `ok N` / "all ok" verdicts, exit-code statements. Bare prose
+ * `OK`/`ERROR` ("OK, moving on") does NOT count — output evidence must
+ * look like output. Line-based and fence-insensitive: real output usually
+ * lives in fenced blocks, so fence content is scanned too.
  */
 export declare function assertSddTddTriple(reportText: string): GateResult;
 /**
@@ -188,16 +188,16 @@ export type PlanQualityResult = GateResult & {
  *
  * Heuristic (documented, conservative):
  * - tokens: `TBD`, `TODO`, `TBA` (case-insensitive, word-boundary, plural
- *   forms included) and the prose ellipsis `...`. One finding per line per
- *   token (a line with two TBDs yields one finding).
+ * forms included) and the prose ellipsis `...`. One finding per line per
+ * token (a line with two TBDs yields one finding).
  * - negation guard: a token preceded by a negation word (`no/not/without/
- *   none`) in the same segment (split at `(`/`[`/`{`/`.`/`;`/`,`/line
- *   start) is an absence assertion ("no TBD/placeholder/TODO" states the
- *   rule), not a placeholder — not flagged.
+ * none`) in the same segment (split at `(`/`[`/`{`/`.`/`;`/`,`/line
+ * start) is an absence assertion ("no TBD/placeholder/TODO" states the
+ * rule), not a placeholder — not flagged.
  * - exemptions: fenced code blocks (```` ``` ```` / `~~~`) and inline code
- *   spans are skipped — `...` in a file-list or example is not a placeholder.
+ * spans are skipped — `...` in a file-list or example is not a placeholder.
  * - out of scope (judgment stays prompt): "add tests" without code, and
- *   `FIXME`/`XXX` code markers.
+ * `FIXME`/`XXX` code markers.
  */
 export declare function planQualityBar(planText: string): PlanQualityResult;
 /**
@@ -205,7 +205,7 @@ export declare function planQualityBar(planText: string): PlanQualityResult;
  * Frontmatter Contract:
  * - `name` — stable, lowercase-hyphen (`example-skill`);
  * - `description` — the trigger contract, third person, not a workflow
- *   summary.
+ * summary.
  *
  * Accepts a full document (leading `---`-fenced block is parsed) or a bare
  * frontmatter body (`name:`/`description:` lines at the start). Violations:
@@ -214,21 +214,21 @@ export declare function planQualityBar(planText: string): PlanQualityResult;
  * - `lint.frontmatter.name.format` — `name` not lowercase-hyphen
  * - `lint.frontmatter.description.missing` — `description` absent/empty
  * - `lint.frontmatter.description.person` — first/second-person pronoun in
- *   the description (third-person heuristic, low severity)
+ * the description (third-person heuristic, low severity)
  * - `lint.frontmatter.description.workflow` — description reads as a
- *   workflow summary (verb-start or paragraph-length heuristic, low
- *   severity)
+ * workflow summary (verb-start or paragraph-length heuristic, low
+ * severity)
  *
  * Heuristics (documented, conservative; corpus regression tests in
  * lint.test.ts cover the 20 real skill frontmatters):
  * - pronouns: `I`/`we`/`you`/`my`/`our`/`your`/`us`, word-boundary,
- *   case-insensitive, after stripping quoted and backticked spans; `I/`
- *   (I/O) and all-caps `US` exempt.
+ * case-insensitive, after stripping quoted and backticked spans; `I/`
+ * (I/O) and all-caps `US` exempt.
  * - workflow shape: description starts with a workflow verb ("Explains how
- *   …", "Describes …") — the contract's own bad example — or exceeds 120
- *   words (corpus max 114). Bold/quote prefixes are stripped before the
- *   verb check. No content judgment (e.g. whether the trigger is narrow
- *   enough) — that stays prompt.
+ * …", "Describes …") — the contract's own bad example — or exceeds 120
+ * words (corpus max 114). Bold/quote prefixes are stripped before the
+ * verb check. No content judgment (e.g. whether the trigger is narrow
+ * enough) — that stays prompt.
  */
 export declare function lintSkillFrontmatter(frontmatterText: string): GateResult;
 /**

package/dist/migrate.d.ts

@@ -19,12 +19,12 @@ export type MigrateSnapshot = {
     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.
-     */
+   * 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;
@@ -57,7 +57,7 @@ export type MigrateRootV2 = {
     file: string;
     data: StatusV2Doc;
 };
-/** Planner options (plan Task 6 — `--dry-run` returns steps, zero writes). */
+/** Planner options ( — `--dry-run` returns steps, zero writes). */
 export type MigrateOptions = {
     dryRun?: boolean;
     /** Project id for the register/roadmap home (default `_default`). */
@@ -68,20 +68,20 @@ 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.
-     */
+   * 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.
-     */
+   * 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. */
@@ -108,7 +108,7 @@ export type MigrateResult = {
     message: string;
 };
 /**
- * Pure migration planner (plan Task 6): reads the v1 tree under `root` and
+ * Pure migration planner (): 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
@@ -120,7 +120,7 @@ export type MigrateResult = {
  */
 export declare function migrateHarnessTree(root: string, opts?: MigrateOptions): MigratePlan;
 /**
- * Execute a migration plan (plan Task 6). Additive-first ordering: the v1
+ * Execute a migration plan (). 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
@@ -128,7 +128,7 @@ export declare function migrateHarnessTree(root: string, opts?: MigrateOptions):
  * `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
+ * pre-validate (a gate here would run the same O(rows) pass
  * twice per snapshot).
  */
 export declare function applyMigratePlan(plan: MigratePlan): Promise<MigrateResult>;

package/dist/path.d.ts

@@ -4,25 +4,25 @@ import { type ValidationResult } from "./core.js";
  */
 export type ResolveHarnessDirOptions = {
     /**
-     * Explicit harness root. Resolved against `startDir` when relative.
-     * Takes precedence over `MSTAR_HARNESS_DIR` and over default probing.
-     * Authoritative: the path is returned even when it does not exist yet
-     * (the caller may scaffold it).
-     */
+   * Explicit harness root. Resolved against `startDir` when relative.
+   * Takes precedence over `MSTAR_HARNESS_DIR` and over default probing.
+   * Authoritative: the path is returned even when it does not exist yet
+   * (the caller may scaffold it).
+   */
     harnessDir?: string;
     /**
-     * Workspace-root stop boundary (roadmap §7c / plan
-     * 20260810-harness-root-boundary). 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
-     * boundary is the git top-level of `startDir` (sync `git rev-parse
-     * --show-cdup`; on failure / non-git start it falls back to
-     * `startDir` itself — a non-git start probes only itself, never upward;
-     * deliberate tightening). The boundary is an explicit caller value: the
-     * engine git-probes only for this default resolution, never during the
-     * walk.
-     */
+   * Workspace-root stop boundary (roadmap §7c / plan
+   * 20260810-harness-root-boundary). 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
+   * boundary is the git top-level of `startDir` (sync `git rev-parse
+   * --show-cdup`; on failure / non-git start it falls back to
+   * `startDir` itself — a non-git start probes only itself, never upward;
+   * deliberate tightening). The boundary is an explicit caller value: the
+   * engine git-probes only for this default resolution, never during the
+   * walk.
+   */
     workspaceRoot?: string;
 };
 /**
@@ -48,10 +48,10 @@ export declare function resolveHarnessDir(startDir?: string, opts?: ResolveHarne
  */
 export type ResolveSpecsDirOptions = {
     /**
-     * Default true: when every candidate is absent or empty, create
-     * `{HARNESS_DIR}/specs/` (plan-conventions § 创建默认). Read-only callers
-     * (e.g. `mstar path resolve`) pass `false` to skip the side effect.
-     */
+   * Default true: when every candidate is absent or empty, create
+   * `{HARNESS_DIR}/specs/` (plan-conventions § 创建默认). Read-only callers
+   * (e.g. `mstar path resolve`) pass `false` to skip the side effect.
+   */
     create?: boolean;
 };
 /**
@@ -79,12 +79,23 @@ export declare function resolveSpecsDir(harnessDir: string, opts?: ResolveSpecsD
 export declare function resolvePlanDir(harnessDir: string): string;
 /**
  * Single safe path component for per-plan path composition
- * (qc2 F-001 — path traversal guard): rejects `""`, `.`, `..`, and any
+ * (path traversal guard): rejects `""`, `.`, `..`, and any
  * `/` or `\`; allows `[A-Za-z0-9._-]+` only. Throws with a clear message so
  * callers interpolating a plan id into a path (archive files, SDD dirs)
  * can never escape the intended parent directory.
  */
 export declare function assertSafePathComponent(value: string, what: string): void;
+/**
+ * Canonicalize `path` for containment checks when the leaf may not exist
+ * (A3 nonexistent-leaf rule): canonicalize the nearest existing ancestor
+ * (realpath — resolves macOS `/var` → `/private/var` and any symlinked
+ * ancestors) and append the not-yet-existing remaining segments lexically.
+ * `..`/`.` segments are collapsed lexically by `resolve` before the walk,
+ * so the result is the path a later write would actually land at. Pure
+ * read-only (stat/realpath only — never creates anything). When nothing up
+ * to the filesystem root exists, the lexically resolved input is returned.
+ */
+export declare function canonicalizeNearestExisting(path: string): string;
 /**
  * Compose `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/` (plan-conventions
  * § 路径符号). A `.mstarc` `[config] sdd_dir` declaration replaces the
@@ -113,7 +124,7 @@ export declare function resolveKnowledgeDir(harnessDir: string): string;
  * 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
+ * Deferred-by-design : 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.
@@ -124,8 +135,7 @@ export declare function resolveWorkflowDir(startDir?: string, opts?: ResolveHarn
  * 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).
- */
+ * `resolveWorkflowDir`. */
 export declare function resolveProjectDir(startDir?: string, opts?: ResolveHarnessDirOptions): string;
 /**
  * Resolve the scaffold target dirs for `root` — the harness dir and the