@mstar-harness/engine 2.4.0 → 3.0.1

package/dist/project.d.ts

@@ -0,0 +1,134 @@
+import { type GateResult, type ValidationResult } from "./core.js";
+import { type ResidualEntry } from "./status.js";
+/** Roadmap file name inside `projects/<id>/` (plan Task 4 — writer contract). */
+export declare const PROJECT_ROADMAP_FILE = "roadmap.md";
+/** Project register file name inside `projects/<id>/` (plan Task 4). */
+export declare const PROJECT_REGISTER_FILE = "residuals.json";
+/** Fallback project id for project-less flows (plan Task 4 — compass ruling 2). */
+export declare const _DEFAULT_PROJECT = "_default";
+/** Roadmap status enum (plan Task 4 — frontmatter schema). */
+export declare const ROADMAP_STATUSES: readonly ["active", "paused", "completed"];
+export type RoadmapStatus = (typeof ROADMAP_STATUSES)[number];
+/**
+ * Roadmap frontmatter (plan Task 4): machine-checkable subset. All fields
+ * are `unknown` because documents come from YAML at runtime; the validator
+ * narrows them. `milestones` / `residuals_ref` are optional; goal-item body
+ * conventions are warnings only.
+ */
+export type RoadmapFrontmatter = {
+    project_id?: unknown;
+    title?: unknown;
+    status?: unknown;
+    created_at?: unknown;
+    milestones?: unknown;
+    residuals_ref?: unknown;
+    [key: string]: unknown;
+};
+/** One register entry: the v1 residual entry verbatim + register provenance. */
+export type ProjectRegisterEntry = ResidualEntry & {
+    source_plan: string;
+    registered_at: string;
+    lifecycle_id?: string;
+};
+/**
+ * Register document shape (`projects/<id>/residuals.json`, plan Task 4;
+ * QC wave-1 W-E): `entries` keyed by plan id, each value an ARRAY of
+ * register entries — v1 `residual_findings[plan-id] = entries[]`
+ * multi-finding semantics preserved verbatim (a plan can hold 2+ open
+ * residuals). `migration_notes[]` (the old single-entry collapse record)
+ * is gone: no entries are ever skipped.
+ */
+export type ProjectRegisterDoc = {
+    entries?: Record<string, ProjectRegisterEntry[]>;
+    [key: string]: unknown;
+};
+/**
+ * Roadmap validation result: schema violations decide `ok`; body-convention
+ * findings are collected as `warnings` and never flip `ok` (plan Task 4 —
+ * goal-item body is not a hard gate).
+ */
+export type RoadmapValidation = GateResult & {
+    warnings: ValidationResult[];
+};
+/** 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 project-register rollup. `stored`/`checks`/`overall` are
+ * retained for export-surface compatibility (the P2 CLI cutover): the v1
+ * stored-summary drift check (`metadata.tech_debt_summary`) is deleted in
+ * the v3 cutover — the project register is the source of truth, so `stored`
+ * is always null and every check reports DRIFT.
+ */
+export type TechDebtRollup = {
+    computed: TechDebtSummary;
+    stored: Record<string, unknown> | null;
+    checks: TechDebtCheck[];
+    overall: "PASS" | "DRIFT";
+};
+/**
+ * Validate a roadmap.md file (plan Task 4): parse the frontmatter with the
+ * shared flat-subset parser and check the schema
+ * `{ project_id, title, status: active|paused|completed, created_at,
+ * milestones[]?, residuals_ref? }`. A roadmap file whose body follows the
+ * documented conventions (a `## Direction` section + goal items as markdown
+ * task-list items) is fully green; convention misses are `warnings` only
+ * and never flip `ok` (compass Non-Goal / AC-P1).
+ */
+export declare function validateRoadmap(filePath: string): RoadmapValidation;
+/**
+ * Validate a project register document (`projects/<id>/residuals.json`,
+ * plan Task 4; QC wave-1 W-E): `{ entries: { [key]: entry[] } }` keyed by
+ * plan id, each value an ARRAY of entries (v1 `residual_findings[plan-id]`
+ * multi-finding semantics preserved — a plan may hold 2+ open residuals).
+ * Each entry is validated by the v1 `validateResidual` verbatim (severity
+ * enum + lifecycle semantics preserved — the register re-hosts, never
+ * copies) plus the register provenance fields `source_plan` (must match its
+ * entries key) and `registered_at` (YYYY-MM-DD), and the optional
+ * `lifecycle_id`.
+ */
+export declare function validateProjectRegister(doc: unknown): GateResult;
+/**
+ * Findings cleanup gate (status-and-residuals.md § Findings cleanup modes;
+ * QC wave-1 W-D relocation — the input is the project register
+ * `projects/<id>/residuals.json`, entries keyed by plan id with an ARRAY of
+ * residuals per plan, and the plan id links the register entries to the
+ * snapshot's plan row). Every OPEN entry of the plan is checked.
+ * `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` → `allow-residual` (the v1
+ * `plans[].metadata.findings_cleanup` mirror is deleted — no dual-track).
+ */
+export declare function findingsCleanupGate(register: ProjectRegisterDoc, planId: string, opts?: {
+    mode?: FindingsCleanupMode;
+}): GateResult;
+/**
+ * Compute the tech-debt rollup over the project registers (QC wave-1 W-D
+ * relocation — status-and-residuals.md § `metadata.tech_debt_summary`
+ * semantics preserved at the project layer): `total_open` / `by_severity` /
+ * `by_target` / `by_plan` over open entries of every
+ * `projects/<id>/residuals.json` register under `projectDir` (legacy
+ * `"warning"` → `low`, `null`/`""` → `medium`; closed entries skipped;
+ * missing `target` groups under `"unspecified"`; `by_plan` keyed by plan id —
+ * the snapshot plan linkage; register values are ARRAYS per plan id, so
+ * every open entry of a plan counts).
+ *
+ * The v1 stored-summary drift check (`metadata.tech_debt_summary`) is a v1
+ * dead path — the register is the source of truth, so `stored` is always
+ * null and the retained `checks`/`overall` fields report DRIFT
+ * (export-surface compatibility until the P2 CLI cutover). Does not write
+ * anything.
+ */
+export declare function techDebtRollup(projectDir: string): TechDebtRollup;

package/dist/sdd.d.ts

@@ -35,10 +35,12 @@ export type ReviewPackageOptions = {
  *    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`.
+ *    — plan finding 2026-08-08: covers repos the status.json probe misses;
+ *    resolved relative to the established root;
+ * 3. `.mstarc` `[config] harness_dir` at `root` (repo-declared root;
+ *    resolved against the config file's directory);
+ * 4. `status.json` probe at root (`.mstar` → `.agents`);
+ * 5. 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.

package/dist/status.d.ts

@@ -1,5 +1,6 @@
 import { type GateResult } from "./core.js";
 import { type EnforcementFlag } from "./dispatch.js";
+import { type WorkflowLifecycleType } from "./workflow.js";
 /**
  * Loose shape of a parsed status.json document. All fields are `unknown`
  * because documents come from JSON at runtime; validators narrow them.
@@ -12,6 +13,25 @@ export type StatusDoc = {
     metadata?: unknown;
     [key: string]: unknown;
 };
+/**
+ * v2 root status document (`{HARNESS_DIR}/status.json`, plan Task 3 — hard
+ * cutover): `version`, `updated_at`, `workflows[]` only. The list holds
+ * ACTIVE (non-terminal) lifecycles; terminal writers unregister AFTER the
+ * snapshot write (removal-at-terminal).
+ */
+export type StatusV2Doc = {
+    version: 2;
+    updated_at: string;
+    workflows: WorkflowEntry[];
+};
+/** One active lifecycle entry of the v2 root `workflows[]` list. */
+export type WorkflowEntry = {
+    id: string;
+    type: WorkflowLifecycleType;
+    started_at: string;
+    /** Harness-relative snapshot dir (e.g. `workflows/<id>`), never absolute. */
+    dir: string;
+};
 /** Residual entry as parsed from status.json (loose — validated by `validateResidual`). */
 export type ResidualEntry = {
     id?: unknown;
@@ -42,31 +62,6 @@ export type PlanRow = {
     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`):
@@ -101,44 +96,69 @@ export declare function validatePlanRow(row: unknown): GateResult;
  */
 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.
+ * Validate one v2 root `workflows[]` entry (plan Task 3): required `id`,
+ * `type` (plan | iteration), `started_at`, `dir` — harness-relative, never
+ * absolute and never containing `..`. The removal-at-terminal invariant
+ * (snapshot exists and is non-terminal) is checked at document level by
+ * `validateStatusV2` when a harness dir is known.
  */
-export declare function validateStatus(docOrPath: StatusDoc | string): GateResult;
+export declare function validateWorkflowEntry(entry: unknown): 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.
+ * Validate a v2 status.json document (plan Task 3 — hard cutover). Accepts a
+ * parsed document or a file path (malformed JSON yields a
+ * `status.invalid-json` violation, never a throw). v1 or unknown-version
+ * inputs — including v1-shaped documents carrying a root `plans[]` — fail
+ * closed with an explicit `status.migration-required` violation carrying the
+ * `mstar migrate` hint; there is no v1 read path anymore (v1 `validateStatus`
+ * was deleted in the same task).
  *
- * `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.
+ * Required: `version: 2`, `updated_at` (YYYY-MM-DD, same convention as the
+ * v1 root), `workflows[]` of active entries (each validated by
+ * `validateWorkflowEntry`, duplicate ids rejected).
  *
- * 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.
+ * Removal-at-terminal invariant: when a harness dir is known (path input, or
+ * `opts.harnessDir` for doc input), every listed entry's snapshot at
+ * `{HARNESS_DIR}/<dir>/snapshot.json` must exist and be non-terminal — the
+ * root holds active lifecycles only, and terminal writers unregister AFTER
+ * the snapshot write. The snapshot must also PHYSICALLY live under the
+ * harness: a symlinked `workflows/<id>/` (or snapshot file) resolving
+ * outside the harness dir is rejected fail-closed (QC wave-1 S-f). Doc
+ * input without a harness dir is structure-only.
  */
-export declare function archiveResiduals(planId: string, harnessDir?: string): Promise<ArchiveResult>;
+export declare function validateStatusV2(docOrPath: StatusV2Doc | string, opts?: {
+    harnessDir?: string;
+}): GateResult;
 /**
- * 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`.
+ * Relocated v2 root validator (plan Task 3 — hard cutover, no dual path):
+ * the v1 `validateStatus` implementation was deleted in the same task that
+ * introduced the v2 surface; the public export name survives so external
+ * consumers (CLI, host hooks — cut over in P2) keep compiling and now fail
+ * closed on v1 input with the `mstar migrate` hint.
  */
-export declare function findingsCleanupGate(doc: StatusDoc, planId: string, opts?: {
-    mode?: FindingsCleanupMode;
-}): GateResult;
+export declare const validateStatus: typeof validateStatusV2;
+/**
+ * Register one active workflow entry in the v2 root file (plan Task 3).
+ * Idempotent upsert by entry `id` under the root-file `withStatusWriteLock`,
+ * bumping root `updated_at`. A missing/empty root file is initialized from
+ * the v2 template (never a v1 tree); a v1 root is refused with the
+ * `mstar migrate` hint (no silent mutation of an un-migrated tree).
+ *
+ * The final document is validated with `validateStatusV2` (including the
+ * removal-at-terminal snapshot invariant against `dirname(root)`) before the
+ * write — an entry whose snapshot is missing or terminal is refused and
+ * nothing is written.
+ */
+export declare function registerWorkflow(root: string, entry: WorkflowEntry): Promise<StatusV2Doc>;
+/**
+ * Remove one workflow entry from the v2 root file (plan Task 3). Idempotent:
+ * removing an absent id is a no-op with no write; a missing/empty root file
+ * is a no-op that never creates the file. Runs under the root-file
+ * `withStatusWriteLock`, bumping root `updated_at` only when an entry was
+ * actually removed. The final document is validated (removal-at-terminal
+ * invariant included) before the write — a v1 root is refused with the
+ * `mstar migrate` hint.
+ */
+export declare function unregisterWorkflow(root: string, id: string): Promise<StatusV2Doc>;
 /**
  * Resolve the repo-level hard-enforcement flag from the iteration compass
  * (roadmap §8.5 C4/D2): `{ITERATION_DIR}/<id>/delivery-compass.md` files are
@@ -156,13 +176,21 @@ export declare function findingsCleanupGate(doc: StatusDoc, planId: string, opts
  */
 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.
+ * Resolve the repo-declared hard-enforcement flag from `.mstarc`
+ * `[config] enforcement` (plan-conventions § `.mstarc` 格式): the nearest
+ * config at the harness dir or its parent (the repo root) wins —
+ * `hard` → hard, `soft` → soft, absent/invalid value → `none`. Same
+ * discovery scope as the sub-directory keys; a config above the repo
+ * root is never adopted.
+ */
+export declare function resolveMstarcEnforcement(harnessDir: string): EnforcementFlag;
+/**
+ * Repo-level hard-enforcement flag: `.mstarc` `[config] enforcement` wins,
+ * else the iteration compass frontmatter (`resolveCompassEnforcement`),
+ * else warn-only. Hosts compose this BELOW their explicit Config override
+ * and the per-dispatch Assignment flag (precedence: Config > Assignment
+ * flag > repo `.mstarc` > compass > warn-only) — `.mstarc` `soft` is a
+ * local rollback against a hard compass, `.mstarc` `hard` hardens
+ * flag-less dispatches and gates.
  */
-export declare function techDebtRollup(docOrPath: StatusDoc | string): TechDebtRollup;
+export declare function resolveRepoEnforcement(harnessDir: string): EnforcementFlag;

package/dist/workflow.d.ts

@@ -0,0 +1,78 @@
+import type { GateResult } from "./core.js";
+import { type IntegrationMergeLease } from "./lease.js";
+import { type PlanRow } from "./status.js";
+/** Snapshot file name inside `workflows/<id>/` (plan Task 2 — writer contract). */
+export declare const WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
+/** Lifecycle status enum (plan Task 2 — terminal set = completed|failed|stopped). */
+export declare const WORKFLOW_LIFECYCLE_STATUSES: readonly ["running", "paused", "completed", "failed", "stopped"];
+/** Terminal statuses: snapshot must carry `ended_at` and no dangling leases. */
+export declare const WORKFLOW_TERMINAL_STATUSES: readonly ["completed", "failed", "stopped"];
+/** Lifecycle type enum (plan Task 2 — id reuses the orchestration id). */
+export declare const WORKFLOW_LIFECYCLE_TYPES: readonly ["plan", "iteration"];
+export type WorkflowLifecycleStatus = (typeof WORKFLOW_LIFECYCLE_STATUSES)[number];
+export type WorkflowLifecycleType = (typeof WORKFLOW_LIFECYCLE_TYPES)[number];
+/**
+ * First-class lifecycle execution policy (plan Task 2 — keys copied from root
+ * `metadata` at migrate; values accepted-but-opaque this iteration, no
+ * semantic gate).
+ */
+export type WorkflowExecutionPolicy = {
+    plan_parallelism?: unknown;
+    worktree_mode?: unknown;
+    push_policy?: unknown;
+};
+/** Iteration branch anchors (plan Task 2 — from root metadata anchors). */
+export type WorkflowBranchAnchors = {
+    base?: string;
+    integration?: string;
+    target?: string;
+};
+/**
+ * v3 workflow snapshot (`workflows/<id>/snapshot.json`) — final schema
+ * (plan Task 2). `plans[]` rows are the legacy PlanRow shape verbatim;
+ * per-row `execution_lease` stays on the row, `integration_merge_lease` is
+ * top-level.
+ *
+ * Notes dual-home SSOT (qc wave-1 S-e): a plan row's `notes` array is the
+ * LEGACY VERBATIM copy preserved at migrate time — the RUNTIME ledger is
+ * `notes.jsonl` in the workflow dir (`migrate.ts` NOTES_LEDGER_FILE). New
+ * notes append to the ledger only; row `notes` is read-only legacy and is
+ * never a dual-write target, so the two never diverge by construction.
+ */
+export type WorkflowSnapshot = {
+    schema_version: 1;
+    id: string;
+    type: WorkflowLifecycleType;
+    status: WorkflowLifecycleStatus;
+    started_at: string;
+    ended_at?: string;
+    updated_at: string;
+    phase?: string;
+    plans: PlanRow[];
+    execution_policy?: WorkflowExecutionPolicy;
+    integration_merge_lease?: IntegrationMergeLease;
+    branch?: WorkflowBranchAnchors;
+    control_worktree_path?: string;
+    legacy_metadata?: Record<string, unknown>;
+    compass_ref?: string;
+};
+/**
+ * Validate a v3 workflow snapshot document (plan Task 2 — final schema):
+ * enum/type/id checks, `schema_version: 1`, required timestamps, `plans[]`
+ * rows validated by the legacy `validatePlanRow` with row-level
+ * `execution_lease` shape delegated to `validateExecutionLease`,
+ * `integration_merge_lease` shape delegated to
+ * `validateIntegrationMergeLease`, `execution_policy` keys accepted-but-
+ * opaque. Terminal invariant: `status` ∈ completed|failed|stopped ⇒
+ * `ended_at` present AND no row carries `execution_lease` AND no
+ * `integration_merge_lease` (no dangling leases).
+ */
+export declare function validateWorkflowSnapshot(doc: unknown): GateResult;
+/**
+ * Write a workflow snapshot as a whole-rewrite of `dir/snapshot.json` under
+ * `withStatusWriteLock(snapshotPath)` (plan Task 2 — the `.status-write.lockdir`
+ * lands inside `workflows/<id>/`, dirname of the snapshot; no harness-root
+ * pollution). The snapshot is validated first — an invalid snapshot throws
+ * and nothing is written. `dir` is created recursively.
+ */
+export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string): Promise<void>;

package/package.json

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