@mstar-harness/engine 0.0.0

package/dist/path.d.ts

@@ -0,0 +1,117 @@
+import { type ValidationResult } from "./core.js";
+/**
+ * Options for `resolveHarnessDir`.
+ */
+export type ResolveHarnessDirOptions = {
+    /**
+     * Explicit harness root. Resolved against `startDir` when relative.
+     * Takes precedence over `MSTAR_HARNESS_DIR` and over default probing.
+     * Authoritative: the path is returned even when it does not exist yet
+     * (the caller may scaffold it).
+     */
+    harnessDir?: string;
+};
+/**
+ * Resolve `{HARNESS_DIR}` per plan-conventions § {HARNESS_DIR} 解析顺序
+ * (find-first-stop): `.mstar/` → `.agents/` → `.plans/`/`plans/`, walking up
+ * from `startDir`. Harness candidates are dir-existence (the empty-dir rule
+ * applies to `{SPECS_DIR}` only). An explicit override via `opts.harnessDir`
+ * or `MSTAR_HARNESS_DIR` wins over probing.
+ *
+ * Returns the absolute harness dir, or `null` when no candidate exists.
+ */
+export declare function resolveHarnessDir(startDir?: string, opts?: ResolveHarnessDirOptions): string | null;
+/**
+ * Options for `resolveSpecsDir`.
+ */
+export type ResolveSpecsDirOptions = {
+    /**
+     * Default true: when every candidate is absent or empty, create
+     * `{HARNESS_DIR}/specs/` (plan-conventions § 创建默认). Read-only callers
+     * (e.g. `mstar path resolve`) pass `false` to skip the side effect.
+     */
+    create?: boolean;
+};
+/**
+ * Resolve `{SPECS_DIR}` per plan-conventions § {SPECS_DIR} 解析: first
+ * non-empty candidate wins — `{HARNESS_DIR}/specs/` → `docs/specs/` →
+ * repo-root `specs/` (repo root = parent of the harness dir), then the
+ * legacy read-only `designs/` candidates (`{HARNESS_DIR}/designs/` →
+ * repo-root `designs/`, § {SPECS_DIR} 解析 Legacy — 兼容读 only, never
+ * created by init). A candidate that exists but holds no files is treated
+ * as absent (empty-dir rule, recursive). When all candidates are absent,
+ * `{HARNESS_DIR}/specs/` is created and returned (unless `create: false`).
+ */
+export declare function resolveSpecsDir(harnessDir: string, opts?: ResolveSpecsDirOptions): string;
+/**
+ * Compose `{PLAN_DIR}` from the harness dir (plan-conventions § 路径符号).
+ * Legacy layout: when the harness root is a plans dir itself (`.plans/` or
+ * `plans/`, resolution rung 3), `{HARNESS_DIR}={PLAN_DIR}` — the same
+ * directory is returned.
+ */
+export declare function resolvePlanDir(harnessDir: string): string;
+/**
+ * Single safe path component for per-plan path composition
+ * (qc2 F-001 — path traversal guard): rejects `""`, `.`, `..`, and any
+ * `/` or `\`; allows `[A-Za-z0-9._-]+` only. Throws with a clear message so
+ * callers interpolating a plan id into a path (archive files, SDD dirs)
+ * can never escape the intended parent directory.
+ */
+export declare function assertSafePathComponent(value: string, what: string): void;
+/**
+ * Compose `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/` (plan-conventions
+ * § 路径符号). The per-plan directory is created by the sdd workspace flow,
+ * not here. `planId` must be a single safe path component (traversal
+ * guard) — see `assertSafePathComponent`.
+ */
+export declare function resolveSddDir(harnessDir: string, planId: string): string;
+/**
+ * Compose `{ITERATION_DIR}` = `{HARNESS_DIR}/iterations/` (plan-conventions
+ * § 路径符号).
+ */
+export declare function resolveIterationDir(harnessDir: string): string;
+/**
+ * Initialize the harness directory under `root`: create `.mstar/` with
+ * `plans/`, `iterations/`, `knowledge/`, `specs/`, `sdd/` and write
+ * `status.json` from the empty template (plan-conventions § 初始化 Plan 目录).
+ * Idempotent: an existing non-empty `status.json` is never clobbered.
+ * Returns the absolute harness dir.
+ */
+export declare function scaffoldHarness(root: string): string;
+/**
+ * Harness kind for the gitignore fence — the canonical snippet is per
+ * harness layout (plan-conventions § Git 跟踪策略): `.mstar/` (default) and
+ * legacy `.agents/`.
+ */
+export type HarnessKind = "mstar" | "agents";
+/**
+ * Emit the canonical `.gitignore` snippet for `kind` (plan-conventions
+ * § Git 跟踪策略): the process-artifact ignore set (`archived/`,
+ * `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json` under the
+ * harness dir) with the tracked/results note. When the kind is unknown
+ * (omitted), both snippets are emitted so either fence can be applied.
+ */
+export declare function emitGitignoreSnippet(kind?: HarnessKind): string;
+/**
+ * Validate that `<root>/.gitignore` contains a complete canonical
+ * process-artifact ignore set (plan-conventions § Git 跟踪策略). Rule
+ * (chosen alignment): the gate passes when the repo's .gitignore holds ONE
+ * complete set for the DETECTED harness kind — `.mstar/` for a `.mstar`
+ * harness, `.agents/` for a legacy `.agents` harness; layouts without a
+ * canonical snippet (rung-3 `.plans`/`plans`, or no harness yet) accept
+ * either complete set. This is deliberately per-kind, unlike the CLI `init`
+ * fence which requires BOTH prefixes (flat dual-entry list — packages/cli
+ * src/adapters/shared-install.ts HARNESS_PROCESS_GITIGNORE); a repo fenced
+ * for one layout still passes here. Extra entries are fine; any missing
+ * entry of the required set is a violation. Non-blocking: returns a
+ * `ValidationResult` (v1 enforcement depth, roadmap §8.5).
+ */
+export declare function validateGitignore(root: string): ValidationResult;
+/**
+ * Plan-writing path gate (plan-conventions § Plan-Writing Path Gate +
+ * harness-core 护栏): plans must live under `{PLAN_DIR}`; external default
+ * plan directories are rejected. When `harnessDir` is `null` (persistent
+ * plan tracking not enabled) any plan path is rejected with a fix pointing
+ * at `scaffoldHarness`. Non-blocking: returns a `ValidationResult`.
+ */
+export declare function assertPlanWritingPath(planPath: string, harnessDir: string | null): ValidationResult;

package/dist/roles.d.ts

@@ -0,0 +1,87 @@
+import type { GateResult } from "./core.js";
+/** One row of the role reference mapping (mstar-roles § Role Reference
+ * Mapping): `agentId` → skill-relative reference file. */
+export type RoleMappingEntry = {
+    agentId: string;
+    reference: string;
+};
+/** The 13 role ids → `references/<role>.md` mapping, embedded as data
+ * (mstar-roles § Role Reference Mapping; shared families point at the
+ * shared reference files). */
+export declare const ROLE_MAPPING: readonly RoleMappingEntry[];
+/** A role family that MUST resolve to one shared reference file
+ * (mstar-roles § Maintenance Rules: "Keep shared-family roles
+ * (`fullstack-dev*`, `qc-specialist*`) on one shared reference file"). */
+export type RoleFamily = {
+    family: string;
+    memberIds: readonly string[];
+};
+export declare const SHARED_FAMILIES: readonly RoleFamily[];
+/** Dev-track parameter row (mstar-roles § Parameter Table (SSOT) — dev
+ * track): `primary` (backend-led) or `parallel_secondary` (second track). */
+export type DevTrackParam = {
+    roleId: string;
+    track: "primary" | "parallel_secondary";
+};
+export declare const DEV_TRACK_PARAMS: readonly DevTrackParam[];
+/** QC reviewer parameter row (mstar-roles § Parameter Table (SSOT) — QC
+ * reviewer): seat index, review focus, and the `qc<index>` report suffix
+ * that lands at `{SDD_DIR}/review/qc<index>.md`. */
+export type QcReviewerParam = {
+    roleId: string;
+    reviewerIndex: number;
+    focus: string;
+    reportSuffix: string;
+};
+export declare const QC_REVIEWER_PARAMS: readonly QcReviewerParam[];
+/** Override point for tests / future role-table extensions; every slot
+ * defaults to the embedded SSOT tables above. */
+export type RoleMappingOptions = {
+    mapping?: readonly RoleMappingEntry[];
+    families?: readonly RoleFamily[];
+    devTrack?: readonly DevTrackParam[];
+    qcReviewers?: readonly QcReviewerParam[];
+};
+/**
+ * Validate the role mapping + parameter tables against the on-disk skill
+ * layout (mstar-roles § Role Reference Mapping / § Parameter Table (SSOT)
+ * / § Maintenance Rules):
+ * - every mapped agent id resolves to `references/<role>.md` under
+ *   `rolesDir`;
+ * - shared families (`fullstack-dev*`, `qc-specialist*`) resolve to ONE
+ *   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>`.
+ *
+ * Violations:
+ * - `roles.mapping.reference.missing` — mapped reference file not on disk
+ * - `roles.mapping.family.member.missing` — family member absent from mapping
+ * - `roles.mapping.family.shared` — family members resolve to different files
+ * - `roles.param.role.missing` — parameter row names an unmapped role
+ * - `roles.param.role.duplicate` — role appears in two parameter rows
+ * - `roles.param.track` — dev track value not primary/parallel_secondary
+ * - `roles.param.qc.index.set` — reviewer_index set ≠ {1, 2, 3} (high)
+ * - `roles.param.qc.focus.missing` — QC seat without a focus
+ * - `roles.param.qc.suffix` — report_suffix ≠ qc<reviewer_index>
+ */
+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).
+ *
+ * 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).
+ *
+ * Violations:
+ * - `roles.loadorder.section.missing` — no Load Order / First action section
+ * - `roles.loadorder.core.missing` — section exists without the core mention
+ */
+export declare function lintLoadOrder(skillTexts: Record<string, string>): GateResult;

package/dist/sdd.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Error carrying the ported script exit code so the CLI can map validation
+ * failures to identical non-zero exits.
+ */
+export declare class SddScriptError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}
+/**
+ * Options for `sddWorkspace` — `mstar sdd workspace PLAN_ID [CONTROL_ROOT]`
+ * usage plus the harness-root override (plan finding 2026-08-08).
+ */
+export type SddWorkspaceOptions = {
+    /** Control worktree repo root — CLI 2nd arg / `MSTAR_CONTROL_ROOT`. */
+    controlRoot?: string;
+    /** Explicit harness root — `MSTAR_HARNESS_DIR` / `--harness-dir`. */
+    harnessDir?: string;
+    /** Working directory for git probes; default `process.cwd()`. */
+    cwd?: string;
+};
+/** Options for `taskBrief` (mirrors `$SDD_DIR` for the default out path). */
+export type TaskBriefOptions = {
+    sddDir?: string;
+};
+/** Options for `reviewPackage` (mirrors `$SDD_DIR` + git probe cwd). */
+export type ReviewPackageOptions = {
+    sddDir?: string;
+    cwd?: string;
+};
+/**
+ * Resolve and ensure `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/` (prints
+ * the absolute path). Resolution order:
+ *
+ * 1. fail-closed FIRST: a linked worktree without a control root never
+ *    resolves or creates any SDD tree under the feature checkout (refuses a
+ *    second SDD tree; no override or probe may bypass this guard);
+ * 2. explicit harness-root override (`opts.harnessDir` / `MSTAR_HARNESS_DIR`)
+ *    — plan finding 2026-08-08: covers `.harness`-rooted repos the
+ *    status.json probe misses; resolved relative to the established root;
+ * 3. `status.json` probe at root (`.mstar` → `.agents`);
+ * 4. fallback: existing `.mstar`/`.agents` dir, else `.mstar`.
+ *
+ * `controlRoot` (CLI 2nd arg / `MSTAR_CONTROL_ROOT`) pins `root` to the
+ * control worktree instead of the cwd's git top-level.
+ */
+export declare function sddWorkspace(planId: string, opts?: SddWorkspaceOptions): string;
+/**
+ * Extract the `## Task N` section of a plan into a file (default
+ * `{SDD_DIR}/task-N-brief.md`). Line state machine: ``` fences toggle
+ * `infence`; headings inside fences are ignored; printing starts at the
+ * heading for `taskN` and continues until the NEXT `## Task` heading (or
+ * EOF for the last task) — a later Task heading resets the section. A
+ * missing task writes an empty file then fails with exit-3
+ * (`SddScriptError.exitCode === 3`).
+ */
+export declare function taskBrief(planFile: string, taskN: number, outFile?: string, opts?: TaskBriefOptions): string;
+/**
+ * Write commit list, stat summary and `git diff -U10` for `BASE..HEAD`
+ * into a file (default `{SDD_DIR}/review-<short base>..<short head>.diff`).
+ * Both refs are validated with `git rev-parse --verify --quiet` (any ref
+ * the original accepted is accepted here; the SHA-only guard is
+ * `assertBaseSha`).
+ */
+export declare function reviewPackage(base: string, head: string, outFile?: string, opts?: ReviewPackageOptions): string;
+/**
+ * BASE_SHA guard (mstar-sdd SKILL.md red flags: never use `HEAD~1` as the
+ * review BASE — multi-commit tasks truncate). Accepts only a full or prefix
+ * commit SHA that exists in the repo; throws `SddScriptError` (exit 2)
+ * otherwise.
+ */
+export declare function assertBaseSha(ref: string, opts?: {
+    cwd?: string;
+}): void;
+/**
+ * True when `{sddDir}/task-N-report.md` exists and is non-empty
+ * (file-handoffs.md: the implementer writes a full report to
+ * `task-N-report.md`; an empty file carries no evidence).
+ */
+export declare function taskReportExists(sddDir: string, taskN: number): boolean;
+/**
+ * Read the progress ledger (mstar-sdd SKILL.md § Progress ledger) as
+ * non-empty trimmed lines; missing `progress.md` reads as `[]`. Tasks
+ * marked `Task N: complete` are DONE and must not be re-dispatched.
+ */
+export declare function readProgressLedger(sddDir: string): string[];
+/**
+ * Sticky implementer session ledger — `{SDD_DIR}/implementer-session.json`
+ * (sticky-implementer-session.md § Session ledger).
+ */
+export type ImplementerSessionLedger = {
+    plan_id: string;
+    execute_as: string;
+    session_mode: "sticky" | "fresh";
+    host: string;
+    /** Agent id from the first Task return — required for resume. */
+    host_agent_id?: string;
+    working_branch: string;
+    started_task: number;
+    last_task: number;
+    started_at: string;
+};
+/** Input to `implementerSessionStickyRules`. */
+export type StickyRulesInput = {
+    session: ImplementerSessionLedger;
+    /** Task about to be dispatched. */
+    nextTask: number;
+    /** Tasks covered by this dispatch (micro-batch); default 1. */
+    microBatchTasks?: number;
+};
+/** Verdict of the sticky resume rules. */
+export type StickyRulesResult = {
+    resume: boolean;
+    reason: string;
+};
+/**
+ * Sticky resume rules (sticky-implementer-session.md + SKILL.md red flag
+ * "Resume implementer without host_agent_id"): a sticky session may only
+ * resume when `session_mode` is `sticky`, `host_agent_id` is present,
+ * `nextTask` is not already completed through `last_task`, and the
+ * micro-batch size is ≤ 3 (max without user override). Reviewers never
+ * resume — that rule lives in the PM flow, not the session ledger.
+ */
+export declare function implementerSessionStickyRules(input: StickyRulesInput): StickyRulesResult;

package/dist/skill-authoring.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Engine skill-authoring module — frontmatter lint, 5-question body lint,
+ * and skill-relative asset-path resolution (thin; roadmap §8.2
+ * `skill-authoring` row, §4.5).
+ *
+ * Source skills (semantic SSOT — this module implements their deterministic
+ * rules, it never redefines them; roadmap §8.5 C2):
+ * - `mstar-skill-authoring` SKILL.md § Frontmatter Contract — `name` stable
+ *   lowercase-hyphen; `description` is the trigger contract (not a workflow
+ *   summary), third person.
+ * - `mstar-skill-authoring` SKILL.md § Body 必须回答的 5 问 + § 默认 Body
+ *   结构 — a SKILL.md body answers five questions via key sections (Load
+ *   Order, Workflow, Decision Rules, Evidence, References).
+ * - `mstar-skill-authoring` SKILL.md § Skill-relative script and asset
+ *   paths ("skill `my-skill` → scripts/do-thing") + `mstar-host` SKILL.md
+ *   § Resolve loaded skill root (per-host resolution).
+ *
+ * The SkillsBench six principles and trigger-contract reasoning stay prompt.
+ */
+import type { GateResult } from "./core.js";
+import { type HostId } from "./host.js";
+/**
+ * Lint a skill file's frontmatter (mstar-skill-authoring § Frontmatter
+ * Contract): `name` lowercase-hyphen, `description` present / third-person /
+ * not a workflow summary. Re-exports `lint.lintSkillFrontmatter` — the
+ * single parser/heuristics implementation (one source of truth; the CLI
+ * `mstar skill lint` calls this alias). Violations keep the `lint.frontmatter.*`
+ * codes.
+ */
+export { lintSkillFrontmatter as lintFrontmatter } from "./lint.js";
+/** One of the five body questions and the canonical section that answers it
+ * (mstar-skill-authoring § Body 必须回答的 5 问 / § 默认 Body 结构). */
+export type FiveQuestionSection = {
+    key: string;
+    label: string;
+    question: string;
+};
+export declare const FIVE_QUESTION_SECTIONS: readonly FiveQuestionSection[];
+/**
+ * Lint a SKILL.md body for the 5-question contract (mstar-skill-authoring
+ * § Body 必须回答的 5 问). Heuristic: each of the five questions must be
+ * answered by the presence of its canonical section heading (case-
+ * insensitive substring match on heading text, any heading level — so
+ * "## Load Order (Required)" and "### Workflow — main path" both match).
+ * Content judgment (whether the answer is actually narrow / procedural)
+ * stays prompt. Advisory: violations are `low` severity (v1 non-blocking).
+ *
+ * Violations: `skill-authoring.five-question.<key>` for each uncovered
+ * question.
+ */
+export declare function lintFiveQuestion(bodyText: string): GateResult;
+/**
+ * Resolve a skill-relative asset path (mstar-skill-authoring § Skill-
+ * relative script and asset paths: name assets as skill `<name>` →
+ * `scripts/…` / `references/…`; never a literal `skills/<name>/…` path from
+ * a consumer cwd) into the host-specific resolution instruction
+ * (mstar-host § Resolve loaded skill root). No filesystem access — this is
+ * an instruction string an agent reads to find the asset.
+ */
+export declare function resolveAssetPath(skillName: string, relPath: string, host: HostId): string;

package/dist/status.d.ts

@@ -0,0 +1,168 @@
+import { type GateResult } from "./core.js";
+import { type EnforcementFlag } from "./dispatch.js";
+/**
+ * Loose shape of a parsed status.json document. All fields are `unknown`
+ * because documents come from JSON at runtime; validators narrow them.
+ */
+export type StatusDoc = {
+    version?: unknown;
+    updated_at?: unknown;
+    plans?: unknown;
+    residual_findings?: unknown;
+    metadata?: unknown;
+    [key: string]: unknown;
+};
+/** Residual entry as parsed from status.json (loose — validated by `validateResidual`). */
+export type ResidualEntry = {
+    id?: unknown;
+    title?: unknown;
+    severity?: unknown;
+    source?: unknown;
+    scope?: unknown;
+    decision?: unknown;
+    owner?: unknown;
+    target?: unknown;
+    tracking?: unknown;
+    detail_doc?: unknown;
+    lifecycle?: unknown;
+    closed_at?: unknown;
+    closure_note?: unknown;
+    closure_evidence?: unknown;
+    superseded_by?: unknown;
+    [key: string]: unknown;
+};
+/** Plan row as parsed from status.json (loose — validated by `validatePlanRow`). */
+export type PlanRow = {
+    id?: unknown;
+    plan_id?: unknown;
+    title?: unknown;
+    file?: unknown;
+    status?: unknown;
+    metadata?: unknown;
+    execution_lease?: unknown;
+    [key: string]: unknown;
+};
+/** Findings cleanup policy mirror of Assignment `Findings cleanup`. */
+export type FindingsCleanupMode = "zero-residual" | "allow-residual";
+/** Computed rollup aggregates (jq semantics). */
+export type TechDebtSummary = {
+    total_open: number;
+    by_severity: Record<string, number>;
+    by_target: Record<string, number>;
+    by_plan: Record<string, number>;
+};
+export type TechDebtCheck = {
+    field: "total_open" | "by_severity" | "by_target" | "by_plan";
+    status: "PASS" | "DRIFT";
+};
+/** Result of the rollup + drift check vs stored `metadata.tech_debt_summary`. */
+export type TechDebtRollup = {
+    computed: TechDebtSummary;
+    stored: Record<string, unknown> | null;
+    checks: TechDebtCheck[];
+    overall: "PASS" | "DRIFT";
+};
+export type ArchiveResult = {
+    planId: string;
+    archived: number;
+    archivePath: string;
+};
+/**
+ * Normalize a residual `severity` value for reading/rolling up
+ * (status-and-residuals.md § severity 5 + rollup `norm_sev`):
+ * legacy `"warning"` → `"low"`; `null`/`""` → `"medium"`; anything else passes
+ * through unchanged (unknown values match no enum bucket, same as jq).
+ */
+export declare function normalizeSeverity(value: unknown): unknown;
+/**
+ * jq semantics: an entry is open when `.lifecycle // "open"` equals `"open"`
+ * (rollup `is_open`; status-and-residuals.md § lifecycle).
+ * The jq alternative operator `//` yields the default for `false` AND
+ * `null` (not just null) — `lifecycle: false` therefore counts as open.
+ * Exported for consumers that need the shared open semantics (e.g. the
+ * iteration phase-gate entry check) instead of a local re-implementation.
+ */
+export declare function isOpenResidual(entry: Record<string, unknown>): boolean;
+/**
+ * Validate one `plans[]` row (status-and-residuals.md § Basic structure +
+ * § Compatibility: read accepts `id` or `plan_id`; write one canonical key).
+ * Required: `id` (or legacy `plan_id`), `title`, `file`, `status` (one of
+ * Todo|InProgress|InReview|Blocked|Done); `metadata` optional but must be an
+ * object when present. `execution_lease` is type-checked here; the full lease
+ * state machine lives in the lease module (Task 5).
+ */
+export declare function validatePlanRow(row: unknown): GateResult;
+/**
+ * Validate one residual entry (status-and-residuals.md § Basic structure):
+ * required `id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`,
+ * `target`, `tracking`; `severity` from the enum (legacy `"warning"` is read
+ * but forbidden on new entries — flagged with fix); `decision` from
+ * defer|accept|risk-accepted; `lifecycle` optional from the close enum.
+ */
+export declare function validateResidual(entry: unknown): GateResult;
+/**
+ * Validate a status.json document (schema: status-and-residuals.md
+ * § Basic structure + § General constraints). Accepts a parsed document or a
+ * file path (malformed JSON yields a `status.invalid-json` violation, never a
+ * throw). Required top-level fields: `version`, `updated_at`, `plans[]`,
+ * root-only `residual_findings`, `metadata`. Root-only canonical: any
+ * `metadata.residual_findings` key is flagged as dual-write.
+ */
+export declare function validateStatus(docOrPath: StatusDoc | string): GateResult;
+/**
+ * Archive the open residuals of a plan (status-and-residuals.md
+ * § Residual findings lifecycle): append every entry of
+ * `residual_findings[<plan-id>]` to `{HARNESS_DIR}/archived/residuals/
+ * <plan-id>.json` (stamped `archived_at`), delete the key from the open list,
+ * and bump root `updated_at`. No-op (archived 0) when the plan has no open
+ * residuals. `harnessDir` defaults to the resolved `{HARNESS_DIR}` from cwd.
+ *
+ * `planId` is validated as a single safe path component before it is used to
+ * build the archive path (path traversal guard — see
+ * `assertSafePathComponent`). The status.json read-modify-write runs under
+ * `withStatusWriteLock` so concurrent coordination writers serialize.
+ *
+ * simplify: archive append + status.json update are two separate writes —
+ * a crash between them leaves entries both archived and open; re-running is
+ * safe because appends dedup on `entries[].id` (F-10). Not transactional by
+ * design (v1); the write lock from F-004 keeps concurrent writers safe.
+ */
+export declare function archiveResiduals(planId: string, harnessDir?: string): Promise<ArchiveResult>;
+/**
+ * Findings cleanup gate (status-and-residuals.md § Findings cleanup modes).
+ * `zero-residual`: only true blocker-defers (`decision: defer` + non-empty
+ * `target`) may stay open — fixable findings, `nit`s, and waived/
+ * risk-accepted entries are violations. `allow-residual` (default): open
+ * residuals are fine unless an unresolved Critical remains. Mode resolution:
+ * explicit `opts.mode` → `plans[].metadata.findings_cleanup` → `allow-residual`.
+ */
+export declare function findingsCleanupGate(doc: StatusDoc, planId: string, opts?: {
+    mode?: FindingsCleanupMode;
+}): GateResult;
+/**
+ * Resolve the repo-level hard-enforcement flag from the iteration compass
+ * (roadmap §8.5 C4/D2): `{ITERATION_DIR}/<id>/delivery-compass.md` files are
+ * scanned; only compasses still steering the repo count — frontmatter
+ * `status: active` or `status: locked` — and the FIRST such compass whose
+ * frontmatter declares `enforcement: hard` hardens the gate in this repo.
+ * A COMPLETED (or status-less/archived) iteration's compass NEVER hardens:
+ * D2 rollback = unset the flag in the ACTIVE compass, and that must work
+ * while older completed compasses still declare hard (qc1 F-001 / qc2 F-002).
+ * A counting compass declaring a non-hard value, or no compass at all,
+ * leaves the flag unset (`source: none`) — hard gates are never the default
+ * and the flag is inert when the engine is absent. Frontmatter is
+ * `---`-fenced; hard declarations in the compass BODY do not count (the
+ * frontmatter is the schema surface — see iteration.compassSchema).
+ */
+export declare function resolveCompassEnforcement(harnessDir: string): EnforcementFlag;
+/**
+ * Compute the `metadata.tech_debt_summary` rollup (status-and-residuals.md
+ * § `metadata.tech_debt_summary`): `total_open` / `by_severity` /
+ * `by_target` / `by_plan` over open entries of root `residual_findings`
+ * merged with the legacy `metadata.residual_findings` read path (canonical
+ * keys win; legacy `"warning"` → `low`, `null`/`""` → `medium`; closed
+ * entries skipped; missing `target` groups under `"unspecified"`), then
+ * compare field-by-field against stored `metadata.tech_debt_summary`.
+ * Accepts a parsed document or a file path. Does not write status.json.
+ */
+export declare function techDebtRollup(docOrPath: StatusDoc | string): TechDebtRollup;

package/dist/worktree.d.ts

@@ -0,0 +1,104 @@
+import type { GateResult } from "./core.js";
+/** One L2 parallel implement track (mstar-branch-worktree L2 table). */
+export type WorktreeTrack = {
+    /** Absolute worktree checkout path for the track. */
+    worktreePath: string;
+    /** PM-approved Working branch checked out in that worktree. */
+    workingBranch: string;
+};
+/**
+ * L1 pre-dispatch checklist input — mirrors the status.json L1 fields
+ * (`metadata.control_worktree_path` + `plans[].execution_lease`).
+ */
+export type L1PreDispatchInput = {
+    /** `metadata.control_worktree_path` — harness coordination SSOT checkout. */
+    controlWorktreePath: string;
+    /** `execution_lease.worktree_path` — the plan's feature worktree. */
+    leaseWorktreePath: string;
+    /** `execution_lease.working_branch` — the plan's Working branch. */
+    leaseWorkingBranch: string;
+    /** Plan id (`status.json.plans[].id` / `{SDD_DIR}` segment) — message context. */
+    planId: string;
+};
+/** L2 pre-dispatch checklist input — the plan's parallel writable tracks. */
+export type L2PreDispatchInput = {
+    tracks: readonly WorktreeTrack[];
+};
+/** Git branch probe options — keep checks pure by precomputing probe inputs. */
+export type BranchProbeOptions = {
+    /** git executable to invoke (default `git`). */
+    gitPath?: string;
+    /**
+     * Precomputed branch lookup keyed by absolute worktree path; return
+     * `undefined` to fall back to a real `git -C <path> branch --show-current`
+     * probe. Lets callers (tests, host hooks) inject probe inputs without a
+     * subprocess.
+     */
+    branchOf?: (worktreePath: string) => string | undefined;
+    /**
+     * Git probe timeout in ms (default 10s; `MSTAR_GIT_PROBE_TIMEOUT_MS` env
+     * overrides; per-call value wins). On timeout the probe fails closed into
+     * `branch-probe-failed` — never hangs, never guesses a branch (qc3 F-4).
+     */
+    timeoutMs?: number;
+};
+/**
+ * QC/QA alignment fields — `plan_id` + `Review range`/`Diff basis` must be
+ * byte-identical across the QC tri + QA assignments (逐字相同).
+ */
+export type QcAlignmentAssignment = {
+    planId: string;
+    reviewRange: string;
+    diffBasis: string;
+};
+/** `singleReviewSnapshot` input — alignment fields plus a precomputed review HEAD. */
+export type QcSnapshotAssignment = QcAlignmentAssignment & {
+    /** Precomputed review HEAD (full SHA preferred) for that assignment. */
+    head?: string;
+};
+/**
+ * L1 cross-plan pre-dispatch checklist (mstar-branch-worktree L1 table +
+ * Harness path SSOT hard rules): control path recorded, feature worktree
+ * exists, lease worktree ≠ control path, and the branch checked out at the
+ * feature worktree matches `execution_lease.working_branch`.
+ */
+export declare function l1PreDispatchCheck(input: L1PreDispatchInput, opts?: BranchProbeOptions): GateResult;
+/**
+ * L2 within-plan pre-dispatch checklist (parallel-writable-pre-dispatch.md):
+ * every parallel writable track's `worktreePath` must be absolute and
+ * distinct (one Worktree per track — N parallel invokes ≠ isolation), the
+ * worktree dir must exist, and `git -C <path> branch --show-current` must
+ * match its Working branch — before the first concurrent writable dispatch.
+ * Fewer than one track is itself a violation (the checklist needs something
+ * to verify).
+ */
+export declare function l2PreDispatchCheck(input: L2PreDispatchInput, opts?: BranchProbeOptions): GateResult;
+/**
+ * L1 hard rule (Harness path SSOT): `execution_lease.worktree_path` MUST
+ * differ from `metadata.control_worktree_path`. String equality on the two
+ * paths — canonical absolute paths are the caller's contract (the lease
+ * validator already requires `worktree_path` to be absolute).
+ */
+export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string): GateResult;
+/**
+ * Assert the branch checked out at `worktreePath` matches `expectedBranch`
+ * (the Assignment Working branch). Probe = `git -C <path> branch
+ * --show-current`; precompute via `opts.branchOf` for purity. Fail-closed on
+ * probe errors and detached HEAD.
+ */
+export declare function assertBranchAlignment(worktreePath: string, expectedBranch: string, opts?: BranchProbeOptions): GateResult;
+/**
+ * QC/QA 对齐字段契约: `plan_id` + `Review range`/`Diff basis` must be
+ * byte-identical (逐字相同 — no trimming, no normalization) across every
+ * assignment in the set, so the QC tri + QA review the same plan/feature and
+ * the same diff range. One violation per field that differs.
+ */
+export declare function assertQcAlignment(assignments: readonly QcAlignmentAssignment[]): GateResult;
+/**
+ * Single review snapshot precondition (派 QC 前置条件): all reviewable
+ * commits must sit on ONE Working branch HEAD before the QC tri + QA are
+ * dispatched. `head` is precomputed per assignment (full SHA preferred);
+ * different heads → violation; a missing head cannot confirm the snapshot →
+ * violation (fail-closed).
+ */
+export declare function singleReviewSnapshot(assignments: readonly QcSnapshotAssignment[]): GateResult;