@mstar-harness/engine 3.1.1 → 3.1.3

package/dist/audit.d.ts

@@ -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 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;
+}>;