@mstar-harness/engine 3.1.2 → 3.2.0

package/dist/audit.d.ts

@@ -1,5 +1,5 @@
 import type { GateResult } from "./core.js";
-/** Priority values (mstar-audit SKILL § Plan files Status block). */
+/** Priority values (mstar-audit SKILL.md § Plan output (all variants) Status block). */
 export declare const AUDIT_PRIORITIES: readonly ["P1", "P2", "P3"];
 export type AuditPriority = (typeof AUDIT_PRIORITIES)[number];
 /** Effort values (Morning Star agent-oriented effort scale). */
@@ -8,12 +8,12 @@ export type AuditEffort = (typeof AUDIT_EFFORTS)[number];
 /** Risk values. */
 export declare const AUDIT_RISKS: readonly ["LOW", "MED", "HIGH"];
 export type AuditRisk = (typeof AUDIT_RISKS)[number];
-/** Category codes (finding-format.md § Category codes + SKILL Status block). */
+/** Category codes (finding-format.md § Category codes + mstar-audit SKILL.md § Plan output (all variants) Status block). */
 export declare const AUDIT_CATEGORIES: readonly ["bug", "security", "perf", "tests", "tech-debt", "migration", "dx", "docs", "direction"];
 export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
 /**
  * Validate the audit Status block(s) of a plan file against the field
- * contract (mstar-audit SKILL § Plan files):
+ * contract (mstar-audit SKILL.md § Plan output (all variants) Status block):
  * - `Priority`: P1 | P2 | P3
  * - `Effort`: XS | S | M | L | XL
  * - `Risk`: LOW | MED | HIGH
@@ -89,7 +89,7 @@ export type ScaffoldAuditPlanResult = {
 };
 /**
  * Scaffold an audit plan directory (`{PLAN_DIR}/audit-<date>/` layout,
- * mstar-audit SKILL § Phase 4): numbered `NNN-<slug>.md` plan files from
+ * mstar-audit SKILL.md § Plan output (all variants)): numbered `NNN-<slug>.md` plan files from
  * findings plus a README.md index. Numbering is monotonic — when the
  * directory already contains `NNN-*.md` files (same-date re-run), the new
  * batch continues after the highest existing number instead of restarting
@@ -97,3 +97,45 @@ export type ScaffoldAuditPlanResult = {
  * findings render in the "considered and rejected" section.
  */
 export declare function scaffoldAuditPlan(outDir: string, findings: readonly AuditFinding[], options?: ScaffoldAuditPlanOptions): ScaffoldAuditPlanResult;
+/** Options for `promoteAuditPlans`. `harnessDir` is required — the snapshot
+ * and `status.json` live under the harness, never beside the audit dir. */
+export type PromoteAuditPlansOptions = {
+    /** Absolute harness dir that contains `status.json` + `workflows/`. Required. */
+    harnessDir: string;
+    /** Default: basename of `outDir` (e.g. `audit-2026-08-22`). */
+    workflowId?: string;
+};
+/**
+ * Promote selected audit plans into the v2 workflow lifecycle as a
+ * `type: "plan"` workflow (mstar-audit SKILL.md § Plan output (all variants) — handoff): write the workflow
+ * snapshot FIRST (with one Todo PlanRow per selected file), then register
+ * the workflow entry — `validateStatusV2` validates the full status doc
+ * including the per-snapshot existence check, so the snapshot must exist
+ * before the registration. Plan rows are built from the README index
+ * `## Execution order & status` columns (Plan/Title), falling back to the
+ * private `readPlanFileSummary` only when the index lacks the row.
+ *
+ * Run-once semantics: a workflow id whose snapshot already exists refuses
+ * the promote (re-promote would drop its registered plan rows); remove
+ * that workflow first.
+ *
+ * The re-promote guard, the snapshot write, and the root upsert run in ONE
+ * atomic section under the root `withStatusWriteLock(statusPath)` — the
+ * same root lock `registerWorkflow` uses — so the guard is check-then-act
+ * safe: two concurrent same-id promotes cannot both pass it (one writes
+ * and registers; the other re-checks under the lock and refuses). The
+ * snapshot is written directly with `writeJson` under the root lock (never
+ * a nested `writeWorkflowSnapshot` — its own snapshot-dir lock would be a
+ * second serialization point; the root lock must be THE serialization
+ * point). The root upsert replicates `registerWorkflow` semantics inline
+ * via the shared `registerWorkflowEntryLocked` helper (calling
+ * `registerWorkflow` itself would re-enter the non-reentrant root lock).
+ *
+ * On any failure inside the lock, the partial snapshot + now-empty
+ * workflow dir are rolled back so a retry converges after the root
+ * conflict is resolved.
+ */
+export declare function promoteAuditPlans(outDir: string, selected: readonly string[], options: PromoteAuditPlansOptions): Promise<{
+    workflowId: string;
+    snapshotPath: string;
+}>;