@mstar-harness/engine 3.6.3 → 3.7.0

package/dist/index.d.ts

@@ -25,10 +25,10 @@
  */
 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";
@@ -39,8 +39,8 @@ export type { AssignmentBranchForms, AssignmentFields, ComposeDispatchGateOption
 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 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";
@@ -59,8 +59,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

package/dist/project.d.ts

@@ -1,18 +1,18 @@
 import { type GateResult, type ValidationResult } from "./core.js";
 import { type ResidualEntry } from "./status.js";
-/** Roadmap file name inside `projects/<id>/` (plan Task 4 — writer contract). */
+/** Roadmap file name inside `projects/<id>/` ( — writer contract). */
 export declare const PROJECT_ROADMAP_FILE = "roadmap.md";
-/** Theme-scoped research directory name inside `projects/<id>/` (plan 20260820-project-research-corpus Task 1 — compass ruling 1). */
+/** Theme-scoped research directory name inside `projects/<id>/`. */
 export declare const PROJECT_REFERENCES_DIR = "references";
-/** Project register file name inside `projects/<id>/` (plan Task 4). */
+/** Project register file name inside `projects/<id>/` (). */
 export declare const PROJECT_REGISTER_FILE = "residuals.json";
-/** Fallback project id for project-less flows (plan Task 4 — compass ruling 2). */
+/** Fallback project id for project-less flows ( — compass ruling 2). */
 export declare const _DEFAULT_PROJECT = "_default";
-/** Roadmap status enum (plan Task 4 — frontmatter schema). */
+/** Roadmap status enum ( — frontmatter schema). */
 export declare const ROADMAP_STATUSES: readonly ["active", "paused", "completed"];
 export type RoadmapStatus = (typeof ROADMAP_STATUSES)[number];
 /**
- * Roadmap frontmatter (plan Task 4): machine-checkable subset. All fields
+ * Roadmap frontmatter (): machine-checkable subset. All fields
  * are `unknown` because documents come from YAML at runtime; the validator
  * narrows them. `milestones` / `residuals_ref` are optional; goal-item body
  * conventions are warnings only.
@@ -33,8 +33,8 @@ export type ProjectRegisterEntry = ResidualEntry & {
     lifecycle_id?: string;
 };
 /**
- * Register document shape (`projects/<id>/residuals.json`, plan Task 4;
- * QC wave-1 W-E): `entries` keyed by plan id, each value an ARRAY of
+ * Register document shape (`projects/<id>/residuals.json`(;
+ * `entries` keyed by plan id, each value an ARRAY of
  * register entries — v1 `residual_findings[plan-id] = entries[]`
  * multi-finding semantics preserved verbatim (a plan can hold 2+ open
  * residuals). `migration_notes[]` (the old single-entry collapse record)
@@ -46,7 +46,7 @@ export type ProjectRegisterDoc = {
 };
 /**
  * Roadmap validation result: schema violations decide `ok`; body-convention
- * findings are collected as `warnings` and never flip `ok` (plan Task 4 —
+ * findings are collected as `warnings` and never flip `ok` ( —
  * goal-item body is not a hard gate).
  */
 export type RoadmapValidation = GateResult & {
@@ -79,7 +79,7 @@ export type TechDebtRollup = {
     overall: "PASS" | "DRIFT";
 };
 /**
- * Validate a roadmap.md file (plan Task 4): parse the frontmatter with the
+ * Validate a roadmap.md file (): parse the frontmatter with the
  * shared flat-subset parser and check the schema
  * `{ project_id, title, status: active|paused|completed, created_at,
  * milestones[]?, residuals_ref? }`. A roadmap file whose body follows the
@@ -90,7 +90,7 @@ export type TechDebtRollup = {
 export declare function validateRoadmap(filePath: string): RoadmapValidation;
 /**
  * Validate a project register document (`projects/<id>/residuals.json`,
- * plan Task 4; QC wave-1 W-E): `{ entries: { [key]: entry[] } }` keyed by
+ *  `{ entries: { [key]: entry[] } }` keyed by
  * plan id, each value an ARRAY of entries (v1 `residual_findings[plan-id]`
  * multi-finding semantics preserved — a plan may hold 2+ open residuals).
  * Each entry is validated by the v1 `validateResidual` verbatim (severity
@@ -100,21 +100,21 @@ export declare function validateRoadmap(filePath: string): RoadmapValidation;
  * `lifecycle_id`.
  */
 export declare function validateProjectRegister(doc: unknown): GateResult;
-/** Options for `appendProjectRegisterEntries` (plan 20260826-backlog-register-cli Task 1 + B-9). */
+/** Options for `appendProjectRegisterEntries`. */
 export type AppendProjectRegisterEntriesOpts = {
     /** Absolute path to the per-project directory (`<harness>/projects/<id>`; `_default` for project-less flows). */
     projectDir: string;
     /**
-     * Base entries key (`<plan-id>`), e.g. `pr-deep-review-2026-08-26`. The
-     * first free same-day key (`basePlanKey`, `basePlanKey-2`, `-3`, …) is
-     * selected INSIDE the status write lock — a caller-computed key would be a
-     * cross-lock TOCTOU (B-9 correction ①).
-     */
+   * Base entries key (`<plan-id>`), e.g. `pr-deep-review-2026-08-26`. The
+   * first free same-day key (`basePlanKey`, `basePlanKey-2`, `-3`, …) is
+   * selected INSIDE the status write lock — a caller-computed key would be a
+   * cross-lock TOCTOU (B-9 correction ①).
+   */
     basePlanKey: string;
     /** Residual entries to append — nine required fields + provenance. `source_plan` is overwritten with the used key; `registered_at` is required and must be set by the caller. */
     entries: ResidualEntry[];
 };
-/** Options for `closeProjectRegisterEntry` (plan 20260826-backlog-register-cli Task 1). */
+/** Options for `closeProjectRegisterEntry`. */
 export type CloseProjectRegisterEntryOpts = {
     /** Absolute path to the per-project directory (`<harness>/projects/<id>`; `_default` for project-less flows). */
     projectDir: string;
@@ -126,8 +126,7 @@ export type CloseProjectRegisterEntryOpts = {
     closureNote: string;
 };
 /**
- * Append residual entries to a project register (plan 20260826-backlog-register-cli
- * Task 1 + B-9): resolve `<projectDir>/residuals.json` and run the WHOLE
+ * Append residual entries to a project register: resolve `<projectDir>/residuals.json` and run the WHOLE
  * critical section inside `withStatusWriteLock(registerPath, ...)` (lease.ts —
  * the `<register dir>/.status-write.lockdir/` lock is reused, never
  * reimplemented). Read the register (absent → empty doc), select the first
@@ -140,7 +139,7 @@ export type CloseProjectRegisterEntryOpts = {
  * key beforehand), append preserving every other key, validate the whole
  * register with `validateProjectRegister`, then `ArtifactStore.put`
  * (FsStore uses `writeJson` — atomic temp+rename; never `open(w)`).
- * Fails loud (qc3 F-201) when the active FsStore would resolve a register
+ * Fails loud when the active FsStore would resolve a register
  * path other than `<projectDir>/residuals.json` — callers whose target root
  * differs from the active store's root MUST
  * `setArtifactStore(createFsStore(root))` first. Fail-loud: any validation
@@ -151,13 +150,12 @@ export declare function appendProjectRegisterEntries(opts: AppendProjectRegister
     key: string;
 }>;
 /**
- * Close one project-register entry in place (plan 20260826-backlog-register-cli
- * Task 1): under `withStatusWriteLock(registerPath, ...)`, find `entryId` in
+ * Close one project-register entry in place under `withStatusWriteLock(registerPath, ...)`, find `entryId` in
  * `entries[planKey]` (absent → throw), set `lifecycle: resolved` +
  * `closed_at: <today YYYY-MM-DD>` + `closure_note`, validate the whole
  * register with `validateProjectRegister`, then `ArtifactStore.put`
  * (FsStore uses `writeJson` — atomic temp+rename).
- * Fails loud (qc3 F-201) when the active FsStore would resolve a register
+ * Fails loud when the active FsStore would resolve a register
  * path other than `<projectDir>/residuals.json`. Fail-loud: an invalid
  * register throws and nothing is written.
  */
@@ -166,7 +164,7 @@ export declare function closeProjectRegisterEntry(opts: CloseProjectRegisterEntr
 }>;
 /**
  * Findings cleanup gate (status-and-residuals.md § Findings cleanup modes;
- * QC wave-1 W-D relocation — the input is the project register
+ * The input is the project register
  * `projects/<id>/residuals.json`, entries keyed by plan id with an ARRAY of
  * residuals per plan, and the plan id links the register entries to the
  * snapshot's plan row). Every OPEN entry of the plan is checked.
@@ -181,7 +179,7 @@ export declare function findingsCleanupGate(register: ProjectRegisterDoc, planId
     mode?: FindingsCleanupMode;
 }): GateResult;
 /**
- * Compute the tech-debt rollup over the project registers (QC wave-1 W-D
+ * Compute the tech-debt rollup over the project registers
  * relocation — status-and-residuals.md § `metadata.tech_debt_summary`
  * semantics preserved at the project layer): `total_open` / `by_severity` /
  * `by_target` / `by_plan` over open entries of every