@mstar-harness/engine 3.3.0 → 3.4.1

package/dist/index.d.ts

@@ -15,7 +15,10 @@
  * secrets and scaffolds audit-<date>/ plan dirs, and `compound` validates
  * knowledge-doc schema, reference existence, index rows and the
  * compound-refresh scope. `roles` validates the role reference mapping +
- * parameter tables and the load-order contract, `host` detects the active
+ * parameter tables and the load-order contract, `prreview` implements the
+ * PR-review tally/score/verdict arithmetic and the merge-class/verdict
+ * constants (mstar-audit pr-review.md § Tally and derived score), `host`
+ * detects the active
  * host from tool shapes, resolves skill roots and defines the type-only
  * `HostAdapter` contract, and `skill-authoring` lints frontmatter +
  * 5-question bodies and resolves skill-relative asset paths.
@@ -40,16 +43,16 @@ export type { ImplementerSessionLedger, ReviewPackageOptions, SddWorkspaceOption
 export { SddScriptError, assertBaseSha, implementerSessionStickyRules, readProgressLedger, reviewPackage, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
 export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
 export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
-export type { FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
-export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
+export type { AppendProjectRegisterEntriesOpts, CloseProjectRegisterEntryOpts, FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
+export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, appendProjectRegisterEntries, closeProjectRegisterEntry, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
 export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, MigrateResult, MigrateRoadmap, MigrateRootV2, MigrateSnapshot, MigrateStep, } from "./migrate.js";
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.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, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, SecretFinding, } from "./audit.js";
-export { AUDIT_CATEGORIES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, validateAuditStatusBlocks, } from "./audit.js";
-export type { ReferenceCheckResult } from "./compound.js";
+export type { AuditCategory, AuditConfidence, AuditEffort, AuditFinding, AuditPriority, AuditRisk, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, ScannedSecret, SecretFinding, SupplyChainFinding, SupplyChainFindingKind, SupplyChainResult, } from "./audit.js";
+export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditStatusBlocks, } from "./audit.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
+export type { ReferenceCheckResult } from "./compound.js";
 export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
 export { assertSddTddTriple, findEphemeralCitations, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
 export type { DevTrackParam, QcReviewerParam, RoleFamily, RoleMappingEntry, RoleMappingOptions, } from "./roles.js";
@@ -58,3 +61,5 @@ export type { DetectResult, HostAdapter, HostId, SkillRootPaths, ToolSignal } fr
 export { detectHost, resolveSkillRoot } from "./host.js";
 export type { FiveQuestionMode, FiveQuestionSection } from "./skill-authoring.js";
 export { FIVE_QUESTION_SECTIONS, RUNTIME_HEADING_ALIASES, lintFiveQuestion, lintFrontmatter, resolveAssetPath, stripFrontmatter, } from "./skill-authoring.js";
+export type { MergeClass, PrReportTarget, PrReviewSeatPromptOptions, PrReviewSizing, PrReviewTier, PrTierKeyword, PrSizeBand, PrTallyInput, PrTallyResult, PrVerdict, ResolvePrReviewTierInput, ReviewChangesetMode, ReviewInlineComment, ReviewPostPlan, ValidateFindingDocOptions, } from "./prreview.js";
+export { MERGE_CLASSES, PR_VERDICTS, REVIEW_EMOJI, computePrTally, pickReviewBranchName, planReviewPost, preflightChangeset, prReviewReportPath, prReviewSeatPrompt, prReviewSizing, resolvePrReviewTier, validateFindingDoc, validatePrReviewReport, } from "./prreview.js";

package/dist/project.d.ts

@@ -100,6 +100,63 @@ 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). */
+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 ①).
+     */
+    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). */
+export type CloseProjectRegisterEntryOpts = {
+    /** Absolute path to the per-project directory (`<harness>/projects/<id>`; `_default` for project-less flows). */
+    projectDir: string;
+    /** Entries key (`<plan-id>`) holding the entry to close. */
+    planKey: string;
+    /** `id` of the entry to close (absent → throw). */
+    entryId: string;
+    /** Closure note written verbatim; `closed_at` is today's local date. */
+    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
+ * 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
+ * free same-day key (`basePlanKey`, `basePlanKey-2`, `-3`, … — port of the
+ * python next-free-key loop, pr-review.md) INSIDE the lock, validate every
+ * entry with `validateResidual`, enforce entry-id uniqueness within the
+ * selected key (B-9 correction ② — `validateProjectRegister` has no
+ * duplicate-id detection), set each entry's `source_plan` to the used key
+ * (provenance must match the entries key; the caller cannot know the bumped
+ * key beforehand), append preserving every other key, validate the whole
+ * register with `validateProjectRegister`, then `writeJson` (atomic
+ * temp+rename — never `open(w)`). Fail-loud: any validation failure throws
+ * and the register is left untouched. Returns the key actually used.
+ */
+export declare function appendProjectRegisterEntries(opts: AppendProjectRegisterEntriesOpts): Promise<{
+    ok: true;
+    key: string;
+}>;
+/**
+ * Close one project-register entry in place (plan 20260826-backlog-register-cli
+ * Task 1): 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 `writeJson` (atomic
+ * temp+rename). Fail-loud: an invalid register throws and nothing is written.
+ */
+export declare function closeProjectRegisterEntry(opts: CloseProjectRegisterEntryOpts): Promise<{
+    ok: true;
+}>;
 /**
  * Findings cleanup gate (status-and-residuals.md § Findings cleanup modes;
  * QC wave-1 W-D relocation — the input is the project register

package/dist/prreview.d.ts

@@ -0,0 +1,335 @@
+import type { GateResult } from "./core.js";
+/** Merge classes for accepted PR-review findings (pr-review.md § Merge class). */
+export declare const MERGE_CLASSES: readonly ["must-fix", "should-fix", "nit"];
+export type MergeClass = (typeof MERGE_CLASSES)[number];
+/** The three PR-review verdict tokens (pr-review.md § Verdict synthesis). */
+export declare const PR_VERDICTS: readonly ["ship it", "needs fixes", "blocked"];
+export type PrVerdict = (typeof PR_VERDICTS)[number];
+/**
+ * Emoji per merge class (+ the unverified bucket) — pr-review.md § Section
+ * emoji map: 🔴 must-fix · 🟠 should-fix · 🔵 nit · ❓ unverified.
+ */
+export declare const REVIEW_EMOJI: Record<MergeClass | "unverified", string>;
+/**
+ * Input to {@link computePrTally}. `findings` are the post-vet accepted
+ * findings only; `unverifiedCount` is the count of residual items under
+ * `- unverified:` (0 when absent / `none`); `unmetAc` is the leftover
+ * unmet acceptance criteria (not met, not cut) — each increments the tally
+ * (§ Linked-issue hygiene), it is not a fourth class and not a second
+ * finding.
+ */
+export type PrTallyInput = {
+    /** Post-vet accepted findings only. */
+    findings: readonly {
+        mergeClass: MergeClass;
+    }[];
+    /** Count of residual `- unverified:` items; 0 default. */
+    unverifiedCount?: number;
+    /** Leftover unmet ACs (not met, not cut). */
+    unmetAc?: readonly {
+        unsafeToShip: boolean;
+    }[];
+};
+/** Result of {@link computePrTally}. */
+export type PrTallyResult = {
+    verdict: PrVerdict;
+    /** `max(0, 100 - 40*mustFix - 15*shouldFix - 3*nit - 10*unverified)`, integer, floor 0. */
+    scorePct: number;
+    tally: {
+        mustFix: number;
+        shouldFix: number;
+        nit: number;
+        unverified: number;
+    };
+    /** Two-line chat display header, verbatim per pr-review.md § Display contract. */
+    chatHeader: string;
+};
+/**
+ * Compute the PR-review tally, score and verdict from accepted findings,
+ * leftover unmet ACs and unverified residuals (pr-review.md § Tally and
+ * derived score — formula semantics verbatim, SSOT immutable).
+ *
+ * Leftover unmet ACs increment the tally (unsafe-to-ship → must_fix + 1,
+ * else should_fix + 1) BEFORE verdict derivation, so they cannot yield
+ * `ship it`. Verdict precedence: any must_fix ≥ 1 → `blocked`; else any
+ * should_fix ≥ 1 → `needs fixes`; else `ship it`. The score is computed but
+ * never overrides the verdict (override invariant).
+ */
+export declare function computePrTally(input: PrTallyInput): PrTallyResult;
+/**
+ * Which reviewed artifact the report (or evidence file) belongs to.
+ *
+ * - `pr` — reviewed PR number `n`.
+ * - `branch` — bare branch, `slug` is the pre-slugged `<branch-slug>`
+ *   (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).
+ */
+export type PrReportTarget = {
+    kind: "pr";
+    n: number;
+} | {
+    kind: "branch";
+    slug: string;
+} | {
+    kind: "diff";
+    headSha?: string;
+};
+/**
+ * Resolve the local-report (or evidence-file) path for a reviewed target
+ * (pr-review.md § Local report archive — naming rules verbatim, pure read,
+ * 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).
+ * - `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`.
+ * - 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).
+ * - `date` defaults to the local calendar date and must be `YYYY-MM-DD`.
+ */
+export declare function prReviewReportPath(opts: {
+    reportsDir: string;
+    date?: string;
+    target: PrReportTarget;
+    stage?: 1 | 2;
+    slug?: string;
+}): string;
+/**
+ * Validate a saved local PR-review report against the machine-readable
+ * contract (pr-review.md § Local report archive Frontmatter + § Output
+ * shape tri-states, semantics verbatim):
+ *
+ * - `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).
+ * - `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).
+ * - `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).
+ * - `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).
+ */
+export declare function validatePrReviewReport(text: string): GateResult;
+/** One inline review comment: `path` + `line` in the three-dot diff, RIGHT
+ * side only (§ Comment posting step 2 — comments[] entry shape). */
+export type ReviewInlineComment = {
+    path: string;
+    line: number;
+    side: "RIGHT";
+    body: string;
+};
+/**
+ * The POST payload for the Reviews API (step 2 built here, step 3
+ * executed by the CLI). `event` is the literal `"COMMENT"` — APPROVE /
+ * REQUEST_CHANGES are not representable in this type (SSOT:
+ * never approve-as-merge).
+ */
+export type ReviewPostPlan = {
+    ownerRepo: string;
+    pr: number;
+    /** PR head SHA — the Reviews API `commit_id`. */
+    commitId: string;
+    event: "COMMENT";
+    body: string;
+    inlineComments: readonly ReviewInlineComment[];
+};
+/**
+ * Build the deterministic part of the GitHub Review POST (pr-review.md §
+ * Comment posting Procedure steps 1-2; step 3's POST + the at-most-once
+ * 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.
+ * - Missing/invalid `headRefOid` throws — there is no commit_id without
+ *   it.
+ * - `event` is always the literal `"COMMENT"`; no other value exists in
+ *   this contract.
+ * - Inline comments validated per-entry (path / positive line / RIGHT).
+ */
+export declare function planReviewPost(prView: {
+    url?: string;
+    headRepository?: unknown;
+    headRefOid?: string;
+}, payload: {
+    body: string;
+    comments?: readonly ReviewInlineComment[];
+}): ReviewPostPlan;
+/**
+ * Pick a collision-free local review branch name BEFORE any fetch
+ * (pr-review.md § Worktree isolation): `pr-<n>` first; when occupied,
+ * loop `pr-<n>-<date>-<i>` with i = 1, 2, ... until an unoccupied name is
+ * found and return it. `existing` holds already-taken branch names; this
+ * function is pure — it never probes git itself.
+ */
+export declare function pickReviewBranchName(existing: ReadonlySet<string>, pr: number, today: string): string;
+/** Input-mode matrix for the review changeset (pr-review.md § Worktree
+ * isolation input modes). Modes with named refs gate on ref resolution;
+ * working-tree counts untracked-only as a changeset. */
+export type ReviewChangesetMode = "pr" | "branch" | "diff" | "working-tree" | "commit";
+/**
+ * Pre-flight gate over the probe results of a resolved review changeset
+ * (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.
+ * - The changeset must be NON-empty in ALL modes — an empty changeset
+ *   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.
+ */
+export declare function preflightChangeset(mode: ReviewChangesetMode, probe: {
+    refsResolve: boolean;
+    changesetEmpty: boolean;
+}): GateResult;
+/** Sizing bands (~100 / ~300 / ~1000), reused across tiers — no second
+ * set of numbers (pr-review.md § Sizing & change shape; § Review depth). */
+export type PrSizeBand = "small" | "large" | "too-large";
+/** Sizing result: band + derived seat plan and advisories. */
+export type PrReviewSizing = {
+    band: PrSizeBand;
+    /** True for too-large (>~1000) — advise a split, never auto-blocked. */
+    adviseSplit: boolean;
+    /** Stage 1 collect seats (§ Scale-driven fan-out table). */
+    collectSeats: 2 | 3;
+    /** File-size watch fired → advise extract/decompose ("decompose, then
+     * add"). Independent of the diff size. */
+    fileDecomposeAdvice: boolean;
+};
+/**
+ * Classify a changeset into the sizing bands and derive the fan-out plan
+ * (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`).
+ * - Stage 1 collect seats: small → 2 (code + security); large/too-large →
+ *   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".
+ */
+export declare function prReviewSizing(input: {
+    changedLines: number;
+    largestTouchedFileTotal?: number;
+}): PrReviewSizing;
+/** Seat prompt tier (SP-A amendment): quick omits the cross-domain /
+ * independent-security-seat block, the collect-wave wording AND shrinks
+ * the lens/prompt-ingredient set; default also omits both (SSOT pr-review.md
+ * § Review depth: default "folds collection in = seat reuse", no separate
+ * Stage-1 wave — collect-wave wording is deep-only); deep includes everything. */
+export type PrReviewTier = "quick" | "default" | "deep";
+/** Options for {@link prReviewSeatPrompt}. */
+export type PrReviewSeatPromptOptions = {
+    stage: 1 | 2;
+    domain: string;
+    seat: string;
+    skillRoot: string;
+    worktreePath: string;
+    reconFacts: readonly string[];
+    decidedTradeoffs?: readonly string[];
+    securitySeat?: boolean;
+    tier?: PrReviewTier;
+};
+/**
+ * Generate the read-only audit-seat prompt for one Stage 1 collect or
+ * Stage 2 domain/security seat (pr-review.md § Review pipeline Seat
+ * prompts + § Fan-out discipline; full-audit mirror codebase-audit.md).
+ * Ingredients:
+ *
+ * - Absolute path to `references/pr-review.md` under `skillRoot` + the
+ *   sections to read; absolute review `worktreePath`.
+ * - 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.
+ * - 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 "folds collection 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
+ * class requirements (presence + enum + placement after Confidence). */
+export type ValidateFindingDocOptions = {
+    prVariant?: boolean;
+};
+/**
+ * Machine-lint one or more findings in the finding-format template shape
+ * (skills/mstar-audit/references/finding-format.md § Template) plus the
+ * 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.
+ * - 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.
+ * - Each Evidence citation matches `path:line` (`\S+:\d+` — the path may
+ *   but need not carry an extension).
+ * - `prVariant` (default false): every finding additionally carries
+ *   **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
+ * tokens (`--quick` / `--default` / `--deep`) alike. */
+export type PrTierKeyword = "quick" | "default" | "deep";
+/** Inference-ladder input for {@link resolvePrReviewTier}. `keywords`
+ * carries EVERY explicit tier token matched on argv (deduplicated);
+ * ANY TWO distinct keywords → hard-stop conflict error (§ Review depth
+ * Conflict rule: at most ONE tier keyword among quick / default / deep —
+ * never silently take a priority). Empty/omitted = no flag, full ladder
+ * runs. */
+export type ResolvePrReviewTierInput = {
+    keywords?: readonly PrTierKeyword[];
+    band: PrSizeBand;
+    sensitiveSurface?: boolean;
+    tinyMechanical?: boolean;
+};
+/**
+ * The deterministic part of pr-review.md § Review depth Inference ladder
+ * (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.)
+ * 2. Too large (>~1000 / band too-large) → advise split; review anyway →
+ *    deep.
+ * 3. Sensitive surface (auth / LLM / supply chain / data) → deep at any
+ *    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.
+ */
+export declare function resolvePrReviewTier(input: ResolvePrReviewTierInput): PrReviewTier;

package/package.json

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