@mstar-harness/engine 2.1.1 → 2.3.0

package/README.md

@@ -19,7 +19,7 @@ const version = readHarnessVersion(); // "1.8.8" — monorepo root package.json
 ## Scope
 
 - Importable library only — **no `bin`**; the CLI (`@mstar-harness/cli`) wraps engine functions as thin `mstar …` subcommands.
-- Dependencies: `node:*` only (zero external runtime deps — all validators hand-rolled; ajv pruned as phantom, zod removed 2026-08-08).
+- Dependencies: `node:*` only (zero external runtime deps — all validators hand-rolled; ajv and zod were pruned as phantom dependencies).
 - Skill prose stays authoritative; engine exports are the machine-checkable mirror of the rules the `mstar-*` skills state.
 
 ## License

package/dist/engine.js

@@ -83,24 +83,52 @@ function readHarnessVersion() {
 }
 // src/path.ts
 import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
   const start = resolve2(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
     return resolve2(start, explicit);
+  const boundary = resolve2(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   let dir = start;
   for (;; ) {
+    if (!isAtOrBelow(dir, boundary))
+      return null;
     for (const candidate of [join2(dir, ".mstar"), join2(dir, ".agents"), join2(dir, ".plans"), join2(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
+    if (dir === boundary)
+      return null;
     const parent = dirname2(dir);
     if (parent === dir)
       return null;
     dir = parent;
   }
 }
+function defaultWorkspaceRoot(startDir) {
+  try {
+    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
+      cwd: startDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!cdup)
+      return startDir;
+    let boundary = startDir;
+    for (const segment of cdup.split(/[\\/]/)) {
+      if (segment && segment !== ".")
+        boundary = dirname2(boundary);
+    }
+    return resolve2(boundary);
+  } catch {}
+  return startDir;
+}
+function isAtOrBelow(dir, root) {
+  const rel = relative(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
 function resolveSpecsDir(harnessDir, opts = {}) {
   const harness = resolve2(harnessDir);
   const repoRoot = dirname2(harness);
@@ -646,7 +674,7 @@ function parseAssignmentBranchForms(assignmentText) {
   if (fields.branchPolicy !== undefined && fields.branchPolicy !== "") {
     const direct = fields.branchPolicy.match(/^direct\s+on\s+(\S+)/i);
     if (direct) {
-      const strict = fields.branchPolicy.match(/^direct\s+on\s+(\S+)(?:\s*(?:[—–]|--|-)\s*(.+))?$/);
+      const strict = fields.branchPolicy.match(/^direct\s+on\s+(\S+)(?:\s*(?:[\u2014\u2013]|--|-)\s*(.+))?$/);
       forms.directOn = { branch: direct[1].trim(), reason: strict ? (strict[2] ?? "").trim() : "" };
     }
   }
@@ -1150,7 +1178,7 @@ function techDebtRollup(docOrPath) {
   return { computed, stored, checks, overall };
 }
 // src/worktree.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync3 } from "node:fs";
 import { isAbsolute as isAbsolute3, resolve as resolve5 } from "node:path";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
@@ -1173,7 +1201,7 @@ function probeBranch(worktreePath, opts) {
     return { branch: precomputed };
   const timeout = opts.timeoutMs ?? probeTimeoutMs();
   try {
-    const stdout = execFileSync(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
+    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout
@@ -1302,7 +1330,7 @@ function singleReviewSnapshot(assignments) {
   return gate(violations);
 }
 // src/sdd.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, realpathSync, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute4, join as join5, resolve as resolve6 } from "node:path";
 class SddScriptError extends Error {
@@ -1330,7 +1358,7 @@ function isFile(file) {
 var GIT_CAPTURE_MAX_BYTES = 64 * 1024 * 1024;
 function gitOut(cwd, args) {
   try {
-    return execFileSync2("git", args, {
+    return execFileSync3("git", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
@@ -1463,7 +1491,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const verifyRef = (ref, what) => {
     try {
-      execFileSync2("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+      execFileSync3("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
     } catch {
       throw new SddScriptError(`bad ${what}: ${ref}`, 2);
     }
@@ -1483,7 +1511,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
     out = join5(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
-  const run = (args) => execFileSync2("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
+  const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
   const parts = [
     Buffer.from(`# Review package: ${base}..${head}
 
@@ -1507,7 +1535,7 @@ function assertBaseSha(ref, opts = {}) {
     throw new SddScriptError(`assertBaseSha: BASE must be a commit SHA (full or prefix); got ${JSON.stringify(ref)}. ` + "Never use HEAD~1 as review BASE (multi-commit tasks truncate).", 2);
   }
   try {
-    execFileSync2("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+    execFileSync3("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
       cwd: opts.cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -2524,6 +2552,7 @@ function renderIndex(params) {
   if (rejectedRows !== "") {
     sections.push("", "## Findings considered and rejected", "", rejectedRows);
   }
+  sections.push("", "## Red-team dispositions", "", "- <finding>: <survived / refuted / hallucination-dropped / uncovered-kept>, <one-line reason>");
   return `${sections.join(`
 `)}
 `;
@@ -3052,11 +3081,31 @@ function findTemporaryMarkers(fileText) {
   }
   return { ok: violations.length === 0, violations, markers };
 }
+var TASK_ARTIFACT_RE = /\btask-\d+(?:-(?:brief|report|fix-report|diff)|\.diff)\b/g;
+var SDD_DEEPLINK_RE = /\.(?:mstar|agents)\/sdd\/([^\s/<>{}\[\]"'\*\?]+)/g;
+function findEphemeralCitations(skillText) {
+  const citations = [];
+  const lines = skillText.split(/\r?\n/);
+  for (let i = 0;i < lines.length; i++) {
+    const found = [];
+    for (const m of lines[i].matchAll(TASK_ARTIFACT_RE)) {
+      found.push({ index: m.index, match: m[0], kind: "task-artifact" });
+    }
+    for (const m of lines[i].matchAll(SDD_DEEPLINK_RE)) {
+      found.push({ index: m.index, match: m[0], kind: "sdd-deeplink" });
+    }
+    found.sort((a, b) => a.index - b.index);
+    for (const f of found) {
+      citations.push({ line: i + 1, match: f.match, kind: f.kind });
+    }
+  }
+  return citations;
+}
 var TEST_FILE_PATH_RE = /[\w./-]+\.(?:test|spec)\.[a-z0-9]+/i;
 var TEST_FILE_PHRASE_RE = /\btest files?\b/i;
 var COMMAND_PROMPT_RE = /^\s*[$>]\s*\S/;
 var RUNNER_RE = /\b(?:bun|pnpm|npm|yarn|npx|bunx)\s+(?:test|run|exec)\b|\b(?:npx|bunx)\s+[\w./-]+\b|\b(?:tsc|vitest|jest|mocha|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/i;
-var OUTPUT_TOKEN_RE = /[✓✔✗✘]|\b(?:PASS|FAIL)\b|\b\d+\s+(?:pass(?:es|ed)?|fail(?:s|ed|ing)?|skipped|tests?|ok)\b|\bok\s+\d+\b|\ball\s+ok\b|exit(?:ed)?\s+(?:with\s+)?(?:code\s+)?\d+/i;
+var OUTPUT_TOKEN_RE = /[\u2713\u2714\u2717\u2718]|\b(?:PASS|FAIL)\b|\b\d+\s+(?:pass(?:es|ed)?|fail(?:s|ed|ing)?|skipped|tests?|ok)\b|\bok\s+\d+\b|\ball\s+ok\b|exit(?:ed)?\s+(?:with\s+)?(?:code\s+)?\d+/i;
 function assertSddTddTriple(reportText) {
   const violations = [];
   const lines = reportText.split(/\r?\n/);
@@ -3377,6 +3426,8 @@ function detectHost(signals) {
     return "opencode";
   if (s.has("task_agent_batch") || s.has("ask") || s.has("hub"))
     return "omp";
+  if (s.has("subagent"))
+    return "dsh";
   if (s.has("AgentSwarm"))
     return "kimi";
   if (s.has("Agent") || s.has("AskUserQuestion") || s.has("EnterPlanMode") || s.has("TodoWrite"))
@@ -3400,9 +3451,10 @@ function resolveSkillRoot(host, paths) {
     case "kimi":
     case "zcode":
       return `./skills/${skill}${suffix}`;
-    case "pi":
     case "dsh":
-      return `deferred: ${host} has no plugin API in v1 — skill-root resolution lands with its adapter (roadmap §8.4)`;
+      return `$DSH_BUNDLED_SKILL_DIR/${skill}${suffix}`;
+    case "pi":
+      return `deferred: pi has no plugin API in v1 — skill-root resolution lands with its adapter (roadmap §8.4)`;
   }
 }
 // src/skill-authoring.ts
@@ -3495,6 +3547,7 @@ export {
   findingsCleanupGate,
   findTemporaryMarkers,
   findSimplifyMarkers,
+  findEphemeralCitations,
   executionModeToN,
   evaluatePhaseGate,
   emitGitignoreSnippet,

package/dist/host.d.ts

@@ -11,7 +11,10 @@
  *   resolution.
  * - `.harness/references/skill-programmatic-roadmap.md` §8.4 — the
  *   `HostAdapter` shared contract (all hooks optional; no concrete adapters
- *   in the engine; pi/dsh deferred).
+ *   in the engine; pi deferred).
+ * - `.harness/references/dsh-adapter-roadmap.md` §4 D5 (this iteration) —
+ *   the dsh detection row + skill-root form; mirror text lands in the
+ *   mstar-host skill when this module is upstreamed.
  *
  * UX judgment (ambiguous-host fallback reasoning, plan-mode bridges) stays
  * prompt — this module only turns tool shapes into a host id.
@@ -19,18 +22,19 @@
 import type { GateResult, ValidationResult } from "./core.js";
 import type { AssignmentFields } from "./dispatch.js";
 import type { IntegrationMergeLease } from "./lease.js";
-/** All hosts the engine knows about (roadmap §8.4 host union). `pi` and
- * `dsh` have no plugin API in v1 — they appear in the union (and in
- * `HostAdapter.host`) but are never detected and get no adapters. */
+/** All hosts the engine knows about (roadmap §8.4 host union). `pi` has no
+ * plugin API in v1 — it appears in the union (and in `HostAdapter.host`) but
+ * is never detected and gets no adapter. `dsh` is detected and resolved
+ * (roadmap §4 D5, this iteration); its adapter ships in the dsh plugin. */
 export type HostId = "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";
-/** Result of `detectHost`: one of the six known hosts or `ambiguous`
+/** Result of `detectHost`: one of the seven known hosts or `ambiguous`
  * (prompt judgment then applies per mstar-host). */
-export type DetectResult = "opencode" | "omp" | "cursor" | "codex" | "kimi" | "zcode" | "ambiguous";
+export type DetectResult = "opencode" | "omp" | "dsh" | "cursor" | "codex" | "kimi" | "zcode" | "ambiguous";
 /** Tool-shape signal tokens accepted by `detectHost`, derived from the
  * mstar-host detection table. Plan-mode extras (CreatePlan/SwitchMode) and
  * Browser-plugin tools are documented in the table but are not part of the
  * v1 signal enum. */
-export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_agent_batch" | "ask" | "hub" | "Agent" | "AgentSwarm" | "AskUserQuestion" | "EnterPlanMode" | "TodoWrite" | "plan_slash" | "goal" | "functions.*" | "tool_search";
+export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_agent_batch" | "ask" | "hub" | "subagent" | "Agent" | "AgentSwarm" | "AskUserQuestion" | "EnterPlanMode" | "TodoWrite" | "plan_slash" | "goal" | "functions.*" | "tool_search";
 /**
  * Detect the active host from session tool shapes, per the ordered
  * mstar-host table (ported verbatim):
@@ -40,14 +44,19 @@ export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_
  * | `subagent_type` (Task param; plan mode + CreatePlan/SwitchMode) | cursor |
  * | `question`, or `task_subagent` (task tool, singular subagent, no batch) | opencode |
  * | `task_agent_batch` (task tool, agent/tasks[] batch), `ask`, `hub` | omp |
+ * | `subagent` (dsh's model-facing delegation tool) | dsh |
  * | `Agent`/`AskUserQuestion`/`EnterPlanMode` + `AgentSwarm` (Kimi-only) | kimi |
  * | `Agent`/`AskUserQuestion`/`EnterPlanMode`/`TodoWrite`, no `AgentSwarm` | zcode |
  * | `/plan`, `/goal`; Goal tools; `functions.*` namespaces; `tool_search` | codex |
  *
- * Order matters: cursor → opencode → omp → kimi → zcode → codex — the
- * sharpest Task-based split is `subagent_type` (Cursor) vs `subagent`
- * (OpenCode) vs `agent`/`tasks[]` (omp). Still ambiguous → `"ambiguous"`
- * (prompt judgment stays in the skill).
+ * Order matters: cursor → opencode → omp → dsh → kimi → zcode → codex — the
+ * sharpest Task-based split is `subagent_type` (Cursor) vs `task_subagent`
+ * (OpenCode) vs `agent`/`tasks[]` (omp); dsh's `subagent` tool (roadmap §4
+ * D5) collides with no other row, so it sits with the agent-tool hosts.
+ * (`mstar-host` skill prose still says colloquial `subagent` for OpenCode —
+ * disambiguate it to `task_subagent` in the same upstream PR that carries
+ * this row, together with the CLI `HOST_SIGNALS` list.)
+ * Still ambiguous → `"ambiguous"` (prompt judgment stays in the skill).
  */
 export declare function detectHost(signals: readonly ToolSignal[]): DetectResult;
 /** Skill name + optional skill-relative path for skill-root resolution. */
@@ -69,7 +78,8 @@ export type SkillRootPaths = {
  * | codex | `skills/<name>[/<rel>]` (plugin-mounted; project command skills under `.agents/skills/<name>/`) |
  * | opencode | `harness-skills/<name>[/<rel>]` (package-internal via `@mstar-harness/opencode` — never `process.cwd()/skills/`) |
  * | kimi / zcode | `./skills/<name>[/<rel>]` (plugin mount from the installed plugin root) |
- * | pi / dsh | deferred — no plugin API in v1 (roadmap §8.4) |
+ * | dsh | `$DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]` (skill-local bundled root — dsh-skill-local `bundledSkillDir` default; the single canonical mount per roadmap D6. Frozen this iteration; local dev mounts the mirror `skills/` via `customSkillDirs` instead, but the canonical published form stays the bundled root) |
+ * | pi | deferred — no plugin API in v1 (roadmap §8.4) |
  */
 export declare function resolveSkillRoot(host: HostId, paths: SkillRootPaths): string;
 /**
@@ -79,8 +89,8 @@ export declare function resolveSkillRoot(host: HostId, paths: SkillRootPaths): s
  * rule: skill text remains authoritative; the engine only returns results
  * the caller chooses to honor). `log` is required — adapters must be able to
  * report. No concrete adapters ship in the engine: opencode binds via its
- * own plugin code, omp via the command layer; pi/dsh adapters are deferred
- * until their plugin APIs land.
+ * own plugin code, omp via the command layer, dsh via the dsh plugin (this
+ * iteration); pi stays deferred until its plugin API lands.
  */
 export interface HostAdapter {
     host: "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";

package/dist/index.d.ts

@@ -42,8 +42,8 @@ export type { AuditCategory, AuditEffort, AuditFinding, AuditPriority, AuditRisk
 export { AUDIT_CATEGORIES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, redactSecrets, scaffoldAuditPlan, validateAuditStatusBlocks, } from "./audit.js";
 export type { ReferenceCheckResult } from "./compound.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
-export type { PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
-export { assertSddTddTriple, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
+export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
+export { assertSddTddTriple, findEphemeralCitations, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
 export type { DevTrackParam, QcReviewerParam, RoleFamily, RoleMappingEntry, RoleMappingOptions, } from "./roles.js";
 export { DEV_TRACK_PARAMS, QC_REVIEWER_PARAMS, ROLE_MAPPING, SHARED_FAMILIES, lintLoadOrder, validateRoleMapping, } from "./roles.js";
 export type { DetectResult, HostAdapter, HostId, SkillRootPaths, ToolSignal } from "./host.js";

package/dist/lint.d.ts

@@ -27,6 +27,10 @@
  *   contract (not a workflow summary), third person.
  * - STRATEGY.md structure: `mstar-strategy` SKILL.md § STRATEGY.md structure —
  *   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.
  *
  * Enforcement depth: roadmap §8.5 C4 — v1 lints are non-blocking
  * `ValidationResult`s; callers surface them as warnings.
@@ -95,6 +99,45 @@ export type TemporaryMarkerResult = GateResult & {
  * carry); do not special-case it without a real FP report.
  */
 export declare function findTemporaryMarkers(fileText: string): TemporaryMarkerResult;
+/**
+ * An ephemeral citation found in durable skill text: a concrete reference to
+ * a per-task artifact or an SDD deeplink that survives nothing (knowledge
+ * conventions/skill-content-porting-discipline.md §3 — "No ephemeral
+ * citations in durable skill text": a calibration line citing an SDD task
+ * report violates standalone + survives nothing; instances/examples cite
+ * in-repo artifacts only).
+ */
+export type EphemeralCitation = {
+    /** 1-based line number of the citation. */
+    line: number;
+    /** 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. */
+    kind: "task-artifact" | "sdd-deeplink";
+};
+/**
+ * Find ephemeral citations in skill text (knowledge
+ * conventions/skill-content-porting-discipline.md §3 + session evaluation
+ * 2026-08-16 discrimination contract).
+ *
+ * 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.
+ * - `.mstar/sdd/<segment>` / `.agents/sdd/<segment>` with a concrete first
+ *   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
+ * `ViolationResult`s (codes `skill.ephemeral.task-artifact` /
+ * `skill.ephemeral.sdd-deeplink`). Citations are reported line by line in
+ * 1-based line order, source order within a line.
+ */
+export declare function findEphemeralCitations(skillText: string): EphemeralCitation[];
 /**
  * Assert the SDD TDD triple is present in a `task-N-report.md` text
  * (mstar-coding-behavior § Integration Notes — "completion evidence must

package/dist/path.d.ts

@@ -10,15 +10,32 @@ export type ResolveHarnessDirOptions = {
      * (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.
+     */
+    workspaceRoot?: string;
 };
 /**
  * Resolve `{HARNESS_DIR}` per plan-conventions § {HARNESS_DIR} 解析顺序
  * (find-first-stop): `.mstar/` → `.agents/` → `.plans/`/`plans/`, walking up
- * from `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.
+ * 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.
  *
- * Returns the absolute harness dir, or `null` when no candidate exists.
+ * Returns the absolute harness dir, or `null` when no candidate exists
+ * within the workspace boundary.
  */
 export declare function resolveHarnessDir(startDir?: string, opts?: ResolveHarnessDirOptions): string | null;
 /**

package/package.json

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