@mstar-harness/engine 3.6.2 → 3.7.0

package/dist/audit.d.ts

@@ -23,13 +23,13 @@ export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
  * - `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)
+ * 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
+ * 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)
+ * 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:
@@ -121,8 +121,7 @@ export type ScannedSecret = {
  * pattern evaluation (only the span — a key beside it still fires). Files
  * that cannot be read are counted in `unreadableFiles` instead of being
  * silently skipped: a security gate must never report clean over input it
- * could not inspect (qc1 W-002).
- */
+ * could not inspect. */
 /** Result of {@link scanSecrets}: findings plus how many selected files
  * could not be read (fail-closed signal for CLI gates). */
 export type ScanSecretsResult = {
@@ -145,14 +144,14 @@ export type SupplyChainResult = GateResult & {
 /**
  * Deterministic supply-chain checks over `repoRoot` (read-only):
  * - `lockfile-missing`: no recognized lockfile at the repo root
- *   (package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock[b] /
- *   Cargo.lock / poetry.lock / uv.lock / Gemfile.lock / composer.lock).
+ * (package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock[b] /
+ * Cargo.lock / poetry.lock / uv.lock / Gemfile.lock / composer.lock).
  * - `lockfile-duplicate`: two or more distinct lockfiles at the root —
- *   ambiguous install boundaries.
+ * ambiguous install boundaries.
  * - `action-unpinned`: `.github/workflows/*.yml` steps using mutable refs
- *   (`@main`, `@master`, `@latest` or any non-SHA ref).
+ * (`@main`, `@master`, `@latest` or any non-SHA ref).
  * - `pull_request_target-head`: a workflow triggers on `pull_request_target`
- *   AND checks out the PR head — untrusted code with secrets access.
+ * AND checks out the PR head — untrusted code with secrets access.
  *
  * Tri-age judgment (reachable / runtime-relevant) is deliberately left to
  * the reviewer (C-class). Violation codes mirror finding kinds with the

package/dist/compound.d.ts

@@ -26,14 +26,14 @@ export declare const KNOWLEDGE_CATEGORY_MAP: Readonly<Record<string, string>>;
  * - `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`
+ * `invalid-severity` / `invalid-resolution-type`
  * - `compound.schema.category-mismatch` — category ≠ mapping for
- *   problem_type (category-mapping.md rule 1)
+ * problem_type (category-mapping.md rule 1)
  * - `compound.schema.missing-track-field` — bug track missing
- *   symptoms/root_cause/resolution_type
+ * 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`
+ * `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. */
@@ -46,13 +46,13 @@ export type ReferenceCheckResult = GateResult & {
  *
  * 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`.
+ * 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).
+ * `<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).
+ * skipped (not repo-relative, or not resolvable deterministically).
  * `checked` counts unique refs that verified.
  */
 export declare function referenceExists(repoRoot: string, docText: string): ReferenceCheckResult;

package/dist/core.d.ts

@@ -76,7 +76,7 @@ export declare function readJson(filePath: string): Record<string, unknown>;
  * 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
+ * Durability note : 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
@@ -99,8 +99,7 @@ export declare function resolveProjectRoot(startDir?: string): string;
  * 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).
- */
+ * alone would regress to `"0.0.0"`. */
 export declare function harnessVersionFrom(moduleDir: string): string;
 /**
  * Read the harness version (own-manifest first — see `harnessVersionFrom`).

package/dist/dispatch.d.ts

@@ -9,11 +9,11 @@ export type AssignmentFields = {
 };
 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…").
-     */
+   * 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}. */
@@ -38,7 +38,7 @@ export type ExecutionModeToNResult = GateResult & {
  * 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).
+ * its acceptance is folded into this parser, not forked —).
  */
 export declare function parseAssignmentFields(assignmentText: string): AssignmentFields;
 /** Where the `Enforcement` flag was declared (roadmap §8.5 C4/D2). */
@@ -53,8 +53,7 @@ export type EnforcementFlag = {
  * 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).
- */
+ * task body cannot harden the dispatch. */
 export declare function assignmentHeaderRegion(assignmentText: string): string;
 /**
  * Parse the `Enforcement: hard` flag (roadmap §8.5 C4 + decision D2 — v2
@@ -63,9 +62,9 @@ export declare function assignmentHeaderRegion(assignmentText: string): string;
  *
  * Recognized forms, checked in order:
  * 1. Assignment header `**Enforcement**: hard` / `Enforcement: hard`
- *    (bold or plain, optional list bullet; value case-insensitive).
+ * (bold or plain, optional list bullet; value case-insensitive).
  * 2. Compass frontmatter YAML key `enforcement: hard` (lowercase key;
- *    value may be quoted, case-insensitive).
+ * 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).
@@ -76,8 +75,7 @@ export declare function assignmentHeaderRegion(assignmentText: string): string;
  * 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).
- */
+ * body markers. */
 export declare function parseEnforcementFlag(text: string): EnforcementFlag;
 /**
  * Parsed branch forms of an Assignment (mstar-branch-worktree § "Assignment
@@ -85,13 +83,12 @@ export declare function parseEnforcementFlag(text: string): EnforcementFlag;
  * <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).
- */
+ * regexes. */
 export type AssignmentBranchForms = {
     /**
-     * `Working branch: <existing>` — the value's first token (create-form
-     * values are excluded and land in {@link createForm} instead).
-     */
+   * `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?: {
@@ -99,11 +96,11 @@ export type AssignmentBranchForms = {
         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`).
-     */
+   * `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;
@@ -122,16 +119,14 @@ export declare function parseAssignmentBranchForms(assignmentText: string): Assi
  * 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).
- */
+ * false })` and skip the default-branch gate for them. */
 export declare function isReadOnlyAssignmentRole(roleId: string): boolean;
 /**
  * Validate an Assignment's header fields (mstar-dispatch-gates Assignment
@@ -143,8 +138,7 @@ export declare function isReadOnlyAssignmentRole(roleId: string): boolean;
  * 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).
- */
+ * `assignment.presence.*` codes as aliases. */
 export declare function validateAssignmentFields(assignmentText: string, opts?: ValidateAssignmentFieldsOptions): GateResult;
 /**
  * Flag writable work on a default protected branch (`main`/`master` per
@@ -161,7 +155,7 @@ export declare function assertDefaultBranchProtected(branch: string, opts?: Defa
  */
 export declare function executionModeToN(executionMode: string, opts?: ExecutionModeToNOptions): ExecutionModeToNResult;
 /**
- * Assert the initial QC wave's reviewer roles are exactly
+ * Assert the initial review 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.
@@ -172,28 +166,28 @@ export declare function assertTriIdentity(reviewerRoles: readonly string[]): Gat
  */
 export type ComposeDispatchGateOptions = {
     /**
-     * Dispatching agent's OWN harness role (dsh `Config.dispatchBinding`).
-     * When non-empty, the anti-recursion precheck compares it against the
-     * Assignment's `Execute as` — equality is self-recursion
-     * (`dispatch.anti-recursion.self-type`, critical). Leave unset on hosts
-     * whose tool-call event cannot report the dispatching agent's identity
-     * (omp/opencode/cursor): the precheck is skipped there and the NEVER red
-     * line stays prompt-level (mstar-dispatch-gates).
-     */
+   * Dispatching agent's OWN harness role (dsh `Config.dispatchBinding`).
+   * When non-empty, the anti-recursion precheck compares it against the
+   * Assignment's `Execute as` — equality is self-recursion
+   * (`dispatch.anti-recursion.self-type`, critical). Leave unset on hosts
+   * whose tool-call event cannot report the dispatching agent's identity
+   * (omp/opencode/cursor): the precheck is skipped there and the NEVER red
+   * line stays prompt-level (mstar-dispatch-gates).
+   */
     caller?: string;
     /**
-     * True on hosts whose contract declares the caller binding mandatory
-     * (dsh): an empty/missing `caller` then fails closed with
-     * `dispatch.anti-recursion.empty-binding` (critical) — the host could
-     * have declared the binding, so an absent one proves nothing and the
-     * dispatch must not proceed as if the NEVER red line held. Default
-     * `false`: the precheck is skipped entirely when `caller` is empty.
-     */
+   * True on hosts whose contract declares the caller binding mandatory
+   * (dsh): an empty/missing `caller` then fails closed with
+   * `dispatch.anti-recursion.empty-binding` (critical) — the host could
+   * have declared the binding, so an absent one proves nothing and the
+   * dispatch must not proceed as if the NEVER red line held. Default
+   * `false`: the precheck is skipped entirely when `caller` is empty.
+   */
     callerRequired?: boolean;
     /**
-     * `false` for read-only roles (scout/explore) — skips the branch-form and
-     * default-branch gates. Default: `true` (writable).
-     */
+   * `false` for read-only roles (scout/explore) — skips the branch-form and
+   * default-branch gates. Default: `true` (writable).
+   */
     writable?: boolean;
 };
 /**
@@ -207,31 +201,30 @@ export type ComposeDispatchGateResult = GateResult & {
     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
+ * Shared host dispatch-gate composition — 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`).
+ * (`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.
+ * === false` (read-only roles), else the writable default.
  * 3. Anti-recursion precheck — CALLER semantics (issue #156): runs only
- *    when the host supplies its own role binding (`caller`), or fails
- *    closed on an empty one when the host contract requires it
- *    (`callerRequired`, dsh). A caller equal to `Execute as` is the
- *    `dispatch.anti-recursion.self-type` critical; a required-but-empty
- *    caller is `dispatch.anti-recursion.empty-binding`. Target-only hosts
- *    (omp/opencode/cursor) skip the leg — their binding field carries the
- *    spawn TARGET, which equals `Execute as` on every compliant dispatch.
+ * when the host supplies its own role binding (`caller`), or fails
+ * closed on an empty one when the host contract requires it
+ * (`callerRequired`, dsh). A caller equal to `Execute as` is the
+ * `dispatch.anti-recursion.self-type` critical; a required-but-empty
+ * caller is `dispatch.anti-recursion.empty-binding`. Target-only hosts
+ * (omp/opencode/cursor) skip the leg — their binding field carries the
+ * spawn TARGET, which equals `Execute as` on every compliant dispatch.
  * 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.
+ * 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`.
+ * result carries `hardBlocked` via `applyEnforcement`.
  *
  * Never throws on text errors: unexpected failures degrade to the same
  * silent non-shaped result.