@mstar-harness/engine 2.0.1 → 2.0.3

package/dist/dispatch.d.ts

@@ -1,31 +1,3 @@
-/**
- * Engine dispatch module — Assignment field validation, default-branch gate,
- * execution-mode → QC seat count, tri identity, anti-recursion precheck.
- *
- * Spec sources (semantic SSOT — the skills stay authoritative; this module
- * implements their deterministic rules without forking semantics):
- * - Assignment field contract (`Execute as` / `Delegation` / `Task category`
- *   present, non-empty; paste-only assignments missing fields are flagged):
- *   `mstar-dispatch-gates` SKILL.md § "调度防串扰（强制）" + § 反模式（派发）
- *   ("Assignment 已写、invoke 为零（paste-only）").
- * - Branch-field exactly-one rule + `<base>` requirement: `mstar-branch-worktree`
- *   SKILL.md § "Assignment 要求（PM）" + § "`<base>` 与叠分支（stacked
- *   branches）" ("若写新建但未写 `<base>`：实现侧应停下问 project-manager…
- *   禁止擅自假设「一定是 main」").
- * - Default-protected-branch gate (`main`/`master` unless an explicit
- *   `Branch policy: direct on <branch> — <reason>` exception exists):
- *   `mstar-branch-worktree` SKILL.md § "Git 功能分支门禁（业务仓库）".
- * - N→seat mapping (sdd→3 tri, inline→1 single, targeted→listed seats) and
- *   tri identity (`qc-specialist` / `qc-specialist-2` / `qc-specialist-3`):
- *   `mstar-dispatch-gates` SKILL.md § "QC tri-review（SDD 强制）" / "QC
- *   单席（例外）" / "QC targeted re-review" + `mstar-roles` SKILL.md
- *   "QC reviewer" 参数表.
- * - Anti-recursion NEVER red line (role binding == `Execute as`): `mstar-dispatch-gates`
- *   SKILL.md § "承接方反递归红线（NEVER / DO NOT；leaf executor 必读）".
- * - Hard-gate enforcement (`Enforcement: hard` flag — per Assignment/compass,
- *   never global; rollback = unset flag): `.harness/references/skill-programmatic-roadmap.md`
- *   §8.5 C4 + decision D2.
- */
 import type { GateResult } from "./core.js";
 /** Parsed Assignment header fields relevant to dispatch validation. */
 export type AssignmentFields = {
@@ -195,6 +167,56 @@ export declare function executionModeToN(executionMode: string, opts?: Execution
  * Any other composition — missing seat, duplicate, or foreign role — fails.
  */
 export declare function assertTriIdentity(reviewerRoles: readonly string[]): GateResult;
+/**
+ * Options for {@link composeDispatchGate}.
+ */
+export type ComposeDispatchGateOptions = {
+    /**
+     * Host role-binding field (omp task entry `agent` / opencode `subagent` /
+     * cursor `subagent_type`); the anti-recursion precheck runs only when
+     * non-empty.
+     */
+    agent?: string;
+    /**
+     * `false` for read-only roles (scout/explore) — skips the branch-form and
+     * default-branch gates. Default: `true` (writable).
+     */
+    writable?: boolean;
+};
+/**
+ * Result of {@link composeDispatchGate}: a GateResult plus the shape verdict
+ * and the header-region enforcement flag.
+ */
+export type ComposeDispatchGateResult = GateResult & {
+    /** Assignment-shaped text was recognized (heading or core-field regex). */
+    shaped: boolean;
+    /** Enforcement parsed from the Assignment HEADER region only (never the body). */
+    enforcement: EnforcementFlag;
+};
+/**
+ * Shared host dispatch-gate composition (qc1 F-001/F-006, qc2 F-005/F-007,
+ * qc3 F-007/F-008) — the SINGLE dispatch-validation composition consumed by
+ * the opencode adapter (`validateDispatchAssignment`), the omp blocking hook
+ * (Gate 2) and the `mstar_dispatch_validate` tool:
+ *
+ * 1. Shape guard: `## Assignment` heading OR any core field line
+ *    (`Execute as` / `Delegation` / `Task category`). Text that is not
+ *    Assignment-shaped passes silently (`shaped: false`).
+ * 2. `validateAssignmentFields` with `writable: false` when `opts.writable
+ *    === false` (read-only roles), else the writable default.
+ * 3. Anti-recursion precheck when `opts.agent` is non-empty.
+ * 4. Default-branch gate for writable text: the branch comes from the
+ *    Assignment's own branch forms (create-form name / Working branch /
+ *    Branch policy branch), else `$MSTAR_WORKING_BRANCH`; a well-formed
+ *    `Branch policy: direct on <branch> — <reason>` exception is honored
+ *    only when its branch is the one being checked.
+ * 5. Enforcement flag parsed from the Assignment HEADER region only; the
+ *    result carries `hardBlocked` via `applyEnforcement`.
+ *
+ * Never throws on text errors: unexpected failures degrade to the same
+ * silent non-shaped result.
+ */
+export declare function composeDispatchGate(text: string, opts?: ComposeDispatchGateOptions): ComposeDispatchGateResult;
 /**
  * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
  * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding

package/dist/engine.js

@@ -740,6 +740,43 @@ function assertTriIdentity(reviewerRoles) {
     ]
   };
 }
+var ASSIGNMENT_HEADING_RE = /^#{1,6}\s+Assignment\s*$/m;
+var ASSIGNMENT_FIELD_RE = /^[ \t]*(?:[-*][ \t]+)?\*{0,2}(Execute as|Delegation|Task category)\*{0,2}[ \t]*:[ \t]*(\S.*)$/gm;
+function isAssignmentShaped(assignmentText) {
+  return ASSIGNMENT_HEADING_RE.test(assignmentText) || assignmentText.match(ASSIGNMENT_FIELD_RE) !== null;
+}
+function composeDispatchGate(text, opts = {}) {
+  const silent = {
+    ok: true,
+    violations: [],
+    shaped: false,
+    enforcement: { hard: false, source: "none" }
+  };
+  try {
+    if (!isAssignmentShaped(text))
+      return silent;
+    const violations = [];
+    const writable = opts.writable !== false;
+    violations.push(...validateAssignmentFields(text, { writable }).violations);
+    const agent = (opts.agent ?? "").trim();
+    if (agent !== "") {
+      violations.push(...antiRecursionPrecheck(agent, parseAssignmentFields(text).executeAs ?? "").violations);
+    }
+    if (writable) {
+      const forms = parseAssignmentBranchForms(text);
+      const branch = forms.createForm?.name ?? forms.workingBranch ?? forms.directOn?.branch ?? process.env.MSTAR_WORKING_BRANCH;
+      if (branch !== undefined && branch.trim() !== "") {
+        const directOnException = parseBranchPolicyDirectOnBranch(text) === branch.trim();
+        violations.push(...assertDefaultBranchProtected(branch.trim(), { directOnException }).violations);
+      }
+    }
+    const enforcement = parseEnforcementFlag(assignmentHeaderRegion(text));
+    const gate = { ok: violations.length === 0, violations };
+    return { ...applyEnforcement(gate, { hard: enforcement.hard }), shaped: true, enforcement };
+  } catch {
+    return silent;
+  }
+}
 function antiRecursionPrecheck(subagentType, executeAs) {
   const binding = subagentType.trim().toLowerCase();
   const role = executeAs.trim().toLowerCase();
@@ -1819,6 +1856,68 @@ function assertIndexRowObligations(iterationsDir) {
   }
   return { ok: violations.length === 0, violations };
 }
+function parseCompassFrontmatter(filePath) {
+  const content = readFileSync5(filePath, "utf8");
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    throw new Error(`no YAML frontmatter fence in ${filePath} (expected first line "---")`);
+  }
+  const end = lines.indexOf("---", 1);
+  if (end === -1) {
+    throw new Error(`unterminated YAML frontmatter in ${filePath} (no closing "---")`);
+  }
+  const doc = {};
+  let listKey = null;
+  for (let i = 1;i < end; i += 1) {
+    const line = lines[i] ?? "";
+    if (!line.trim() || line.trim().startsWith("#"))
+      continue;
+    if (listKey !== null && /^\s*-\s+/.test(line)) {
+      const item = line.replace(/^\s*-\s+/, "").trim().replace(/^["']|["']$/g, "");
+      if (!Array.isArray(doc[listKey]))
+        doc[listKey] = [];
+      doc[listKey].push(item);
+      continue;
+    }
+    listKey = null;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) {
+      throw new Error(`unsupported frontmatter line in ${filePath}: ${JSON.stringify(line)}`);
+    }
+    const value = kv[2].trim();
+    doc[kv[1]] = value === "" ? null : /^\[.*\]$/.test(value) ? parseFlowArray(value, filePath) : value.replace(/^["']|["']$/g, "");
+    listKey = value === "" ? kv[1] : null;
+  }
+  return doc;
+}
+function parseFlowArray(raw, filePath) {
+  const inner = raw.slice(1, -1);
+  if (/[[\]]/.test(inner)) {
+    throw new Error(`nested flow-style array in ${filePath}: ${JSON.stringify(raw)} — only flat scalar items are supported (e.g. [a, b])`);
+  }
+  let quote = null;
+  for (const ch of inner) {
+    if (ch === '"' || ch === "'") {
+      if (quote === null)
+        quote = ch;
+      else if (quote === ch)
+        quote = null;
+    } else if (ch === "," && quote !== null) {
+      throw new Error(`ambiguous flow-style array in ${filePath}: ${JSON.stringify(raw)} — quoted item containing comma cannot be split unambiguously (flat scalar items only)`);
+    }
+  }
+  if (quote !== null) {
+    throw new Error(`unterminated ${quote} quote in flow-style array in ${filePath}: ${JSON.stringify(raw)}`);
+  }
+  const items = [];
+  for (const part of inner.split(",")) {
+    const item = part.trim().replace(/^["']|["']$/g, "");
+    if (item === "")
+      continue;
+    items.push(item);
+  }
+  return items;
+}
 // src/design-md.ts
 function violation6(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
@@ -3379,6 +3478,7 @@ export {
   planExecutionLeaseLocations,
   parseEnforcementFlag,
   parseDesignFrontmatter,
+  parseCompassFrontmatter,
   parseBranchPolicyDirectOnBranch,
   parseAssignmentFields,
   parseAssignmentBranchForms,
@@ -3400,6 +3500,7 @@ export {
   emitGitignoreSnippet,
   detectHost,
   compoundRefreshScope,
+  composeDispatchGate,
   completenessLevel,
   claimLease,
   canSteal,

package/dist/index.d.ts

@@ -28,14 +28,14 @@ export type { ArchiveResult, FindingsCleanupMode, PlanRow, ResidualEntry, Status
 export { archiveResiduals, findingsCleanupGate, normalizeSeverity, resolveCompassEnforcement, techDebtRollup, validatePlanRow, validateResidual, validateStatus, } 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 { AssignmentBranchForms, AssignmentFields, DefaultBranchOptions, EnforcementFlag, EnforcementSource, ExecutionModeToNOptions, ExecutionModeToNResult, ValidateAssignmentFieldsOptions, } from "./dispatch.js";
-export { antiRecursionPrecheck, assertDefaultBranchProtected, assertTriIdentity, assignmentHeaderRegion, executionModeToN, isReadOnlyAssignmentRole, parseAssignmentBranchForms, parseAssignmentFields, parseBranchPolicyDirectOnBranch, parseEnforcementFlag, validateAssignmentFields, } from "./dispatch.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";
 export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, l1PreDispatchCheck, l2PreDispatchCheck, singleReviewSnapshot, } from "./worktree.js";
 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, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
+export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.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

@@ -86,3 +86,17 @@ export declare function pushCadenceProbe(ciRunning: boolean, reviewWaveActive: b
  * a missing README, a missing header, and missing per-iteration rows.
  */
 export declare function assertIndexRowObligations(iterationsDir: string): GateResult;
+/**
+ * Parse the YAML frontmatter of a delivery-compass.md into a flat doc.
+ *
+ * The compass frontmatter is a flat YAML subset (scalar keys plus one
+ * `plans:` list-of-scalars — see `skills/mstar-iteration/references/
+ * 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).
+ *
+ * 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>;

package/package.json

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