@mstar-harness/engine 0.0.0

package/dist/host.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Engine host module — host auto-detection from tool shapes, skill-root
+ * resolution, and the type-only HostAdapter contract (thin; roadmap §8.2
+ * `host` row, §4.2/§8.4).
+ *
+ * Source skills (semantic SSOT — this module ports their deterministic
+ * rules verbatim, it never redefines them; roadmap §8.5 C2):
+ * - `mstar-host` SKILL.md § Detect active host — the ordered table
+ *   cursor → opencode → omp → kimi → zcode → codex ("Order matters").
+ * - `mstar-host` SKILL.md § Resolve loaded skill root — per-host skill-root
+ *   resolution.
+ * - `.harness/references/skill-programmatic-roadmap.md` §8.4 — the
+ *   `HostAdapter` shared contract (all hooks optional; no concrete adapters
+ *   in the engine; pi/dsh deferred).
+ *
+ * UX judgment (ambiguous-host fallback reasoning, plan-mode bridges) stays
+ * prompt — this module only turns tool shapes into a host id.
+ */
+import type { GateResult, ValidationResult } from "./core.js";
+import type { AssignmentFields } from "./dispatch.js";
+import type { IntegrationMergeLease } from "./lease.js";
+/** All hosts the engine knows about (roadmap §8.4 host union). `pi` and
+ * `dsh` have no plugin API in v1 — they appear in the union (and in
+ * `HostAdapter.host`) but are never detected and get no adapters. */
+export type HostId = "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";
+/** Result of `detectHost`: one of the six known hosts or `ambiguous`
+ * (prompt judgment then applies per mstar-host). */
+export type DetectResult = "opencode" | "omp" | "cursor" | "codex" | "kimi" | "zcode" | "ambiguous";
+/** Tool-shape signal tokens accepted by `detectHost`, derived from the
+ * mstar-host detection table. Plan-mode extras (CreatePlan/SwitchMode) and
+ * Browser-plugin tools are documented in the table but are not part of the
+ * v1 signal enum. */
+export type ToolSignal = "subagent_type" | "question" | "task_subagent" | "task_agent_batch" | "ask" | "hub" | "Agent" | "AgentSwarm" | "AskUserQuestion" | "EnterPlanMode" | "TodoWrite" | "plan_slash" | "goal" | "functions.*" | "tool_search";
+/**
+ * Detect the active host from session tool shapes, per the ordered
+ * mstar-host table (ported verbatim):
+ *
+ * | Signal | Host |
+ * |--------|------|
+ * | `subagent_type` (Task param; plan mode + CreatePlan/SwitchMode) | cursor |
+ * | `question`, or `task_subagent` (task tool, singular subagent, no batch) | opencode |
+ * | `task_agent_batch` (task tool, agent/tasks[] batch), `ask`, `hub` | omp |
+ * | `Agent`/`AskUserQuestion`/`EnterPlanMode` + `AgentSwarm` (Kimi-only) | kimi |
+ * | `Agent`/`AskUserQuestion`/`EnterPlanMode`/`TodoWrite`, no `AgentSwarm` | zcode |
+ * | `/plan`, `/goal`; Goal tools; `functions.*` namespaces; `tool_search` | codex |
+ *
+ * Order matters: cursor → opencode → omp → kimi → zcode → codex — the
+ * sharpest Task-based split is `subagent_type` (Cursor) vs `subagent`
+ * (OpenCode) vs `agent`/`tasks[]` (omp). Still ambiguous → `"ambiguous"`
+ * (prompt judgment stays in the skill).
+ */
+export declare function detectHost(signals: readonly ToolSignal[]): DetectResult;
+/** Skill name + optional skill-relative path for skill-root resolution. */
+export type SkillRootPaths = {
+    skill: string;
+    rel?: string;
+};
+/**
+ * Resolve the loaded skill root for a host (mstar-host § Resolve loaded
+ * skill root). Returns the canonical resolution string for the host —
+ * resolve the loaded skill directory first, never `skills/<name>/…` from a
+ * consumer app cwd (that layout exists in the harness source / plugin
+ * package only).
+ *
+ * | Host | Resolution |
+ * |------|------------|
+ * | omp | `skill://<name>[/<rel>]` (filesystem fallback: plugin package root `skills/<name>/` after install/link) |
+ * | cursor | `~/.cursor/plugins/local/morning-star-harness/skills/<name>[/<rel>]` (global plugin fallback; prefer skill name via plugin skills) |
+ * | codex | `skills/<name>[/<rel>]` (plugin-mounted; project command skills under `.agents/skills/<name>/`) |
+ * | opencode | `harness-skills/<name>[/<rel>]` (package-internal via `@mstar-harness/opencode` — never `process.cwd()/skills/`) |
+ * | kimi / zcode | `./skills/<name>[/<rel>]` (plugin mount from the installed plugin root) |
+ * | pi / dsh | deferred — no plugin API in v1 (roadmap §8.4) |
+ */
+export declare function resolveSkillRoot(host: HostId, paths: SkillRootPaths): string;
+/**
+ * Shared host-adapter contract (roadmap §8.4) — every host plugin implements
+ * this; the engine never imports host-specific SDKs. All lifecycle hooks are
+ * optional so a host degrades gracefully when a slot is absent (standalone
+ * rule: skill text remains authoritative; the engine only returns results
+ * the caller chooses to honor). `log` is required — adapters must be able to
+ * report. No concrete adapters ship in the engine: opencode binds via its
+ * own plugin code, omp via the command layer; pi/dsh adapters are deferred
+ * until their plugin APIs land.
+ */
+export interface HostAdapter {
+    host: "opencode" | "omp" | "pi" | "dsh" | "cursor" | "codex" | "kimi" | "zcode";
+    /** Called before a status.json write; return a validation result the host
+     * surfaces (non-blocking warn in v1, opt-in block in v2). */
+    beforeStatusWrite?: (path: string, doc: unknown) => Promise<ValidationResult>;
+    /** Called before a subagent dispatch; return the Assignment field gate. */
+    beforeDispatch?: (assignment: AssignmentFields) => Promise<GateResult>;
+    /** Called before an integration-branch merge; return the lease gate. */
+    beforeMerge?: (lease: IntegrationMergeLease) => Promise<GateResult>;
+    log: (level: "info" | "warn" | "error", msg: string) => void;
+}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @mstar-harness/engine — public entry (exports map `.` → `dist/engine.js`).
+ *
+ * Engine = importable library for deterministic harness checks; the CLI and
+ * OpenCode plugin consume it in-process. `core` is the shared type/version
+ * base, `path` implements harness path resolution + scaffold + gitignore
+ * checks, `status` implements the status.json schema, residual lifecycle,
+ * findings-cleanup gate and the tech-debt rollup port, `lease` implements
+ * the execution/merge lease state machines + same-host status write lock,
+ * `dispatch` implements the Assignment field contract, default-branch
+ * gate, QC seat mapping and tri-identity/anti-recursion prechecks, `lint`
+ * implements marker/TDD-triple/plan-quality/frontmatter/STRATEGY checks,
+ * `design-md` validates DESIGN.md token frontmatter + light/dark parity +
+ * completeness levels, `audit` validates audit Status blocks, redacts
+ * 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
+ * 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.
+ */
+export type { GateResult, Severity, ValidationResult } from "./core.js";
+export { SEVERITY_ORDER, applyEnforcement, readHarnessVersion, readJson, resolveProjectRoot, writeJson } from "./core.js";
+export type { HarnessKind, ResolveHarnessDirOptions, ResolveSpecsDirOptions } from "./path.js";
+export { assertPlanWritingPath, emitGitignoreSnippet, resolveHarnessDir, resolveIterationDir, resolvePlanDir, resolveSddDir, resolveSpecsDir, scaffoldHarness, validateGitignore, } from "./path.js";
+export type { ArchiveResult, FindingsCleanupMode, PlanRow, ResidualEntry, StatusDoc, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./status.js";
+export { archiveResiduals, findingsCleanupGate, normalizeSeverity, resolveCompassEnforcement, techDebtRollup, validatePlanRow, validateResidual, validateStatus, } from "./status.js";
+export type { ClaimLeaseFields, ExecutionLease, ExecutionLeaseLocations, IntegrationMergeLease, LeaseTransition, LeaseVerifyResult, } from "./lease.js";
+export { canSteal, claimLease, planExecutionLeaseLocations, releaseLease, sameHolderResume, validateExecutionLease, validateIntegrationMergeLease, verifyPlanExecutionLease, withStatusWriteLock, } from "./lease.js";
+export type { AssignmentBranchForms, AssignmentFields, DefaultBranchOptions, EnforcementFlag, EnforcementSource, ExecutionModeToNOptions, ExecutionModeToNResult, ValidateAssignmentFieldsOptions, } from "./dispatch.js";
+export { antiRecursionPrecheck, assertDefaultBranchProtected, assertTriIdentity, assignmentHeaderRegion, executionModeToN, isReadOnlyAssignmentRole, parseAssignmentBranchForms, parseAssignmentFields, parseBranchPolicyDirectOnBranch, parseEnforcementFlag, validateAssignmentFields, } from "./dispatch.js";
+export type { BranchProbeOptions, L1PreDispatchInput, L2PreDispatchInput, QcAlignmentAssignment, QcSnapshotAssignment, WorktreeTrack, } from "./worktree.js";
+export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, l1PreDispatchCheck, l2PreDispatchCheck, singleReviewSnapshot, } from "./worktree.js";
+export type { ImplementerSessionLedger, ReviewPackageOptions, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
+export { SddScriptError, assertBaseSha, implementerSessionStickyRules, readProgressLedger, reviewPackage, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
+export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
+export { assertIndexRowObligations, evaluatePhaseGate, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.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, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, SecretFinding, } from "./audit.js";
+export { AUDIT_CATEGORIES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, redactSecrets, scaffoldAuditPlan, validateAuditStatusBlocks, } from "./audit.js";
+export type { ReferenceCheckResult } from "./compound.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 { PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";
+export { assertSddTddTriple, findSimplifyMarkers, findTemporaryMarkers, lintSkillFrontmatter, lintStrategySections, planQualityBar, } from "./lint.js";
+export type { DevTrackParam, QcReviewerParam, RoleFamily, RoleMappingEntry, RoleMappingOptions, } from "./roles.js";
+export { DEV_TRACK_PARAMS, QC_REVIEWER_PARAMS, ROLE_MAPPING, SHARED_FAMILIES, lintLoadOrder, validateRoleMapping, } from "./roles.js";
+export type { DetectResult, HostAdapter, HostId, SkillRootPaths, ToolSignal } from "./host.js";
+export { detectHost, resolveSkillRoot } from "./host.js";
+export type { FiveQuestionSection } from "./skill-authoring.js";
+export { FIVE_QUESTION_SECTIONS, lintFiveQuestion, lintFrontmatter, resolveAssetPath, } from "./skill-authoring.js";

package/dist/iteration.d.ts

@@ -0,0 +1,88 @@
+import type { GateResult, ValidationResult } from "./core.js";
+import { type StatusDoc } from "./status.js";
+/**
+ * Loose shape of a parsed delivery-compass.md frontmatter. All fields are
+ * `unknown` because documents come from YAML at runtime; validators narrow
+ * them.
+ */
+export type CompassDoc = {
+    iteration_id?: unknown;
+    start_date?: unknown;
+    end_date?: unknown;
+    status?: unknown;
+    iteration_base_branch?: unknown;
+    target_branch?: unknown;
+    plans?: unknown;
+    [key: string]: unknown;
+};
+/** Where the iteration stands per the Phase transition gates table. */
+export type PhaseTransition = "phase-2-execute" | "phase-3-close" | "phase-4-pr-delivery";
+/**
+ * Git probe inputs for the §3.5 exit checklist. The engine never shells out
+ * to git; callers (CLI / host hooks) probe and pass values in.
+ */
+export type PhaseGateOptions = {
+    /** `git branch --show-current` of the working checkout (Phase 3 runs on the integration branch). */
+    currentBranch?: string;
+    /** Expected `spec_integration_branch` (status.json metadata / compass Delivery Branch Policy). */
+    specIntegrationBranch?: string;
+    /** Resolved PR base branch for Phase 4 (§3.5 exit item 6). */
+    prBaseBranch?: string;
+};
+/**
+ * Result of the phase-transition gate evaluation. `entry`/`exit` are the
+ * checkable subsets of the §3.1 / §3.5 checklists; `ok`/`violations` are the
+ * gate verdict over the triggered transition:
+ * - not all plans Done → `phase-2-execute` (keep executing; gate passes).
+ * - all plans Done with missing checklist items → `phase-3-close` (Phase 3
+ *   required; missing items listed in `violations`).
+ * - all plans Done and both checklists clean → `phase-4-pr-delivery`.
+ *
+ * Note (qc2 F-003): during the Phase-3 window `ok` is false because the
+ * §3.4 close items (`status: completed` + `end_date`) are only written at
+ * the END of close — the exit checklist gates Phase 4, not the Phase-3
+ * entry, so callers (e.g. the CLI, which exits 1) must treat that as "close
+ * work pending", not "don't enter Phase 3".
+ */
+export type PhaseGateResult = {
+    transition: PhaseTransition;
+    allPlansDone: boolean;
+    /** §3.1 close entry checklist — checkable subset (HARD GATE before §3.2). */
+    entry: GateResult;
+    /** §3.5 close exit checklist — checkable subset (gate to Phase 4). */
+    exit: GateResult;
+    ok: boolean;
+    violations: ValidationResult[];
+};
+/**
+ * Validate a parsed delivery-compass.md frontmatter (mstar-iteration §1.3 +
+ * iteration-compass-template.md Fields guide). `end_date` is required only
+ * when `status: completed` (Phase 3 §3.4) and is a violation while the
+ * iteration is still `active`/`locked`.
+ */
+export declare function validateCompassFrontmatter(doc: unknown): GateResult;
+/**
+ * Evaluate the Phase transition gates (mstar-iteration Phase transition
+ * gates table): all compass-registered plans `Done` (per statusDoc plans[]
+ * status) → Phase 3 required, with the checkable subsets of the §3.1 entry
+ * and §3.5 exit checklists as missing-item violations.
+ *
+ * Pure function — git probes (`currentBranch`, `specIntegrationBranch`,
+ * `prBaseBranch`) come from the caller via `opts`.
+ */
+export declare function evaluatePhaseGate(statusDoc: StatusDoc, compassDoc: CompassDoc, opts?: PhaseGateOptions): PhaseGateResult;
+/**
+ * §5.1a push-cadence probe (HARD): never push the PR head while required CI
+ * is still queued/in_progress or an AI/bot review wave is running. Pure
+ * function — no external calls; callers probe CI / review state and pass the
+ * booleans. Fix locally early, push once the wave settles (§5.1a push gate
+ * 1 + 2).
+ */
+export declare function pushCadenceProbe(ciRunning: boolean, reviewWaveActive: boolean): GateResult;
+/**
+ * §1.4 index obligations: one row per iteration in `{ITERATION_DIR}/README.md`
+ * (table header on first creation). Iterations are discovered as subdirectories
+ * of `iterationsDir` containing `delivery-compass.md`. Returns violations for
+ * a missing README, a missing header, and missing per-iteration rows.
+ */
+export declare function assertIndexRowObligations(iterationsDir: string): GateResult;

package/dist/lease.d.ts

@@ -0,0 +1,193 @@
+import type { GateResult, ValidationResult } from "./core.js";
+import type { PlanRow } from "./status.js";
+/**
+ * `plans[].execution_lease` (v1) — see spec header. Extra fields (e.g. the
+ * real control data's `base_sha`) are allowed and preserved.
+ */
+export type ExecutionLease = {
+    holder: string;
+    claimed_at: string;
+    worktree_path: string;
+    working_branch: string;
+    session_label?: string;
+    [key: string]: unknown;
+};
+/**
+ * Root `metadata.integration_merge_lease` (v1) — see spec header. Absent =
+ * unclaimed; writers delete the key on release (never `null`/tombstone).
+ */
+export type IntegrationMergeLease = {
+    holder: string;
+    claimed_at: string;
+    plan_id: string;
+    source_branch: string;
+    target_branch: string;
+    session_label?: string;
+    [key: string]: unknown;
+};
+/** Assignment-side fields written into an `execution_lease` at claim time. */
+export type ClaimLeaseFields = {
+    worktree_path: string;
+    working_branch: string;
+    session_label?: string;
+};
+/**
+ * Result of a pure lease transition on one plan row. `row` is the resulting
+ * row (unchanged when `ok` is false); `outcome` distinguishes a fresh claim
+ * from a same-holder resume / a release.
+ */
+export type LeaseTransition = {
+    ok: boolean;
+    row: PlanRow;
+    outcome?: "claimed" | "resumed" | "released";
+    violations: ValidationResult[];
+};
+/**
+ * Validate one `plans[].execution_lease` object (status-and-residuals.md
+ * § `plans[].execution_lease`): required `holder` / `claimed_at` /
+ * `worktree_path` (absolute) / `working_branch`; optional `session_label`
+ * display-only. `null` and tombstone objects are invalid — writers delete
+ * the key on release, never write `null` (§ Agent prohibitions). Extra
+ * fields are allowed (the real control lease carries `base_sha`).
+ */
+export declare function validateExecutionLease(lease: unknown): GateResult;
+/**
+ * Validate one root `metadata.integration_merge_lease` object
+ * (status-and-residuals.md § Root `metadata.integration_merge_lease` (v1)):
+ * required `holder` / `claimed_at` / `plan_id` / `source_branch` /
+ * `target_branch`; optional `session_label`. Absent = unclaimed; `null` and
+ * tombstone objects are invalid (writers delete the key on release).
+ * Integration merges into `spec_integration_branch` are serial — one holder
+ * at a time (phase-2-worktree-lease.md § Integration merge lease).
+ */
+export declare function validateIntegrationMergeLease(lease: unknown): GateResult;
+/**
+ * Claim-before-`InProgress` transition (status-and-residuals.md
+ * § Claim-before-`InProgress`; phase-2-worktree-lease.md § Execution lease).
+ *
+ * - No lease + status `Todo`/`Blocked` → claim: status becomes `InProgress`
+ *   and the full `execution_lease` is written in one update (`claimed_at`
+ *   = now, RFC 3339 UTC with `Z`).
+ * - Lease with the **same** `holder` → resume: the stored lease is preserved
+ *   verbatim, but `worktree_path`/`working_branch` must match the Assignment
+ *   (`verify-held-lease`) or the resume is refused.
+ * - Lease with a **different** `holder` → refused: no timestamp makes it
+ *   stealable.
+ * - `InProgress` **without** a lease → orphan: refused; never invent a
+ *   lease (§ Orphan recovery — recovery is PM/human-owned).
+ * - `null`/tombstone stored lease → refused, not silently replaced
+ *   (§ Agent prohibitions).
+ * - The fields to be written are validated via `validateExecutionLease`
+ *   **before** the Todo/Blocked → InProgress transition commits: a relative
+ *   `worktree_path` or missing fields are rejected without mutating the row
+ *   (the written lease must itself pass the validator).
+ *
+ * Pure: returns the resulting row; the caller performs the locked
+ * read-check-replace-verify around `status.json` and persists it.
+ */
+export declare function claimLease(row: PlanRow, holder: string, fields: ClaimLeaseFields): LeaseTransition;
+/**
+ * Release transition — deletes `execution_lease` entirely, never writes
+ * `null` (status-and-residuals.md § "Hold, release, and override" + § Agent
+ * prohibitions). Requires the **same-session holder**: when `holder` differs
+ * from the stored lease `holder`, the release is refused and the row is left
+ * unmodified — a different holder must Blocked, never released by another
+ * session (no timestamp makes a lease stealable). Idempotent when no lease
+ * is present. The `Done` authority deletes the lease in the same
+ * complete-file update as `status: "Done"` — **only after** successful
+ * integration merge into `spec_integration_branch` (§ Integration merge
+ * protocol); the caller enforces that ordering around the locked update.
+ */
+export declare function releaseLease(row: PlanRow, holder: string): LeaseTransition;
+/**
+ * Same-holder resume check (status-and-residuals.md § Claim-before-`InProgress`
+ * #2): `true` iff the stored lease `holder` equals the session `holder`.
+ * Verify-held-lease (worktree_path/working_branch vs the Assignment) is the
+ * caller's check via `claimLease`.
+ */
+export declare function sameHolderResume(lease: unknown, holder: string): boolean;
+/**
+ * Steal decision (status-and-residuals.md § Agent prohibitions + § "Hold,
+ * release, and override"): an active lease MUST NOT be stolen — `false`
+ * unless the **current-turn user explicitly authorizes** the override
+ * (`opts.userOverride: true`). The caller MUST still append an audit entry
+ * to `plans[].notes` (timestamp, prior holder, new holder/release, user
+ * authorized). Agents MUST NOT infer override from age, inactivity, `Blocked`
+ * status, or a failed session.
+ */
+export declare function canSteal(lease: unknown, holder: string, opts?: {
+    userOverride?: boolean;
+}): boolean;
+/** Execution lease locations found on one plan row (SSOT + legacy read-compat). */
+export type ExecutionLeaseLocations = {
+    /** SSOT location: `plans[].execution_lease`. */
+    row: unknown;
+    /** Legacy/hand-written read-compat location: `plans[].metadata.execution_lease`. */
+    metadata: unknown;
+};
+export declare function planExecutionLeaseLocations(row: Record<string, unknown>): ExecutionLeaseLocations;
+export type LeaseVerifyResult = {
+    ok: boolean;
+    violations: ValidationResult[];
+    /** The lease chosen for validation (row-level wins) — absent when neither location has one. */
+    lease?: unknown;
+};
+/**
+ * Verify a plan's `execution_lease` across its two possible locations
+ * (status-and-residuals.md § `plans[].execution_lease`; ADR
+ * 2026-07-22-iteration-worktree-plan-lease.md A3 — the plan row is the
+ * claim/hold/release SSOT):
+ * - Row-level `plans[].execution_lease` only, valid → OK.
+ * - Metadata-only (`plans[].metadata.execution_lease`) → high-severity
+ *   `lease.verify.non-ssot-location`: the metadata location is a
+ *   legacy/hand-written read-compat fallback, NOT equivalent to SSOT
+ *   success. Always a FAIL (non-zero exit) with the lease shape still
+ *   validated and reported.
+ * - Both locations present → `lease.verify.dual-write`: the row-level lease
+ *   wins and is validated; the metadata copy must be deleted.
+ * - Neither present → `lease.verify.missing` (non-InProgress) /
+ *   `lease.verify.orphan` (InProgress).
+ *
+ * Kept in the engine so every host hook / CLI entry / Slice-2+ consumer
+ * imports ONE gate (CLI `mstar lease verify` is a thin wrapper).
+ */
+export declare function verifyPlanExecutionLease(row: Record<string, unknown>, planId: string): LeaseVerifyResult;
+/**
+ * Same-host exclusive write lock around `status.json` coordination writes
+ * (status-and-residuals.md § "Same-host exclusive write lock (control
+ * status.json)"; phase-2-worktree-lease.md § "Same-host exclusive write
+ * lock"). Lease mutations and plan-status transitions that touch leases MUST
+ * run inside this lock for the full read-check-replace-verify sequence.
+ *
+ * Acquires by atomic `mkdir` on `<status dir>/.status-write.lockdir/`
+ * (success acquires; existing dir → another writer holds the lock). While
+ * another writer holds it, wait up to `timeoutMs` (default 30s) and then
+ * throw (Blocked) — the lockdir is never removed for another holder.
+ *
+ * Ownership guard (double-unlock safety): the lockdir's `(dev, ino)` is
+ * captured at acquisition; `finally` re-stats the path and removes the
+ * directory ONLY when the identity is unchanged. When `fn` itself removed
+ * the lockdir (e.g. explicit rollback), or another writer replaced it with
+ * a fresh lockdir before this writer's `finally` ran, the removal is
+ * skipped — a second writer's lock is never destroyed.
+ *
+ * Reentrancy: a nested acquisition on the same lockdir within the same
+ * async context (i.e. `fn` calling `withStatusWriteLock` on the same
+ * status.json) throws immediately instead of waiting out the timeout.
+ *
+ * Crash diagnosis: a `holder.pid` file (acquiring process id) is written
+ * inside the lockdir on acquisition and removed on release. A hard crash
+ * between `mkdirSync` and release leaks the lockdir; the timeout error
+ * message names the recovery step (remove the lockdir when no writer is
+ * alive).
+ *
+ * simplify: mkdir lockdir is the SSOT-documented alternative to `flock`
+ * (`{HARNESS_DIR}/.status-write.lock`) — Bun 1.2 exposes no `node:fs`
+ * flock/flockSync, so the advisory-file variant is unavailable here. Unlike
+ * flock, a hard process crash leaks the lockdir; swap to flock when the
+ * runtime provides it.
+ */
+export declare function withStatusWriteLock<T>(statusPath: string, fn: () => T | Promise<T>, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<T>;

package/dist/lint.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Engine lint module — deterministic lint checks ported from skill prose.
+ *
+ * Roadmap: `.harness/references/skill-programmatic-roadmap.md` §8.2 `lint`
+ * row + §4.5 Lint layer (`simplify:` / `temporary` marker presence; SDD TDD
+ * triple in completion reports; plan-quality-bar checks; skill frontmatter
+ * contract; STRATEGY.md required sections). Skill text stays the semantic
+ * SSOT (roadmap D5) — this module implements the deterministic subset and
+ * never forks semantics.
+ *
+ * Spec sources (each function cites the source section):
+ * - simplify:/temporary markers: `mstar-coding-behavior` SKILL.md § Simplicity
+ *   First → "Simplification markers": a deliberate shortcut with a known
+ *   ceiling is marked with a `simplify:` comment naming the ceiling and the
+ *   upgrade path; a workaround is labeled `simplify:` / `temporary`, explains
+ *   why, and records the removal path in the plan/status artifact before the
+ *   task is claimed complete.
+ * - SDD TDD triple: `mstar-coding-behavior` SKILL.md § Integration Notes —
+ *   completion evidence must include the TDD triple (test file(s), command,
+ *   output) in `task-N-report.md`; `mstar-sdd/references/file-handoffs.md` —
+ *   fix subagents append covering test file(s), command run, output.
+ * - Plan quality bar: `mstar-plan-artifacts/references/plan-quality-bar.md`
+ *   § Quality checklist + `templates/plan.main.md` self-review
+ *   ("Placeholder scan: no TBD").
+ * - Skill frontmatter contract: `mstar-skill-authoring` SKILL.md § Frontmatter
+ *   Contract — `name` stable lowercase-hyphen; `description` is the trigger
+ *   contract (not a workflow summary), third person.
+ * - STRATEGY.md structure: `mstar-strategy` SKILL.md § STRATEGY.md structure —
+ *   six required sections.
+ *
+ * Enforcement depth: roadmap §8.5 C4 — v1 lints are non-blocking
+ * `ValidationResult`s; callers surface them as warnings.
+ *
+ * Severity mapping: structural gaps (missing name/description/sections,
+ * placeholder tokens, TDD-triple gaps, un-tracked temporary markers) are
+ * `medium`; style heuristics (pronouns, workflow-summary shape) are `low`.
+ */
+import type { GateResult } from "./core.js";
+/**
+ * A `simplify:` marker found in a file, with its 1-based line number and the
+ * trimmed comment line (lint reporting).
+ */
+export type SimplifyMarker = {
+    line: number;
+    text: string;
+};
+/**
+ * Find `simplify:` marker comments (mstar-coding-behavior § Simplicity First
+ * → "Simplification markers": a deliberate shortcut with a known ceiling —
+ * global lock, O(n²) scan, naive heuristic — is marked with a `simplify:`
+ * comment naming the ceiling and the upgrade path).
+ *
+ * Heuristic (documented, conservative): a marker is a line where a comment
+ * introducer (`//`, `/*`, `*`, `#`, `;`, `--`) precedes `simplify:` —
+ * case-insensitive, any column (leading or trailing comments). Pure prose
+ * like "we simplify: the interface" carries no comment introducer and is
+ * never reported. No judgment about whether the marker actually names a
+ * ceiling/upgrade path — discovery only; callers may inspect `text`.
+ */
+export declare function findSimplifyMarkers(fileText: string): SimplifyMarker[];
+/**
+ * A `temporary` marker found in a file. `removalPath` is the recorded
+ * plan/status artifact reference (first pattern match, see
+ * `findTemporaryMarkers`), or `null` when the marker names no removal path.
+ */
+export type TemporaryMarker = {
+    line: number;
+    text: string;
+    removalPath: string | null;
+};
+/** Result of `findTemporaryMarkers`: the gate verdict plus the markers found
+ * (so callers can both lint and report). */
+export type TemporaryMarkerResult = GateResult & {
+    markers: TemporaryMarker[];
+};
+/**
+ * Find `temporary` label comments and check each carries a recorded removal
+ * path (plan/status artifact reference). Markers lacking a removal path are
+ * violations: `lint.temporary.no-removal-path` (mstar-coding-behavior §
+ * Simplicity First — "If a workaround is unavoidable, label it `simplify:` /
+ * `temporary`, explain why, and record the removal path in the plan/status
+ * artifact before claiming the task complete").
+ *
+ * Heuristic (documented, conservative): a marker is a comment-context line
+ * containing the word `temporary` (case-insensitive, word-boundary — so
+ * "temporarily" is not a label). Removal-path detection uses the pattern set
+ * above; a version mention alone ("remove in v2.0.0") is NOT a plan/status
+ * artifact reference and is reported, per the strict convention wording.
+ *
+ * Accepted false-positive (documented trade-off): the `;` / `--` comment
+ * introducers (Lisp/SQL comment syntax) can match code lines such as
+ * `foo(); temporary = 1;` — the `;` introducer + `\s*temporary\b` looks
+ * like a marker even though `temporary` is a variable name. Errs toward
+ * flagging (a violation prompts a removal path, which the code line won't
+ * carry); do not special-case it without a real FP report.
+ */
+export declare function findTemporaryMarkers(fileText: string): TemporaryMarkerResult;
+/**
+ * Assert the SDD TDD triple is present in a `task-N-report.md` text
+ * (mstar-coding-behavior § Integration Notes — "completion evidence must
+ * include TDD triple — test file(s), command, output — in task-N-report.md";
+ * mstar-sdd/references/file-handoffs.md — fix subagents append covering test
+ * file(s), command run, output).
+ *
+ * One violation per missing part:
+ * - `lint.sdd-tdd.missing-tests` — no test file reference
+ * - `lint.sdd-tdd.missing-command` — no runnable command
+ * - `lint.sdd-tdd.missing-output` — no output evidence
+ *
+ * Heuristics (documented, conservative — tuned so prose alone never counts):
+ * - tests: a `.test.<ext>` / `.spec.<ext>` path, or the phrase "test file(s)"
+ *   (the handoff template's exact header). "I added tests" without a file or
+ *   the phrase does not count.
+ * - command: a `$`-prefixed line, or a known runner invocation (bun/pnpm/
+ *   npm/yarn/npx/bunx test|run|exec, npx/bunx exec, tsc/vitest/jest/mocha/
+ *   pytest/go test/cargo test). Prose "run the tests" names no runner and
+ *   does not count (plan-quality-bar marks it a weak step anyway).
+ * - output: check marks, PASS/FAIL tokens, counts ("12 pass"), `N ok` /
+ *   TAP `ok N` / "all ok" verdicts, exit-code statements. Bare prose
+ *   `OK`/`ERROR` ("OK, moving on") does NOT count — output evidence must
+ *   look like output. Line-based and fence-insensitive: real output usually
+ *   lives in fenced blocks, so fence content is scanned too.
+ */
+export declare function assertSddTddTriple(reportText: string): GateResult;
+/**
+ * One placeholder occurrence found by `planQualityBar`.
+ */
+export type PlanQualityFinding = {
+    /** Normalized token: `TBD`, `TODO`, `TBA`, or `...`. */
+    token: string;
+    /** 1-based line number. */
+    line: number;
+    /** Trimmed source line. */
+    text: string;
+};
+/** Result of `planQualityBar`: the gate verdict plus structured findings. */
+export type PlanQualityResult = GateResult & {
+    findings: PlanQualityFinding[];
+};
+/**
+ * Plan quality bar — placeholder scan (mstar-plan-artifacts
+ * `references/plan-quality-bar.md` § Quality checklist + `templates/
+ * plan.main.md` self-review "Placeholder scan: no TBD"). Every placeholder
+ * token found becomes one `lint.plan-quality.placeholder` violation whose
+ * message lists the token and location.
+ *
+ * Heuristic (documented, conservative):
+ * - tokens: `TBD`, `TODO`, `TBA` (case-insensitive, word-boundary, plural
+ *   forms included) and the prose ellipsis `...`. One finding per line per
+ *   token (a line with two TBDs yields one finding).
+ * - negation guard: a token preceded by a negation word (`no/not/without/
+ *   none`) in the same segment (split at `(`/`[`/`{`/`.`/`;`/`,`/line
+ *   start) is an absence assertion ("no TBD/placeholder/TODO" states the
+ *   rule), not a placeholder — not flagged.
+ * - exemptions: fenced code blocks (```` ``` ```` / `~~~`) and inline code
+ *   spans are skipped — `...` in a file-list or example is not a placeholder.
+ * - out of scope (judgment stays prompt): "add tests" without code, and
+ *   `FIXME`/`XXX` code markers.
+ */
+export declare function planQualityBar(planText: string): PlanQualityResult;
+/**
+ * Lint a skill file's frontmatter against the mstar-skill-authoring §
+ * Frontmatter Contract:
+ * - `name` — stable, lowercase-hyphen (`example-skill`);
+ * - `description` — the trigger contract, third person, not a workflow
+ *   summary.
+ *
+ * Accepts a full document (leading `---`-fenced block is parsed) or a bare
+ * frontmatter body (`name:`/`description:` lines at the start). Violations:
+ * - `lint.frontmatter.missing` — no frontmatter block found
+ * - `lint.frontmatter.name.missing` — `name` absent
+ * - `lint.frontmatter.name.format` — `name` not lowercase-hyphen
+ * - `lint.frontmatter.description.missing` — `description` absent/empty
+ * - `lint.frontmatter.description.person` — first/second-person pronoun in
+ *   the description (third-person heuristic, low severity)
+ * - `lint.frontmatter.description.workflow` — description reads as a
+ *   workflow summary (verb-start or paragraph-length heuristic, low
+ *   severity)
+ *
+ * Heuristics (documented, conservative; corpus regression tests in
+ * lint.test.ts cover the 20 real skill frontmatters):
+ * - pronouns: `I`/`we`/`you`/`my`/`our`/`your`/`us`, word-boundary,
+ *   case-insensitive, after stripping quoted and backticked spans; `I/`
+ *   (I/O) and all-caps `US` exempt.
+ * - workflow shape: description starts with a workflow verb ("Explains how
+ *   …", "Describes …") — the contract's own bad example — or exceeds 120
+ *   words (corpus max 114). Bold/quote prefixes are stripped before the
+ *   verb check. No content judgment (e.g. whether the trigger is narrow
+ *   enough) — that stays prompt.
+ */
+export declare function lintSkillFrontmatter(frontmatterText: string): GateResult;
+/**
+ * Lint a STRATEGY.md document for the six required section headings
+ * (mstar-strategy § STRATEGY.md structure: Vision, What we build, What we
+ * don't build, Guiding Principles, Technology Direction, Decision Log).
+ * Optional sections (Current Focus, Risks & Mitigations, Competitive
+ * Context) are not required.
+ *
+ * Heuristic (documented, conservative): a section is a Markdown heading
+ * (`#`–`######`) whose text matches a required name exactly, case-
+ * insensitively, after stripping emphasis/backticks (so `## VISION`,
+ * `### What We Don't Build` all count). Partial matches ("Vision (short)")
+ * and other heading levels do not count. Each missing section is one
+ * `lint.strategy.missing-section` violation naming the heading.
+ */
+export declare function lintStrategySections(docText: string): GateResult;