@mstar-harness/engine 3.6.3 → 3.7.1

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

package/dist/prreview.d.ts

@@ -57,8 +57,7 @@ export type PrTallyResult = {
  */
 export declare function computePrTally(input: PrTallyInput): PrTallyResult;
 /**
- * One accepted PR-review finding in the `mstar.review/v1` envelope (SP3 §
- * Schema). `mergeClass` is harness vocab (MERGE_CLASSES); `title`/`body`
+ * One accepted PR-review finding in the `mstar.review/v1` envelope (the review envelope schema). `mergeClass` is harness vocab (MERGE_CLASSES); `title`/`body`
  * are non-empty strings; the rest are optional.
  */
 export type MstarReviewFinding = {
@@ -72,7 +71,7 @@ export type MstarReviewFinding = {
     fingerprint_hint?: string;
 };
 /**
- * The `mstar.review/v1` envelope (SP3 § Schema) — a parseable review
+ * The `mstar.review/v1` envelope (the review envelope schema) — a parseable review
  * document with harness vocab, sibling to the Markdown pr-review report.
  * `verdict` is PR_VERDICTS; `tally` (when present) must be a full
  * `PrTallyResult` (shape-checked) whose `verdict` must equal the top-level
@@ -92,7 +91,7 @@ export type MstarReviewV1 = {
     };
 };
 /**
- * Validate a `mstar.review/v1` envelope (SP3 § Schema). Fail-loud sibling
+ * Validate a `mstar.review/v1` envelope (the review envelope schema). Fail-loud sibling
  * of {@link validatePrReviewReport} (the Markdown report validator) —
  * shares PR_VERDICTS / MERGE_CLASSES only, never reuses the Markdown
  * parser. Inspector M1 vocab (`comment|request_changes|approve`,
@@ -108,7 +107,7 @@ export type MstarReviewV1 = {
 export declare function validateMstarReviewV1(doc: unknown): GateResult;
 /**
  * Fold already-vetted findings into a complete `mstar.review/v1` envelope
- * (SP3 § synthesizeReview). Pure and synchronous — verdict/tally come ONLY
+ * . Pure and synchronous — verdict/tally come ONLY
  * from {@link computePrTally}; no I/O, no GitHub, no store, no seat
  * dispatch. `findings` pass through untouched; `target` is carried when
  * provided. When `summary_md` is omitted, {@link defaultReviewSummary}
@@ -126,11 +125,11 @@ export declare function synthesizeReview(input: {
  *
  * - `pr` — reviewed PR number `n`.
  * - `branch` — bare branch, `slug` is the pre-slugged `<branch-slug>`
- *   (caller slugs; the resolver only guards path safety).
+ * (caller slugs; the resolver only guards path safety).
  * - `diff` — arbitrary changeset. When `headSha` is a non-empty string its
- *   short form (first 7 hex chars) lands in the filename; when absent or an
- *   empty string the bare `-diff` stem is used — a missing SHA is **never
- *   fabricated** (pr-review.md § Local report archive, Filename bullet).
+ * short form (first 7 hex chars) lands in the filename; when absent or an
+ * empty string the bare `-diff` stem is used — a missing SHA is **never
+ * fabricated** (pr-review.md § Local report archive, Filename bullet).
  */
 export type PrReportTarget = {
     kind: "pr";
@@ -148,16 +147,16 @@ export type PrReportTarget = {
  * never writes and never overwrites):
  *
  * - `<YYYY-MM-DD>-pr<N>.md` for PR targets; bare branch →
- *   `<YYYY-MM-DD>-<branch-slug>.md`; diff with head SHA →
- *   `<YYYY-MM-DD>-diff-<short-head-sha>.md`; diff without →
- *   `<YYYY-MM-DD>-diff.md` (never fabricate a SHA).
+ * `<YYYY-MM-DD>-<branch-slug>.md`; diff with head SHA →
+ * `<YYYY-MM-DD>-diff-<short-head-sha>.md`; diff without →
+ * `<YYYY-MM-DD>-diff.md` (never fabricate a SHA).
  * - `stage: 1 | 2` requires `slug` (the seat Assignment's `<domain>-<seat>`
- *   slug) and produces the Stage 1/2 evidence-file stem
- *   `<stem>-stage<1|2>-<slug>.md`.
+ * slug) and produces the Stage 1/2 evidence-file stem
+ * `<stem>-stage<1|2>-<slug>.md`.
  * - Same day, same target (same final stem): scans ALL existing files in
- *   `reportsDir` with that stem and appends `-r2`, `-r3`, ... on collision —
- *   a prior report is never overwritten. Report files and evidence files
- *   escalate independently (different stems).
+ * `reportsDir` with that stem and appends `-r2`, `-r3`, ... on collision —
+ * a prior report is never overwritten. Report files and evidence files
+ * escalate independently (different stems).
  * - `date` defaults to the local calendar date and must be `YYYY-MM-DD`.
  */
 export declare function prReviewReportPath(opts: {
@@ -174,22 +173,22 @@ export declare function prReviewReportPath(opts: {
  *
  * - `type: pr-review` required.
  * - `verdict` exactly one of the three verdict tokens (§ Verdict synthesis)
- *   and CONSISTENT with the tally (any must_fix -> blocked; else any
- *   should_fix -> needs fixes; else ship it).
+ * and CONSISTENT with the tally (any must_fix -> blocked; else any
+ * should_fix -> needs fixes; else ship it).
  * - `score_pct` integer 0-100 and equal to the locked-formula recompute
- *   from the document's own tally via {@link computePrTally}
- *   (mismatch = hand-arithmetic drift — the exact defect class this gate
- *   exists to catch).
+ * from the document's own tally via {@link computePrTally}
+ * (mismatch = hand-arithmetic drift — the exact defect class this gate
+ * exists to catch).
  * - `tally` flow map with the four classes.
  * - `comments` tri-state: `posted` (alias `yes`) | `n/a-no-pr` | `failed`.
- *   The states are distinct: a FAILED POST IS `FAILED`, never
- *   `n/a-no-pr`; `review_url` must pair accordingly (`http(s)://` for
- *   posted, `n/a` for n/a-no-pr, a `failed: <gh error summary>` for failed).
+ * The states are distinct: a FAILED POST IS `FAILED`, never
+ * `n/a-no-pr`; `review_url` must pair accordingly (`http(s)://` for
+ * posted, `n/a` for n/a-no-pr, a `failed: <gh error summary>` for failed).
  * - `generated_at` must be `YYYY-MM-DD` (DATE_RE).
  * - `tier` optional: `quick | default | deep`; absent is valid (legacy
- *   reports without tier still pass — SP-A amendment).
+ * reports without tier still pass — SP-A amendment).
  * - `elapsed` optional: non-negative integer minutes; absent is valid
- *   (legacy reports without elapsed still pass).
+ * (legacy reports without elapsed still pass).
  */
 export declare function validatePrReviewReport(text: string): GateResult;
 /** One inline review comment: `path` + `line` in the three-dot diff, RIGHT
@@ -221,14 +220,14 @@ export type ReviewPostPlan = {
  * 422 fallback stay with the CLI, which owns the network):
  *
  * - Resolves the target from `gh pr view --json url,headRefOid` output:
- *   parse `owner/repo` from `url` ONLY — the BASE repo that owns the PR
- *   number. `headRepository` (fork head-repo data) is IGNORED: fork PRs
- *   are legal, and a fork's owner/name must never leak into the API path.
- *   It is never used as a fallback either.
+ * parse `owner/repo` from `url` ONLY — the BASE repo that owns the PR
+ * number. `headRepository` (fork head-repo data) is IGNORED: fork PRs
+ * are legal, and a fork's owner/name must never leak into the API path.
+ * It is never used as a fallback either.
  * - Missing/invalid `headRefOid` throws — there is no commit_id without
- *   it.
+ * it.
  * - `event` is always the literal `"COMMENT"`; no other value exists in
- *   this contract.
+ * this contract.
  * - Inline comments validated per-entry (path / positive line / RIGHT).
  */
 export declare function planReviewPost(prView: {
@@ -256,13 +255,13 @@ export type ReviewChangesetMode = "pr" | "branch" | "diff" | "working-tree" | "c
  * (pr-review.md § Worktree isolation Pre-flight bullet, all modes):
  *
  * - Named refs must resolve in modes that HAVE refs (pr / branch / commit);
- *   establish them with explicit refspecs first.
+ * establish them with explicit refspecs first.
  * - The changeset must be NON-empty in ALL modes — an empty changeset
- *   reports "no changes to review" and stops before any lens fan-out.
+ * reports "no changes to review" and stops before any lens fan-out.
  * - For working-tree input, untracked-only changes ARE a non-empty
- *   changeset: the caller folds `git ls-files --others
- *   --exclude-standard` output into `changesetEmpty: false` when anything
- *   is listed.
+ * changeset: the caller folds `git ls-files --others
+ * --exclude-standard` output into `changesetEmpty: false` when anything
+ * is listed.
  */
 export declare function preflightChangeset(mode: ReviewChangesetMode, probe: {
     refsResolve: boolean;
@@ -277,12 +276,12 @@ export type PrReviewSizing = {
     /** True for too-large (>~1000) — advise a split, never auto-blocked. */
     adviseSplit: boolean;
     /** Stage 1 collect seats (§ Scale-driven fan-out table). Kept-wave
-     * qualifier: these seats apply only when the deep collect wave is KEPT —
-     * by default (pinned diff pack present) the fold dispatches none
-     * (pr-review.md § Review pipeline fold default). */
+   * qualifier: these seats apply only when the deep collect wave is KEPT —
+   * by default (pinned diff pack present) the fold dispatches none
+   * (pr-review.md § Review pipeline fold default). */
     collectSeats: 2 | 3;
     /** File-size watch fired → advise extract/decompose ("decompose, then
-     * add"). Independent of the diff size. */
+   * add"). Independent of the diff size. */
     fileDecomposeAdvice: boolean;
 };
 /**
@@ -290,13 +289,13 @@ export type PrReviewSizing = {
  * (pr-review.md § Sizing & change shape + § Scale-driven fan-out):
  *
  * - ≤~300 reviewable/acceptable → band `small`; >~300 → `large`;
- *   >~1000 → `too-large` + split advice (a should-fix finding with split
- *   advice or a verdict note — never auto-`blocked`).
+ * >~1000 → `too-large` + split advice (a should-fix finding with split
+ * advice or a verdict note — never auto-`blocked`).
  * - Stage 1 collect seats: small → 2 (code + security); large/too-large →
- *   3 by domain.
+ * 3 by domain.
  * - `largestTouchedFileTotal` drives `fileDecomposeAdvice` INDEPENDENTLY
- *   of the diff size — a small diff materially growing a file past ~1000
- *   total lines gets "decompose, then add".
+ * of the diff size — a small diff materially growing a file past ~1000
+ * total lines gets "decompose, then add".
  */
 export declare function prReviewSizing(input: {
     changedLines: number;
@@ -310,23 +309,23 @@ export declare function prReviewSizing(input: {
  * includes everything. */
 export type PrReviewTier = "quick" | "default" | "deep";
 /**
- * Per-tier time budget for the `amazing-pr-review` pipeline (SP1 tier
+ * Per-tier time budget for the `amazing-pr-review` pipeline (tier
  * time-budget). Prose SSOT: pr-review.md § Review depth — its Budget column
  * carries the wall-clock minutes; the per-seat caps below are the engine
  * contract, rendered into seat prompts, never duplicated as numbers in prose.
  *
  * - `wallClockMinutes`: prompt-discipline target for the whole review,
- *   measured worktree-setup → local report saved by the main agent.
- *   Overruns are declared in the report `- notes:` — budgets are never a
- *   host-level hard kill.
+ * measured worktree-setup → local report saved by the main agent.
+ * Overruns are declared in the report `- notes:` — budgets are never a
+ * host-level hard kill.
  * - `maxSeats`: review seats only — Stage 2 domain seats + the independent
- *   cross-domain security seat; NOT Stage 1 collect seats (collect fan-out
- *   stays governed by pr-review.md § Scale-driven fan-out).
+ * cross-domain security seat; NOT Stage 1 collect seats (collect fan-out
+ * stays governed by pr-review.md § Scale-driven fan-out).
  * - `perSeatFindingsCap` / `evidenceTokensCap` / `fileOpenCap`: per-seat
- *   expansion stops (findings / evidence payload tokens / file opens; the
- *   pinned diff snapshot read does not count). Baseline assumption: 100
- *   tok/s output — wall-clock is dominated by reads/tool latency, which
- *   `fileOpenCap` bounds.
+ * expansion stops (findings / evidence payload tokens / file opens; the
+ * pinned diff snapshot read does not count). Baseline assumption: 100
+ * tok/s output — wall-clock is dominated by reads/tool latency, which
+ * `fileOpenCap` bounds.
  *
  * No new sizing bands: the table references tiers only (pr-review.md
  * § Sizing & change shape stays the only sizing SSOT). */
@@ -349,18 +348,18 @@ export type PrReviewSeatPromptOptions = {
     securitySeat?: boolean;
     tier?: PrReviewTier;
     /** Absolute path to the pinned diff snapshot written by `worktree-setup`
-     * (review artifact beside the sidecar). Non-empty → the prompt gains a
-     * read-first ingredient line pointing at it. */
+   * (review artifact beside the sidecar). Non-empty → the prompt gains a
+   * read-first ingredient line pointing at it. */
     diffFile?: string;
     /** Stage-2 only (`true` + `stage: 1` throws): the collect wave was folded
-     * onto this domain seat — the deep-tier fold default (pinned diff pack
-     * present; SSOT pr-review.md § Review pipeline; prose "collection folded
-     * in = seat reuse" = § Review depth default-tier row). Kept-wave
-     * exceptions dispatch collect seats instead. Requires a non-empty
-     * `diffFile`, and the independent cross-domain security seat is never
-     * folded — either contradiction throws. The prompt gains one bullet after
-     * the `## Budget` block telling the seat to do its own collection, staying
-     * within the budget block. Omitted/`false` → no line. */
+   * onto this domain seat — the deep-tier fold default (pinned diff pack
+   * present; SSOT pr-review.md § Review pipeline; prose "collection folded
+   * in = seat reuse" = § Review depth default-tier row). Kept-wave
+   * exceptions dispatch collect seats instead. Requires a non-empty
+   * `diffFile`, and the independent cross-domain security seat is never
+   * folded — either contradiction throws. The prompt gains one bullet after
+   * the `## Budget` block telling the seat to do its own collection, staying
+   * within the budget block. Omitted/`false` → no line. */
     collectFolded?: boolean;
 };
 /**
@@ -370,30 +369,30 @@ export type PrReviewSeatPromptOptions = {
  * Ingredients:
  *
  * - Absolute path to `references/pr-review.md` under `skillRoot` + the
- *   sections to read; absolute review `worktreePath`.
- * - Per-seat budget block (`## Budget`, SP1 tier time-budget): findings /
- *   evidence-token / file-open caps interpolated from `PR_REVIEW_TIER_BUDGETS`
- *   — expansion stops for the seat, never a host-level hard stop.
+ * sections to read; absolute review `worktreePath`.
+ * - Per-seat budget block (`## Budget`, tier time budget): findings /
+ * evidence-token / file-open caps interpolated from `PR_REVIEW_TIER_BUDGETS`
+ * — expansion stops for the seat, never a host-level hard stop.
  * - `collectFolded: true` (stage 2 only; stage 1, a missing `diffFile`, or
- *   the security seat throws): one bullet after the `## Budget` block — the
- *   collect wave folded onto this seat, so it collects itself (pinned diff
- *   snapshot/pack first, then in-domain changed files) within the budget
- *   block.
+ * the security seat throws): one bullet after the `## Budget` block — the
+ * collect wave folded onto this seat, so it collects itself (pinned diff
+ * snapshot/pack first, then in-domain changed files) within the budget
+ * block.
  * - Recon facts + decided tradeoffs.
  * - Hard Rules 4/5 VERBATIM.
  * - Payload-return contract (write-blocked-safe; main agent writes files).
  * - No-verdict / never-post clauses.
  * - Slug mandate `<domain>-<seat>`.
  * - Stage 2 adds finding-format.md (+ security-review.md for security
- *   seats) and the Merge-class instruction.
+ * seats) and the Merge-class instruction.
  * - Tier cuts (SP-A amendment): quick drops the cross-domain /
- *   independent-security block, the collect-wave wording AND shrinks the
- *   lens/prompt-ingredient set; default drops the same blocks (SSOT
- *   pr-review.md § Review depth, default-tier row: "collection folded in =
- *   seat reuse" — no separate Stage-1 wave, so collect-wave wording is
- *   deep-only); deep keeps everything.
- *   Tier omitted → `default` (pr-review.md § Review depth: the no-flag
- *   landing tier).
+ * independent-security block, the collect-wave wording AND shrinks the
+ * lens/prompt-ingredient set; default drops the same blocks (SSOT
+ * pr-review.md § Review depth, default-tier row: "collection folded in =
+ * seat reuse" — no separate Stage-1 wave, so collect-wave wording is
+ * deep-only); deep keeps everything.
+ * Tier omitted → `default` (pr-review.md § Review depth: the no-flag
+ * landing tier).
  */
 export declare function prReviewSeatPrompt(opts: PrReviewSeatPromptOptions): string;
 /** Options for {@link validateFindingDoc}: `prVariant` gates the Merge
@@ -407,18 +406,18 @@ export type ValidateFindingDocOptions = {
  * PR-only Merge class contract (pr-review.md § Merge class):
  *
  * - Every finding opens with `### [CATEGORY-NN] Title`; CATEGORY ∈
- *   `AUDIT_CATEGORIES` (case-insensitive read, canonical uppercase forms
- *   per category codes), NN numeric.
+ * `AUDIT_CATEGORIES` (case-insensitive read, canonical uppercase forms
+ * per category codes), NN numeric.
  * - Required fields: Evidence / Impact / Effort / Risk / Confidence —
- *   Effort / Risk / Confidence each validated as their LEADING token
- *   (Effort via `AUDIT_EFFORTS`, Risk via `AUDIT_RISKS`, Confidence via
- *   HIGH | MED | LOW with `MEDIUM` tolerated as the MED alias); free-text
- *   gloss after a separator is allowed and ignored.
+ * Effort / Risk / Confidence each validated as their LEADING token
+ * (Effort via `AUDIT_EFFORTS`, Risk via `AUDIT_RISKS`, Confidence via
+ * HIGH | MED | LOW with `MEDIUM` tolerated as the MED alias); free-text
+ * gloss after a separator is allowed and ignored.
  * - Each Evidence citation matches `path:line` (`\S+:\d+` — the path may
- *   but need not carry an extension).
+ * but need not carry an extension).
  * - `prVariant` (default false): every finding additionally carries
- *   **Merge class** ∈ {must-fix, should-fix, nit} placed IMMEDIATELY after
- *   Confidence.
+ * **Merge class** ∈ {must-fix, should-fix, nit} placed IMMEDIATELY after
+ * Confidence.
  */
 export declare function validateFindingDoc(text: string, opts?: ValidateFindingDocOptions): GateResult;
 /** Tier keywords the CLI may have matched from argv — the three explicit
@@ -441,16 +440,16 @@ export type ResolvePrReviewTierInput = {
  * (SP-A amendment; first hit wins):
  *
  * 1. Explicit keyword → that tier (user intent beats heuristics; a lone
- *    `default` returns `default` BEFORE the band/sensitive heuristics).
- *    Any two DISTINCT keywords (quick / default / deep) → hard-stop
- *    conflict error — never silently take a priority. (Empty/omitted =
- *    no flag.)
+ * `default` returns `default` BEFORE the band/sensitive heuristics).
+ * Any two DISTINCT keywords (quick / default / deep) → hard-stop
+ * conflict error — never silently take a priority. (Empty/omitted =
+ * no flag.)
  * 2. Too large (>~1000 / band too-large) → advise split; review anyway →
- *    deep.
+ * deep.
  * 3. Sensitive surface (auth / LLM / supply chain / data) → deep at any
- *    size.
+ * size.
  * 4. Large (>~300 / band large) → deep.
  * 5. Small: tiny-mechanical shape (docs-only / rename / formatting / pure
- *    deletion) → quick; anything else (real code change) → default.
+ * deletion) → quick; anything else (real code change) → default.
  */
 export declare function resolvePrReviewTier(input: ResolvePrReviewTierInput): PrReviewTier;

package/dist/roles.d.ts

@@ -47,14 +47,14 @@ export type RoleMappingOptions = {
  * layout (mstar-roles § Role Reference Mapping / § Parameter Table (SSOT)
  * / § Maintenance Rules):
  * - every mapped agent id resolves to `references/<role>.md` under
- *   `rolesDir`;
+ * `rolesDir`;
  * - shared families (`fullstack-dev*`, `qc-specialist*`) resolve to ONE
- *   shared reference file each;
+ * shared reference file each;
  * - every parameter row references a mapped role, exactly once;
  * - dev track values are `primary` / `parallel_secondary`;
  * - the QC parameter table contract holds: reviewer_index is exactly
- *   {1, 2, 3} across the three seats, each seat has a focus, and
- *   `report_suffix === qc<reviewer_index>`.
+ * {1, 2, 3} across the three seats, each seat has a focus, and
+ * `report_suffix === qc<reviewer_index>`.
  *
  * Violations:
  * - `roles.mapping.reference.missing` — mapped reference file not on disk
@@ -70,18 +70,28 @@ export type RoleMappingOptions = {
 export declare function validateRoleMapping(rolesDir: string, options?: RoleMappingOptions): GateResult;
 /**
  * Lint load-order declarations across skill texts (mstar-harness-core
- * § 加载约定: every `mstar-*` topic skill presumes the reader has Read core
- * first, so each must declare `mstar-harness-core` in its Load Order /
- * First action section).
+ * § 与其它 `mstar-*` skill 的加载契约 + mstar-roles § Load Order; Spec A2 —
+ * single load-selection authority).
  *
  * Input: `skillTexts` maps skill name → full SKILL.md text. `mstar-harness-
- * core` itself and non-`mstar-*` skills are exempt. Heuristic: a section
- * headed Load Order / Load order / First action must exist and mention
- * `mstar-harness-core` inside that section (mentions in later sections do
- * not count).
+ * core` itself and non-`mstar-*` skills are exempt.
+ *
+ * - Every `mstar-*` topic skill (reached by direct invocation) must have a
+ * Load Order / First action section (heading Load Order / Load order /
+ * First action) that names `mstar-harness-core` as its first dependency
+ * (mentions in later sections do not count).
+ * - The `mstar-roles` hub bootstrap is the ONE exception (narrow, keyed on
+ * the skill name — broad exemptions are rejected): it does not declare
+ * core-first; instead its Load Order section must declare the preset
+ * decision matrix (`roles.loadorder.hub.bootstrap.missing` when tokens
+ * are missing) and keep the conditional `mstar-harness-core`
+ * conflict-authority pointer (`roles.loadorder.core.missing`).
  *
  * Violations:
  * - `roles.loadorder.section.missing` — no Load Order / First action section
- * - `roles.loadorder.core.missing` — section exists without the core mention
+ * - `roles.loadorder.core.missing` — topic section without the core-first
+ * declaration, or hub section without the core conflict-authority pointer
+ * - `roles.loadorder.hub.bootstrap.missing` — hub section missing the
+ * identity→none/standard/methods/unknown-preset decision matrix
  */
 export declare function lintLoadOrder(skillTexts: Record<string, string>): GateResult;