@mstar-harness/engine 0.0.0

package/README.md

@@ -0,0 +1,27 @@
+# @mstar-harness/engine
+
+Morning Star (启明星) harness engine — deterministic library for harness checks (version, path, status, lease, validation), shared by the installer CLI and the OpenCode plugin.
+
+## Install
+
+```bash
+npm install @mstar-harness/engine
+```
+
+## Usage
+
+```ts
+import { readHarnessVersion } from "@mstar-harness/engine";
+
+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).
+- Skill prose stays authoritative; engine exports are the machine-checkable mirror of the rules the `mstar-*` skills state.
+
+## License
+
+MIT — see [LICENSE](https://github.com/btspoony/mstar-harness/blob/main/LICENSE).

package/dist/audit.d.ts

@@ -0,0 +1,99 @@
+import type { GateResult } from "./core.js";
+/** Priority values (mstar-audit SKILL § Plan files Status block). */
+export declare const AUDIT_PRIORITIES: readonly ["P1", "P2", "P3"];
+export type AuditPriority = (typeof AUDIT_PRIORITIES)[number];
+/** Effort values (Morning Star agent-oriented effort scale). */
+export declare const AUDIT_EFFORTS: readonly ["XS", "S", "M", "L", "XL"];
+export type AuditEffort = (typeof AUDIT_EFFORTS)[number];
+/** Risk values. */
+export declare const AUDIT_RISKS: readonly ["LOW", "MED", "HIGH"];
+export type AuditRisk = (typeof AUDIT_RISKS)[number];
+/** Category codes (finding-format.md § Category codes + SKILL Status block). */
+export declare const AUDIT_CATEGORIES: readonly ["bug", "security", "perf", "tests", "tech-debt", "migration", "dx", "docs", "direction"];
+export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
+/**
+ * Validate the audit Status block(s) of a plan file against the field
+ * contract (mstar-audit SKILL § Plan files):
+ * - `Priority`: P1 | P2 | P3
+ * - `Effort`: XS | S | M | L | XL
+ * - `Risk`: LOW | MED | HIGH
+ * - `Depends on`: `none` or `plans/NNN-*.md` (the `*` is a literal
+ *   wildcard form — the documented scaffolded scheme; concrete
+ *   `plans/NNN-<slug>.md` paths are accepted too)
+ * - `Category`: bug | security | perf | tests | tech-debt | migration |
+ *   dx | docs | direction
+ * - `Planned at`: `commit <short SHA>, <YYYY-MM-DD>` — `commit unknown`
+ *   is accepted as the documented fallback (`scaffoldAuditPlan` default
+ *   when the CLI runs outside a git repo)
+ *
+ * Every `## Status` block in the document is checked; a document without
+ * any block gets `audit.status.missing-block`. Violation codes:
+ * `audit.status.missing-block`, `audit.status.missing-field`,
+ * `audit.status.invalid-priority|effort|risk|depends-on|category|planned-at`.
+ */
+export declare function validateAuditStatusBlocks(planText: string): GateResult;
+/** A redacted credential occurrence: 1-based line + credential type. */
+export type SecretFinding = {
+    line: number;
+    type: string;
+};
+/** Result of `redactSecrets`: redacted text + the findings summary. */
+export type RedactResult = {
+    text: string;
+    findings: SecretFinding[];
+};
+/**
+ * Scan text for credential patterns and replace every occurrence with a
+ * `[REDACTED <type>@<line> in <file>]` marker (file omitted when `filePath`
+ * is not provided), per mstar-audit Hard Rule 4. Newlines are preserved so
+ * line numbers stay stable. Returns the redacted text plus a deduplicated,
+ * line-sorted findings summary (`{ line, type }`).
+ */
+export declare function redactSecrets(text: string, filePath?: string): RedactResult;
+/** One audit finding, shaped after finding-format.md. */
+export type AuditFinding = {
+    title: string;
+    category: AuditCategory;
+    impact: string;
+    effort: AuditEffort;
+    risk: AuditRisk;
+    confidence: "HIGH" | "MED" | "LOW";
+    evidence: readonly string[];
+    priority: AuditPriority;
+    fixSketch?: string;
+    verification?: string;
+    dependsOn?: string;
+};
+/** Options for `scaffoldAuditPlan`. `plannedAt` defaults to the
+ * `repoShortSha` + `date`; `date` defaults to today (YYYY-MM-DD). */
+export type ScaffoldAuditPlanOptions = {
+    date?: string;
+    repoName?: string;
+    repoShortSha?: string;
+    plannedAt?: {
+        commit: string;
+        date: string;
+    };
+    rejected?: readonly {
+        title: string;
+        reason: string;
+    }[];
+};
+/** Result of `scaffoldAuditPlan`. `nextNumber` is the next free plan number
+ * (monotonic continuation vs. any pre-existing `NNN-*.md` files). */
+export type ScaffoldAuditPlanResult = {
+    outDir: string;
+    date: string;
+    files: string[];
+    nextNumber: number;
+};
+/**
+ * Scaffold an audit plan directory (`{PLAN_DIR}/audit-<date>/` layout,
+ * mstar-audit SKILL § Phase 4): numbered `NNN-<slug>.md` plan files from
+ * findings plus a README.md index. Numbering is monotonic — when the
+ * directory already contains `NNN-*.md` files (same-date re-run), the new
+ * batch continues after the highest existing number instead of restarting
+ * at 001, and the rebuilt index includes the pre-existing plans. Rejected
+ * findings render in the "considered and rejected" section.
+ */
+export declare function scaffoldAuditPlan(outDir: string, findings: readonly AuditFinding[], options?: ScaffoldAuditPlanOptions): ScaffoldAuditPlanResult;

package/dist/compound.d.ts

@@ -0,0 +1,90 @@
+import type { GateResult } from "./core.js";
+/** Required frontmatter fields (schema.yaml required_fields). */
+export declare const KNOWLEDGE_REQUIRED_FIELDS: readonly ["module", "date", "problem_type", "category", "severity"];
+/** All problem_type enum values (bug track + knowledge track). */
+export declare const KNOWLEDGE_PROBLEM_TYPES: readonly ["build_error", "test_failure", "runtime_error", "performance_issue", "database_issue", "security_issue", "ui_bug", "integration_issue", "logic_error", "config_error", "developer_experience", "workflow_issue", "best_practice", "documentation_gap", "architecture_pattern", "design_pattern", "tooling_decision", "convention", "api_design", "testing_pattern"];
+/** Bug-track problem_types (schema.yaml tracks.bug). */
+export declare const KNOWLEDGE_BUG_PROBLEM_TYPES: readonly ["build_error", "test_failure", "runtime_error", "performance_issue", "database_issue", "security_issue", "ui_bug", "integration_issue", "logic_error", "config_error"];
+/** Knowledge-track problem_types (schema.yaml tracks.knowledge). */
+export declare const KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES: readonly ["developer_experience", "workflow_issue", "best_practice", "documentation_gap", "architecture_pattern", "design_pattern", "tooling_decision", "convention", "api_design", "testing_pattern"];
+/** Severity enum (schema.yaml required_fields.severity). */
+export declare const KNOWLEDGE_SEVERITIES: readonly ["critical", "high", "medium", "low"];
+/** Bug-track resolution_type enum (schema.yaml track_rules.bug). */
+export declare const KNOWLEDGE_RESOLUTION_TYPES: readonly ["code_fix", "migration", "config_change", "test_fix", "dependency_update", "environment_setup", "workflow_improvement", "documentation_update", "tooling_addition"];
+/** problem_type → category directory (category-mapping.md; rule 1: the
+ * frontmatter `category` must match the mapped directory name). */
+export declare const KNOWLEDGE_CATEGORY_MAP: Readonly<Record<string, string>>;
+/**
+ * Validate a knowledge-doc frontmatter against the schema.yaml contract
+ * (embedded constants — no runtime skill-file reads):
+ * required fields (module, date, problem_type, category, severity), enum
+ * values, track rules (bug track needs symptoms / root_cause /
+ * resolution_type), category↔problem_type mapping consistency, and optional
+ * fields (plan_id, tags ≤ 8, last_updated, related_components).
+ *
+ * Violation codes:
+ * - `compound.schema.missing-frontmatter` — no `---` block
+ * - `compound.schema.missing-field` — required field absent/empty
+ * - `compound.schema.invalid-date` / `invalid-problem-type` /
+ *   `invalid-severity` / `invalid-resolution-type`
+ * - `compound.schema.category-mismatch` — category ≠ mapping for
+ *   problem_type (category-mapping.md rule 1)
+ * - `compound.schema.missing-track-field` — bug track missing
+ *   symptoms/root_cause/resolution_type
+ * - `compound.schema.invalid-symptoms` / `invalid-root-cause` /
+ *   `invalid-applies-when` / `invalid-plan-id` / `invalid-tags` /
+ *   `tags-too-many` / `invalid-last-updated` / `invalid-related-components`
+ */
+export declare function validateSchemaYaml(frontmatterText: string): GateResult;
+/** Result of `referenceExists`: gate verdict + number of refs verified. */
+export type ReferenceCheckResult = GateResult & {
+    checked: number;
+};
+/**
+ * Check that paths/functions referenced in a knowledge doc exist on disk
+ * (compound-refresh Phase 2 item 1: "Referenced code still exists?").
+ *
+ * Backticked refs are classified conservatively:
+ * - path-like refs (contain `/` or end in a known file extension) are
+ *   resolved against `repoRoot` and must exist — `:line` suffixes and
+ *   `#anchors` are stripped first; violation `compound.reference.missing-file`.
+ * - `module.symbol` refs use a documented heuristic: a module file named
+ *   `<module>.ts|tsx|js|jsx|mjs|cjs` must exist somewhere under `repoRoot`;
+ *   violation `compound.reference.module-missing` (low severity — heuristic).
+ * - URLs, `{PLACEHOLDER}` refs, globs, absolute paths, and bare symbols are
+ *   skipped (not repo-relative, or not resolvable deterministically).
+ * `checked` counts unique refs that verified.
+ */
+export declare function referenceExists(repoRoot: string, docText: string): ReferenceCheckResult;
+/**
+ * Assert every knowledge doc under `knowledgeDir` has a row in
+ * `knowledgeDir/README.md` (mstar-compound SKILL.md Phase 6 index
+ * obligations). Row first cells may be plain paths or `[title](path)`
+ * links, with optional `./` / `knowledge/` prefixes. `README.md` and
+ * `index.md` files are not docs.
+ *
+ * Violation codes:
+ * - `compound.index.missing-readme` — no README.md index
+ * - `compound.index.missing-row` — doc with no index row
+ */
+export declare function assertIndexRows(knowledgeDir: string): GateResult;
+/**
+ * The compound-refresh scope (mstar-compound-refresh SKILL.md §
+ * 产物与操作路径): `{HARNESS_DIR}/knowledge/**`, `knowledge/README.md`,
+ * `<repo-root>/CONCEPTS.md`, `{HARNESS_DIR}/status.json`.
+ */
+export declare function compoundRefreshScope(harnessDir: string, projectRoot: string): string[];
+/**
+ * Guard an operation path against the allowed root set (compound-refresh
+ * scope SSOT: only knowledge/**, knowledge/README.md, CONCEPTS.md, and
+ * status.json may be written). File-like roots require an exact match;
+ * directory roots allow any path beneath them. `..` traversal-out is
+ * rejected via `resolve()` normalization.
+ *
+ * Limitation (documented): the guard is lexical — `resolve()` never follows
+ * symlinks, so a symlink inside an allowed root that points outside is not
+ * detected. Real enforcement is host-side (the sandbox/approval layer).
+ *
+ * Violation code: `compound.scope.outside` (medium).
+ */
+export declare function scopeGuard(path: string, allowedRoots: readonly string[]): GateResult;

package/dist/core.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Severity levels used across harness validation results.
+ *
+ * Machine SSOT — `mstar-plan-artifacts/references/status-and-residuals.md`
+ * § "Residual findings: `severity` (SSOT, machine field)" defines the same
+ * five lowercase-English values; `warning` / `Major` / any other value are
+ * forbidden in JSON severity fields.
+ */
+export type Severity = "critical" | "high" | "medium" | "low" | "nit";
+/**
+ * Total order, heavy → light (spec: status-and-residuals.md § severity):
+ * `critical` > `high` > `medium` > `low` > `nit`. `nit` is always lighter
+ * than `low` — never invert or equate.
+ */
+export declare const SEVERITY_ORDER: readonly Severity[];
+/**
+ * Result of one harness validation check.
+ *
+ * Shape per `.harness/references/skill-programmatic-roadmap.md` §8.5 C4:
+ * `{ ok: boolean, severity, code, message, fix? }`. v1 enforcement is
+ * non-blocking: callers (CLI output readers, host hooks) surface it as a
+ * warning, never a hard stop.
+ */
+export type ValidationResult = {
+    ok: boolean;
+    severity: Severity;
+    code: string;
+    message: string;
+    fix?: string;
+    /**
+     * Backward-compat alias codes for the same violation, emitted by the
+     * engine's single parser (e.g. the Slice-2 `assignment.presence.*`
+     * namespace kept as aliases on the three core Assignment field
+     * violations — see `dispatch.requireField`). Consumers keyed off either
+     * namespace see exactly ONE violation per missing field.
+     */
+    aliases?: readonly string[];
+};
+/**
+ * Aggregate of validation checks for one gate (spec: roadmap §8.2 core row).
+ * `ok` is the gate verdict over `violations` — a gate with any violation
+ * does not pass.
+ *
+ * `hardBlocked` (Slice 5 / roadmap §8.5 C4 + D2) is the hard-enforcement
+ * overlay: `true` when the gate has violations AND the caller requested hard
+ * mode via `applyEnforcement`. Absent/`false` means warn-only — the caller
+ * may proceed with a warning. A caller that can refuse an action MUST refuse
+ * when `hardBlocked === true`.
+ */
+export type GateResult = {
+    ok: boolean;
+    violations: ValidationResult[];
+    hardBlocked?: boolean;
+};
+/**
+ * Apply hard-enforcement semantics to a gate result (roadmap §8.5 C4/D2):
+ * `hardBlocked` is `true` exactly when `hard` is requested AND the gate has
+ * violations. `ok` and `violations` are preserved — enforcement is an
+ * overlay on the verdict, never a re-validation. When `hard` is false
+ * (flag absent/unset) the result is warn-only (`hardBlocked: false`), so
+ * rollback is simply unsetting the flag. Returns a NEW result; the input
+ * gate is not mutated.
+ */
+export declare function applyEnforcement(gate: GateResult, opts: {
+    hard: boolean;
+}): GateResult;
+/**
+ * Read and parse a JSON document. Missing or empty files read as `{}`
+ * (same contract as the CLI helper this consolidates); malformed JSON
+ * throws with the file path in the message.
+ */
+export declare function readJson(filePath: string): Record<string, unknown>;
+/**
+ * Serialize `value` as pretty JSON with a trailing newline and write it
+ * atomically: temp file in the same directory, then rename over the target.
+ * Creates parent directories as needed; on failure the temp file is removed
+ * and the error rethrown, so the target is never partially written.
+ *
+ * Durability note (qc2 F-013): no fsync before the rename — atomicity (no
+ * partial file) is guaranteed by the same-dir temp + rename, but a power
+ * loss immediately after rename may lose the write. Acceptable for
+ * coordination files (status.json) whose writers re-read + verify the
+ * stored state; revisit if the harness moves to a filesystem without
+ * rename-atomicity guarantees.
+ */
+export declare function writeJson(filePath: string, value: Record<string, unknown>): void;
+/**
+ * Resolve the project root by walking up from `startDir` (default: cwd) to
+ * the nearest ancestor containing `package.json` or `bun.lock`. Falls back
+ * to the resolved `startDir` when no marker exists up to the filesystem root.
+ */
+export declare function resolveProjectRoot(startDir?: string): string;
+/**
+ * Resolve the harness version from a module directory: the module's OWN
+ * manifest first (`<moduleDir>/../package.json` — always shipped by npm,
+ * e.g. `node_modules/@mstar-harness/engine/package.json` next to
+ * `dist/engine.js`, or the CLI/opencode package.json next to their bundles),
+ * falling back to the monorepo root `morning-star` `package.json` walk.
+ * The single-version invariant makes both equivalent in-repo; the
+ * own-manifest-first order fixes published installs, where no
+ * `morning-star` manifest exists anywhere above `node_modules` and the walk
+ * alone would regress to `"0.0.0"` (qc3 F-1).
+ */
+export declare function harnessVersionFrom(moduleDir: string): string;
+/**
+ * Read the harness version (own-manifest first — see `harnessVersionFrom`).
+ *
+ * Single source for the harness version inside TS (roadmap §8.5 C6, moved
+ * from `packages/cli/src/utils.ts`); the CLI re-exports it unchanged. The
+ * single-version invariant keeps root, engine, cli and opencode aligned.
+ */
+export declare function readHarnessVersion(): string;

package/dist/design-md.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Engine design-md module — DESIGN.md token frontmatter validation, light/dark
+ * parity, and completeness level audit.
+ *
+ * Spec sources (all embedded as constants — no runtime skill-file reads):
+ * - mstar-design-md SKILL.md: YAML frontmatter is the SSOT for token values;
+ *   dual theme = same token names, different values; three completeness
+ *   levels with LEVEL2/LEVEL3_PLACEHOLDER upgrade markers.
+ * - mstar-design-md/references/design-md-spec.md §1.5 (token store: colors /
+ *   typography / spacing / rounded / components shapes), §3 (token naming),
+ *   §4 (light/dark contract), §5 (upgrade placeholders), §6 ({path} refs).
+ * - mstar-design-md/references/completeness-checklist.md: Level 1–3 items;
+ *   placeholders (`"[...]"`) never count as complete.
+ *
+ * Judgment stays prompt — this module is the deterministic half.
+ */
+import type { GateResult } from "./core.js";
+/** Parsed DESIGN.md frontmatter. Group values are `unknown` because a
+ * malformed group (e.g. `colors: red`) is a scalar; validation reports it. */
+export type DesignFrontmatter = {
+    version?: string;
+    name?: string;
+    description?: string;
+    colors: Record<string, unknown>;
+    typography: Record<string, unknown>;
+    spacing: Record<string, unknown>;
+    rounded: Record<string, unknown>;
+    components: Record<string, unknown>;
+};
+/**
+ * Parse the leading `---`-fenced YAML frontmatter of a DESIGN.md into the
+ * five token groups plus version/name/description. Commented-out lines
+ * (including `# LEVEL2_PLACEHOLDER:` markers) are skipped, so only ACTIVE
+ * tokens count — matching the checklist rule that commented keys are not
+ * complete. Returns `null` when the text has no frontmatter block.
+ *
+ * A token group whose YAML value is a scalar is stored as
+ * `{ [RAW_GROUP]: <value> }` so validation can report `group-not-map`.
+ */
+export declare function parseDesignFrontmatter(frontmatterText: string): DesignFrontmatter | null;
+/**
+ * Validate a DESIGN.md frontmatter against the token-store contract
+ * (design-md-spec §1.5): the colors/typography/spacing/rounded groups must
+ * exist with spec-typed values, `components` (optional below Level 2) must
+ * carry `{path}` references that resolve within the same file.
+ *
+ * Violation codes:
+ * - `design-md.tokens.missing-frontmatter` — no `---` block
+ * - `design-md.tokens.missing-group` — required group absent/empty
+ * - `design-md.tokens.group-not-map` — group value is a scalar
+ * - `design-md.tokens.color-format` — not hex or oklch()
+ * - `design-md.tokens.typography-shape` — not exactly the five properties
+ * - `design-md.tokens.spacing-base` / `spacing-key` / `spacing-format`
+ * - `design-md.tokens.rounded-format` — not a px length
+ * - `design-md.tokens.components-shape` — component entry not a map
+ * - `design-md.tokens.ref-unresolved` — `{group.key}` does not resolve
+ * - `design-md.tokens.placeholder` — `"[...]"` template value (low)
+ */
+export declare function validateDesignTokenFrontmatter(frontmatterText: string): GateResult;
+/**
+ * Assert the light/dark dual-theme contract (design-md-spec §4 rules 1–4):
+ * both files define the SAME token key set across all five groups; only
+ * values differ. Every token active in one file must be active in the other.
+ *
+ * Violation codes:
+ * - `design-md.parity.missing-frontmatter` — either file has no block
+ * - `design-md.parity.missing-dark` — token present in light only
+ * - `design-md.parity.missing-light` — token present in dark only
+ */
+export declare function assertLightDarkParity(lightFm: string, darkFm: string): GateResult;
+/** Completeness level verdict (checklist § Verdict). */
+export type CompletenessLevel = "BELOW_MVP" | "MVP" | "Standard" | "Production";
+/** One checklist item: id, owning level, source, and pass/fail. */
+export type CompletenessItem = {
+    id: string;
+    level: 1 | 2 | 3;
+    ok: boolean;
+    source: "frontmatter" | "body";
+};
+/** A `LEVEL2_PLACEHOLDER` / `LEVEL3_PLACEHOLDER` marker found in the text. */
+export type CompletenessPlaceholder = {
+    level: 2 | 3;
+    marker: string;
+    line: number;
+};
+/** Result of `completenessLevel`. `bodyUnverified` is true when the caller
+ * passed no checklist (body-only items were excluded from the level
+ * computation and Production is capped at Standard). */
+export type CompletenessResult = {
+    level: CompletenessLevel;
+    items: CompletenessItem[];
+    /** Ids failing at the next-highest level boundary (or the current level
+     * when below MVP). */
+    missing: string[];
+    placeholders: CompletenessPlaceholder[];
+    upgradeTo: 2 | 3 | null;
+    bodyUnverified: boolean;
+};
+/**
+ * Determine the DESIGN.md completeness level from its frontmatter
+ * (completeness-checklist.md): Level 1 (MVP) → Level 2 (Standard) → Level 3
+ * (Production). A level is complete only when all items at that level and
+ * below pass; placeholder values and commented-out keys never count.
+ *
+ * Body-only items (breakpoints, elevation, motion, voice, dark-file) cannot
+ * be verified from frontmatter — pass their ids in `checklist` to confirm
+ * them. When `checklist` is omitted, body items are excluded from level
+ * computation and Production is capped at Standard (`bodyUnverified: true`).
+ *
+ * Placeholder detection scans for `LEVEL2_PLACEHOLDER` / `LEVEL3_PLACEHOLDER`
+ * markers (design-md-spec §5) and suggests the implied upgrade target.
+ */
+export declare function completenessLevel(frontmatterText: string, checklist?: readonly string[]): CompletenessResult;

package/dist/dispatch.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 = {
+    executeAs?: string;
+    delegation?: string;
+    taskCategory?: string;
+    workingBranch?: string;
+    branchPolicy?: string;
+};
+export type ValidateAssignmentFieldsOptions = {
+    /**
+     * Whether the assignment produces repo diffs (default `true`). The
+     * branch-form exactly-one gate applies to writable assignments only —
+     * read-only assignments (explore/scout orientation) legitimately omit
+     * branch fields per mstar-branch-worktree ("每个可写 Assignment…").
+     */
+    writable?: boolean;
+};
+/** Options for {@link assertDefaultBranchProtected}. */
+export type DefaultBranchOptions = {
+    /** Protected default branch names (project convention; default `main`/`master`). */
+    defaultBranches?: readonly string[];
+    /** True when the Assignment carries an explicit `Branch policy: direct on …` exception. */
+    directOnException?: boolean;
+};
+/** Options for {@link executionModeToN}. */
+export type ExecutionModeToNOptions = {
+    /** Listed reviewer seats for `targeted` re-review (`QC re-review: targeted — reviewers: …`). */
+    seats?: readonly string[];
+};
+/** Result of {@link executionModeToN}: a GateResult carrying `n` on success. */
+export type ExecutionModeToNResult = GateResult & {
+    n?: number;
+};
+/**
+ * Parse `**Field**: value` (or plain `Field: value`) header lines from an
+ * Assignment into the dispatch-relevant fields. Only known field labels are
+ * captured; values are trimmed. List-bullet prefixes (`- **Field**: value`)
+ * are accepted so the engine parser is the SINGLE grammar for Assignment
+ * header fields (the Slice-2 opencode presence parser tolerated bullets;
+ * its acceptance is folded into this parser, not forked — qc1 F-002).
+ */
+export declare function parseAssignmentFields(assignmentText: string): AssignmentFields;
+/** Where the `Enforcement` flag was declared (roadmap §8.5 C4/D2). */
+export type EnforcementSource = "assignment" | "compass" | "none";
+/** Parsed hard-enforcement flag. `hard: false` + `source: none` = flag absent. */
+export type EnforcementFlag = {
+    hard: boolean;
+    source: EnforcementSource;
+};
+/**
+ * Slice an Assignment's header region — the text before the first body
+ * marker (see {@link ASSIGNMENT_BODY_START_RE}). Returns the full text when
+ * no marker is present. The Assignment enforcement flag is parsed against
+ * THIS region only, so an example line `**Enforcement**: hard` quoted in the
+ * task body cannot harden the dispatch (qc1 F-003 / qc2 F-003).
+ */
+export declare function assignmentHeaderRegion(assignmentText: string): string;
+/**
+ * Parse the `Enforcement: hard` flag (roadmap §8.5 C4 + decision D2 — v2
+ * hard gates are OPT-IN per Assignment/compass, never global; rollback =
+ * unset flag; inert when the engine is absent).
+ *
+ * Recognized forms, checked in order:
+ * 1. Assignment header `**Enforcement**: hard` / `Enforcement: hard`
+ *    (bold or plain, optional list bullet; value case-insensitive).
+ * 2. Compass frontmatter YAML key `enforcement: hard` (lowercase key;
+ *    value may be quoted, case-insensitive).
+ *
+ * The Assignment form wins over the compass form when both appear in the
+ * input (per-Assignment precedence — a dispatch's own flag is decisive).
+ * A present-but-non-hard value (`soft`, empty, malformed) still reports
+ * its source so callers can distinguish "explicitly not hard" from
+ * "not mentioned" (`source: none`). Never throws.
+ *
+ * Assignment-form callers MUST pass the header region (see
+ * {@link assignmentHeaderRegion}) — this function itself scans the whole
+ * input because the compass form is fed raw frontmatter, which has no
+ * body markers (qc1 F-003 / qc2 F-003).
+ */
+export declare function parseEnforcementFlag(text: string): EnforcementFlag;
+/**
+ * Parsed branch forms of an Assignment (mstar-branch-worktree § "Assignment
+ * 要求"): `Working branch: <existing>` | `Working branch: create <new> from
+ * <base>` | `Branch policy: direct on <branch> — <reason>`. Exactly one is
+ * required for writable assignments. This is the engine's SINGLE branch-form
+ * grammar — CLI and host hooks consume it instead of re-implementing the
+ * regexes (qc1 F-001 / qc3 F-3).
+ */
+export type AssignmentBranchForms = {
+    /**
+     * `Working branch: <existing>` — the value's first token (create-form
+     * values are excluded and land in {@link createForm} instead).
+     */
+    workingBranch?: string;
+    /** `Working branch: create <new> from <base>` — created branch name (+ base when written). */
+    createForm?: {
+        name: string;
+        base?: string;
+    };
+    /**
+     * `Branch policy: direct on <branch> — <reason>` — branch captured by the
+     * loose `direct on <branch>` prefix; `reason` is the strict-form reason
+     * ("" when the value is not a well-formed direct-on form, i.e. no
+     * separator + non-empty reason — mirror of `validateAssignmentFields`).
+     */
+    directOn?: {
+        branch: string;
+        reason: string;
+    };
+};
+/**
+ * Parse an Assignment's branch forms via the engine's single parser
+ * (`parseAssignmentFields` + {@link parseWorkingBranchValue}). Consumed by
+ * the CLI `dispatch validate` gate-branch derivation and the opencode hook;
+ * also the internal grammar behind `validateAssignmentFields`.
+ */
+export declare function parseAssignmentBranchForms(assignmentText: string): AssignmentBranchForms;
+/**
+ * Parse the Assignment's `Branch policy: direct on <branch> — <reason>`
+ * exception branch. Returns the branch ONLY for the well-formed direct-on
+ * form (branch + non-empty reason; separator set [—–]|--|-); undefined when
+ * absent or malformed — the default-branch gate recognizes explicit
+ * direct-on exceptions only. Single engine grammar shared by CLI + plugin
+ * (qc1 F-001).
+ */
+export declare function parseBranchPolicyDirectOnBranch(assignmentText: string): string | undefined;
+/**
+ * True when the Assignment's `Execute as` role is a read-only orientation
+ * role (`scout` / `explore`, case-insensitive). Read-only assignments
+ * legitimately omit branch forms (mstar-branch-worktree § "每个可写
+ * Assignment…") — callers pass `validateAssignmentFields(text, { writable:
+ * false })` and skip the default-branch gate for them (qc3 F-1 / qc2 S-5).
+ */
+export declare function isReadOnlyAssignmentRole(roleId: string): boolean;
+/**
+ * Validate an Assignment's header fields (mstar-dispatch-gates Assignment
+ * field contract + mstar-branch-worktree branch-form contract).
+ *
+ * Required: `Execute as` / `Delegation` / `Task category` present with
+ * non-empty values (paste-only shells are caught here — every field missing).
+ * Writable assignments must carry EXACTLY ONE branch form; `create <new>
+ * from <base>` without `<base>` (incl. the dangling `create <new> from`
+ * / `create from <base>` typos) and `Branch policy` without branch/reason
+ * are flagged. The three core-field violations carry the legacy
+ * `assignment.presence.*` codes as aliases (qc1 F-002).
+ */
+export declare function validateAssignmentFields(assignmentText: string, opts?: ValidateAssignmentFieldsOptions): GateResult;
+/**
+ * Flag writable work on a default protected branch (`main`/`master` per
+ * project convention) unless an explicit direct-on exception is present
+ * (mstar-branch-worktree § "Git 功能分支门禁"). `directOnException` mirrors
+ * the Assignment carrying `Branch policy: direct on <branch> — <reason>`.
+ */
+export declare function assertDefaultBranchProtected(branch: string, opts?: DefaultBranchOptions): GateResult;
+/**
+ * Map an Assignment `Execution mode` to its QC seat count N
+ * (mstar-dispatch-gates § QC tri / 单席 / targeted): `sdd` → 3 (tri),
+ * `inline` → 1, `targeted` → the listed reviewer seats. Unknown or missing
+ * modes are violations.
+ */
+export declare function executionModeToN(executionMode: string, opts?: ExecutionModeToNOptions): ExecutionModeToNResult;
+/**
+ * Assert the initial QC wave's reviewer roles are exactly
+ * `qc-specialist` / `qc-specialist-2` / `qc-specialist-3`
+ * (mstar-dispatch-gates § QC tri-review; mstar-roles QC reviewer 参数表).
+ * Any other composition — missing seat, duplicate, or foreign role — fails.
+ */
+export declare function assertTriIdentity(reviewerRoles: readonly string[]): GateResult;
+/**
+ * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
+ * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding
+ * field (`subagent_type` / `agent` / `subagent`) equals its own `Execute as`.
+ * Comparison is case-insensitive after trim; an empty binding is not a
+ * self-recursion (its presence is the field gate's job, not this precheck).
+ */
+export declare function antiRecursionPrecheck(subagentType: string, executeAs: string): GateResult;