@jamie-tam/forge 6.0.0

package/dist/work-manifest.js

@@ -0,0 +1,798 @@
+/**
+ * v6 work-manifest verifier.
+ *
+ * Specs:
+ *   - v6 delta: templates/manifests/v6/SCHEMA.md (phase_plan extension)
+ *   - Base structure: templates/manifests/v5/SCHEMA.md (slice graph, gates)
+ *
+ * Distinct from src/manifest.ts (which is the install manifest, forge.json).
+ *
+ * v4 manifests parse and are synthesized to a v5-shaped in-memory structure
+ * per v5 SCHEMA.md §6. v5 manifests parse as-is with `phase_plan` undefined.
+ * v6 manifests are parsed natively with phase_plan normalized to object form.
+ */
+import { readFileSync } from "node:fs";
+import { load as yamlLoad } from "js-yaml";
+// ============================================================================
+// Constants (per SCHEMA.md §3.4)
+// ============================================================================
+const RESERVED_MANIFEST_GATE_NAMES = new Set([
+    "codebase-analysis",
+    "brainstorm",
+    "design-system",
+    "architecture",
+    "task-decompose",
+    "code-review-final",
+    "test-plan",
+    "test-execution",
+    "uiux-review",
+]);
+const ALLOWED_SLICE_GATE_NAMES = new Set([
+    "skeleton-runs",
+    "build-tdd",
+    "wiki-lint",
+    "runtime-reach",
+    "code-review",
+]);
+const VALID_PHASE_PLAN_STATUSES = [
+    "active",
+    "active-light",
+    "active-commit-only",
+    "skipped",
+    "as-discovered",
+    "complete-inline",
+];
+const SLICE_ID_RE = /^[a-z][a-z0-9-]*$/;
+const VALID_SLICE_TYPES = ["skeleton", "feature-slice", "refactor-slice"];
+const VALID_SLICE_STATUSES = [
+    "pending",
+    "in-progress",
+    "gated",
+    "complete",
+    "abandoned",
+];
+const VALID_GATE_STATUSES = [
+    "pending",
+    "in-progress",
+    "complete",
+    "skipped",
+    "not-applicable",
+];
+const VALID_MANIFEST_TYPES = [
+    "feature",
+    "bugfix",
+    "hotfix",
+    "refactor",
+    "greenfield",
+];
+const VALID_MANIFEST_STATUSES = [
+    "in-progress",
+    "paused",
+    "completed",
+    "escalated",
+    "abandoned",
+];
+// Per-work-type recommended phase_plan keys, sourced from v6 SCHEMA.md §3.2's
+// recommended-keys table. Keys NOT in this set produce W_UNKNOWN_PHASE_PLAN_KEY
+// warnings (advisory only — typos are silent failures by spec, so a warning
+// gives commands a chance to catch them at preflight without breaking workflows
+// that legitimately extend their plan with custom keys).
+const RECOMMENDED_PHASE_PLAN_KEYS = new Map([
+    [
+        "feature",
+        new Set([
+            "discover-codebase",
+            "concept",
+            "wireframe",
+            "plan-design-system",
+            "prototype",
+            "iterate",
+            "codify",
+            "worktree",
+            "production-build",
+            "test-plan",
+            "uiux-review",
+            "code-review-final",
+            "deliver",
+            "onboarding",
+            "gotchas",
+        ]),
+    ],
+    [
+        "greenfield",
+        new Set([
+            "discover-requirements",
+            "concept",
+            "wireframe",
+            "plan-design-system",
+            "prototype",
+            "iterate",
+            "codify",
+            "scaffold",
+            "production-build",
+            "test-plan",
+            "uiux-review",
+            "code-review-final",
+            "deliver",
+            "onboarding",
+            "gotchas",
+        ]),
+    ],
+    [
+        "bugfix",
+        new Set(["debug-root-cause", "production-build", "code-review", "deliver", "gotchas"]),
+    ],
+    [
+        "hotfix",
+        new Set([
+            "debug-root-cause",
+            "production-build",
+            "smoke-tests",
+            "code-review-critical",
+            "deliver",
+            "gotchas",
+            "followup-ticket",
+        ]),
+    ],
+    [
+        "refactor",
+        new Set([
+            "discover-codebase",
+            "brainstorm",
+            "task-decompose",
+            "production-build",
+            "test-execution",
+            "assessment",
+            "deliver",
+            "gotchas",
+        ]),
+    ],
+]);
+// ============================================================================
+// Public API
+// ============================================================================
+export function parseManifest(yaml) {
+    let parsed;
+    try {
+        parsed = yamlLoad(yaml);
+    }
+    catch (e) {
+        const err = e;
+        return {
+            ok: false,
+            errors: [
+                {
+                    code: "E_YAML_PARSE",
+                    message: err.message ?? String(err),
+                    path: "(root)",
+                },
+            ],
+            warnings: [],
+        };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return {
+            ok: false,
+            errors: [
+                { code: "E_YAML_PARSE", message: "manifest is empty or not an object", path: "(root)" },
+            ],
+            warnings: [],
+        };
+    }
+    const root = parsed;
+    // Normalize schema_version: YAML may parse a quoted "6" as string "6", but an
+    // unquoted 6 as number 6. Treat both as v6.
+    const schemaVersion = root.schema_version !== undefined ? String(root.schema_version) : "";
+    const isV6 = schemaVersion === "6";
+    const isV5 = schemaVersion === "5";
+    const hasV4Build = root.phases && typeof root.phases === "object" && "build" in root.phases;
+    let manifest;
+    let detectedSchema;
+    if (isV6) {
+        detectedSchema = "v6";
+        manifest = root;
+    }
+    else if (isV5) {
+        detectedSchema = "v5";
+        manifest = root;
+    }
+    else if (hasV4Build) {
+        detectedSchema = "v4";
+        manifest = synthesizeV5FromV4(root);
+    }
+    else {
+        return {
+            ok: false,
+            errors: [
+                {
+                    code: "E_BAD_ENUM_VALUE",
+                    message: `unrecognised schema_version "${schemaVersion}" and no v4 phases.build present`,
+                    path: "schema_version",
+                },
+            ],
+            warnings: [],
+        };
+    }
+    const errors = [];
+    const warnings = [];
+    validateRequiredFields(manifest, errors, detectedSchema);
+    validateEnums(manifest, errors);
+    validateSliceGraph(manifest, errors);
+    validatePhaseGatePremature(manifest, errors);
+    if (detectedSchema === "v6") {
+        validateAndNormalizePhasePlan(manifest, errors);
+        validatePhasePlanKeysForType(manifest, warnings);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors, warnings };
+    }
+    return { ok: true, manifest, schema: detectedSchema, warnings };
+}
+export function readManifest(path) {
+    let yaml;
+    try {
+        yaml = readFileSync(path, "utf-8");
+    }
+    catch (e) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    code: "E_FILE_NOT_FOUND",
+                    message: `cannot read ${path}: ${e.message}`,
+                    path,
+                },
+            ],
+            warnings: [],
+        };
+    }
+    return parseManifest(yaml);
+}
+// ============================================================================
+// Structural validators
+// ============================================================================
+function validateRequiredFields(manifest, errors, schema) {
+    // slice_graph is optional in v6 (planning is allowed before slice
+    // decomposition has happened — codify fills it in). v4 and v5 manifests
+    // always have a slice_graph: v4 synthesizes one, v5 templates ship with
+    // a populated graph.
+    const required = [
+        "schema_version",
+        "name",
+        "type",
+        "description",
+        "status",
+        "created",
+        "command",
+        "phases",
+        ...(schema === "v6" ? [] : ["slice_graph"]),
+    ];
+    for (const field of required) {
+        if (manifest[field] === undefined || manifest[field] === null) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `required field "${field}" is missing`,
+                path: String(field),
+            });
+        }
+    }
+    if (schema === "v6" && (manifest.phase_plan === undefined || manifest.phase_plan === null)) {
+        errors.push({
+            code: "E_MISSING_REQUIRED_FIELD",
+            message: `v6 manifests require a "phase_plan" block`,
+            path: "phase_plan",
+        });
+    }
+    // Shape checks (per SCHEMA.md §1)
+    if (manifest.name && !SLICE_ID_RE.test(String(manifest.name))) {
+        errors.push({
+            code: "E_BAD_ENUM_VALUE",
+            message: `name "${manifest.name}" must be kebab-case (^[a-z][a-z0-9-]*$)`,
+            path: "name",
+        });
+    }
+    if (manifest.phases !== undefined && manifest.phases !== null) {
+        if (typeof manifest.phases !== "object" || Array.isArray(manifest.phases)) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `phases must be a map`,
+                path: "phases",
+            });
+        }
+    }
+    if (manifest.slice_graph !== undefined && manifest.slice_graph !== null) {
+        const sg = manifest.slice_graph;
+        if (typeof sg !== "object" || Array.isArray(sg) || !sg.slices) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `slice_graph must be a map containing "slices"`,
+                path: "slice_graph",
+            });
+        }
+        else {
+            const slices = sg.slices;
+            if (typeof slices !== "object" || Array.isArray(slices)) {
+                errors.push({
+                    code: "E_MISSING_REQUIRED_FIELD",
+                    message: `slice_graph.slices must be a map`,
+                    path: "slice_graph.slices",
+                });
+            }
+            const cs = sg.current_slice;
+            if (cs === undefined || cs === null || cs === "") {
+                errors.push({
+                    code: "E_BAD_CURRENT_SLICE",
+                    message: `slice_graph.current_slice is required and must reference an existing slice`,
+                    path: "slice_graph.current_slice",
+                });
+            }
+        }
+    }
+}
+function validateEnums(manifest, errors) {
+    if (manifest.type && !VALID_MANIFEST_TYPES.includes(manifest.type)) {
+        errors.push({
+            code: "E_BAD_ENUM_VALUE",
+            message: `type "${manifest.type}" is not one of ${VALID_MANIFEST_TYPES.join(" | ")}`,
+            path: "type",
+        });
+    }
+    if (manifest.status && !VALID_MANIFEST_STATUSES.includes(manifest.status)) {
+        errors.push({
+            code: "E_BAD_ENUM_VALUE",
+            message: `status "${manifest.status}" is not one of ${VALID_MANIFEST_STATUSES.join(" | ")}`,
+            path: "status",
+        });
+    }
+}
+function validateSliceGraph(manifest, errors) {
+    const sg = manifest.slice_graph;
+    if (!sg || typeof sg !== "object" || !sg.slices)
+        return; // missing-required already caught
+    const sliceIds = Object.keys(sg.slices);
+    // §3.1 slice IDs must match regex
+    for (const id of sliceIds) {
+        if (!SLICE_ID_RE.test(id)) {
+            errors.push({
+                code: "E_BAD_SLICE_ID",
+                message: `slice ID "${id}" must match ^[a-z][a-z0-9-]*$`,
+                path: `slice_graph.slices.${id}`,
+            });
+        }
+    }
+    // §3.1 current_slice must resolve
+    if (sg.current_slice && !sg.slices[sg.current_slice]) {
+        errors.push({
+            code: "E_BAD_CURRENT_SLICE",
+            message: `current_slice "${sg.current_slice}" does not resolve to any slice`,
+            path: "slice_graph.current_slice",
+        });
+    }
+    // §3.2 per-slice invariants
+    const skeletons = [];
+    for (const [id, slice] of Object.entries(sg.slices)) {
+        const slicePath = `slice_graph.slices.${id}`;
+        if (!slice || typeof slice !== "object") {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `slice "${id}" must be an object`,
+                path: slicePath,
+            });
+            continue;
+        }
+        if (!VALID_SLICE_TYPES.includes(slice.type)) {
+            errors.push({
+                code: "E_BAD_ENUM_VALUE",
+                message: `slice "${id}" type "${slice.type}" is not one of ${VALID_SLICE_TYPES.join(" | ")}`,
+                path: `${slicePath}.type`,
+            });
+        }
+        if (!VALID_SLICE_STATUSES.includes(slice.status)) {
+            errors.push({
+                code: "E_BAD_ENUM_VALUE",
+                message: `slice "${id}" status "${slice.status}" is not one of ${VALID_SLICE_STATUSES.join(" | ")}`,
+                path: `${slicePath}.status`,
+            });
+        }
+        if (slice.type === "skeleton") {
+            skeletons.push(id);
+            if (!slice.variant || typeof slice.variant !== "string" || slice.variant.trim() === "") {
+                errors.push({
+                    code: "E_VARIANT_REQUIRED",
+                    message: `skeleton slice "${id}" requires a non-empty variant`,
+                    path: `${slicePath}.variant`,
+                });
+            }
+            if (slice.depends_on && slice.depends_on.length > 0) {
+                errors.push({
+                    code: "E_SKELETON_NOT_ROOT",
+                    message: `skeleton slice "${id}" must have empty depends_on (it is the root)`,
+                    path: `${slicePath}.depends_on`,
+                });
+            }
+        }
+        else {
+            if (slice.variant !== undefined && slice.variant !== null) {
+                // §3.2 #8: variant must be ABSENT or null. Empty string is forbidden.
+                errors.push({
+                    code: "E_VARIANT_FORBIDDEN",
+                    message: `non-skeleton slice "${id}" must not have a variant (got: ${JSON.stringify(slice.variant)})`,
+                    path: `${slicePath}.variant`,
+                });
+            }
+        }
+        // depends_on: shape + unresolved + self
+        if (slice.depends_on !== undefined && !Array.isArray(slice.depends_on)) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `slice "${id}" depends_on must be an array (got ${typeof slice.depends_on})`,
+                path: `${slicePath}.depends_on`,
+            });
+            // Replace with empty so cycle detection doesn't crash on this slice.
+            slice.depends_on = [];
+        }
+        const deps = Array.isArray(slice.depends_on) ? slice.depends_on : [];
+        for (let i = 0; i < deps.length; i++) {
+            const dep = deps[i];
+            if (dep === id) {
+                errors.push({
+                    code: "E_SELF_DEP",
+                    message: `slice "${id}" cannot depend on itself`,
+                    path: `${slicePath}.depends_on[${i}]`,
+                });
+            }
+            if (!sg.slices[dep]) {
+                errors.push({
+                    code: "E_UNRESOLVED_DEP",
+                    message: `slice "${id}" depends on "${dep}" which does not exist`,
+                    path: `${slicePath}.depends_on[${i}]`,
+                });
+            }
+        }
+        // §3.4 gate name collisions
+        if (slice.gates === undefined || slice.gates === null) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `slice "${id}" is missing required gates map`,
+                path: `${slicePath}.gates`,
+            });
+        }
+        else if (typeof slice.gates !== "object" || Array.isArray(slice.gates)) {
+            errors.push({
+                code: "E_MISSING_REQUIRED_FIELD",
+                message: `slice "${id}" gates must be a map, not ${Array.isArray(slice.gates) ? "array" : typeof slice.gates}`,
+                path: `${slicePath}.gates`,
+            });
+        }
+        else {
+            for (const [gateName, gate] of Object.entries(slice.gates)) {
+                const gatePath = `${slicePath}.gates.${gateName}`;
+                // Name validation
+                if (RESERVED_MANIFEST_GATE_NAMES.has(gateName)) {
+                    errors.push({
+                        code: "E_GATE_COLLISION",
+                        message: `slice "${id}" gate "${gateName}" collides with a reserved manifest-level gate name`,
+                        path: gatePath,
+                    });
+                }
+                else if (!ALLOWED_SLICE_GATE_NAMES.has(gateName)) {
+                    errors.push({
+                        code: "E_BAD_ENUM_VALUE",
+                        message: `slice "${id}" gate "${gateName}" is not one of ${[...ALLOWED_SLICE_GATE_NAMES].join(" | ")}`,
+                        path: gatePath,
+                    });
+                }
+                // Payload validation (status + gate-passed)
+                if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
+                    errors.push({
+                        code: "E_MISSING_REQUIRED_FIELD",
+                        message: `gate "${gateName}" must be an object with { status, gate-passed }`,
+                        path: gatePath,
+                    });
+                }
+                else {
+                    const g = gate;
+                    if (!VALID_GATE_STATUSES.includes(g.status)) {
+                        errors.push({
+                            code: "E_BAD_ENUM_VALUE",
+                            message: `gate "${gateName}" status "${g.status}" is not one of ${VALID_GATE_STATUSES.join(" | ")}`,
+                            path: `${gatePath}.status`,
+                        });
+                    }
+                    if (typeof g["gate-passed"] !== "boolean") {
+                        errors.push({
+                            code: "E_MISSING_REQUIRED_FIELD",
+                            message: `gate "${gateName}" gate-passed must be a boolean (got ${typeof g["gate-passed"]})`,
+                            path: `${gatePath}.gate-passed`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // §3.2 #4 skeleton uniqueness
+    if (skeletons.length > 1) {
+        errors.push({
+            code: "E_MULTIPLE_SKELETONS",
+            message: `at most one slice may have type: skeleton (found: ${skeletons.join(", ")})`,
+            path: "slice_graph.slices",
+        });
+    }
+    // §3.2 #3 cycle detection (Kahn's algorithm)
+    const cycle = detectCycle(sg.slices);
+    if (cycle.length > 0) {
+        errors.push({
+            code: "E_CYCLE",
+            message: `cycle detected involving slices: ${cycle.join(" → ")}`,
+            path: "slice_graph.slices",
+        });
+    }
+    // §3.2 #6 skeleton ancestry: every non-skeleton slice must transitively depend on the skeleton
+    if (skeletons.length === 1 && cycle.length === 0) {
+        const skeletonId = skeletons[0];
+        const reachable = reverseReachableFrom(skeletonId, sg.slices);
+        for (const id of sliceIds) {
+            if (id !== skeletonId && !reachable.has(id)) {
+                errors.push({
+                    code: "E_ORPHAN_SLICE",
+                    message: `slice "${id}" does not transitively depend on skeleton "${skeletonId}"`,
+                    path: `slice_graph.slices.${id}.depends_on`,
+                });
+            }
+        }
+    }
+}
+/**
+ * v6 SCHEMA.md §3: phase_plan must be a map of string → enum (scalar) or
+ * { status: enum, reason?: string } (object). Mutates the manifest to
+ * normalize scalar values into object form so downstream code reads a
+ * uniform shape.
+ */
+function validateAndNormalizePhasePlan(manifest, errors) {
+    const raw = manifest.phase_plan;
+    if (raw === undefined || raw === null)
+        return; // missing-required already caught
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push({
+            code: "E_BAD_PHASE_PLAN_SHAPE",
+            message: `phase_plan must be a map (got ${Array.isArray(raw) ? "array" : typeof raw})`,
+            path: "phase_plan",
+        });
+        return;
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const path = `phase_plan.${key}`;
+        if (typeof value === "string") {
+            // Scalar form: `concept: skipped`
+            if (!VALID_PHASE_PLAN_STATUSES.includes(value)) {
+                errors.push({
+                    code: "E_BAD_PHASE_PLAN_STATUS",
+                    message: `phase_plan.${key} status "${value}" is not one of ${VALID_PHASE_PLAN_STATUSES.join(" | ")}`,
+                    path,
+                });
+                continue;
+            }
+            normalized[key] = { status: value };
+        }
+        else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            // Object form: `test-plan: { status: active-light, reason: "..." }`
+            const entry = value;
+            const status = entry.status;
+            if (typeof status !== "string") {
+                errors.push({
+                    code: "E_BAD_PHASE_PLAN_SHAPE",
+                    message: `phase_plan.${key} (object form) requires a "status" string field`,
+                    path: `${path}.status`,
+                });
+                continue;
+            }
+            if (!VALID_PHASE_PLAN_STATUSES.includes(status)) {
+                errors.push({
+                    code: "E_BAD_PHASE_PLAN_STATUS",
+                    message: `phase_plan.${key} status "${status}" is not one of ${VALID_PHASE_PLAN_STATUSES.join(" | ")}`,
+                    path: `${path}.status`,
+                });
+                continue;
+            }
+            const normalizedEntry = { status: status };
+            if (typeof entry.reason === "string") {
+                normalizedEntry.reason = entry.reason;
+            }
+            else if (entry.reason !== undefined) {
+                errors.push({
+                    code: "E_BAD_PHASE_PLAN_SHAPE",
+                    message: `phase_plan.${key}.reason must be a string (got ${typeof entry.reason})`,
+                    path: `${path}.reason`,
+                });
+            }
+            normalized[key] = normalizedEntry;
+        }
+        else {
+            errors.push({
+                code: "E_BAD_PHASE_PLAN_SHAPE",
+                message: `phase_plan.${key} must be a status string or { status, reason? } object`,
+                path,
+            });
+        }
+    }
+    // Replace the raw map with the normalized one so downstream readers get
+    // uniform object-form entries.
+    manifest.phase_plan = normalized;
+}
+/**
+ * Advisory check: warn on phase_plan keys not in the recommended-keys table for
+ * this manifest's work type (v6 SCHEMA.md §3.2). Typos in keys are silent
+ * failures by spec (the parser does not validate against a canonical
+ * vocabulary), so this warning gives commands a chance to catch them at
+ * preflight without breaking workflows that legitimately extend the plan with
+ * custom keys.
+ *
+ * Implemented as a warning, not an error: SCHEMA.md §3.2 reserves promotion to
+ * a hard enum if real usage shows typos causing failures. Until then, command
+ * authors can read `result.warnings` and surface them however they want.
+ */
+function validatePhasePlanKeysForType(manifest, warnings) {
+    if (!manifest.phase_plan)
+        return;
+    const allowed = RECOMMENDED_PHASE_PLAN_KEYS.get(manifest.type);
+    if (!allowed)
+        return; // unknown work type — E_BAD_ENUM_VALUE already caught that
+    for (const key of Object.keys(manifest.phase_plan)) {
+        if (!allowed.has(key)) {
+            warnings.push({
+                code: "W_UNKNOWN_PHASE_PLAN_KEY",
+                message: `phase_plan.${key} is not a recommended key for work type "${manifest.type}" (likely typo; SCHEMA.md §3.2 lists allowed keys)`,
+                path: `phase_plan.${key}`,
+            });
+        }
+    }
+}
+function validatePhaseGatePremature(manifest, errors) {
+    // §3.6: code-review-final cannot be passed until all slices are terminal.
+    // Only applies when a slice_graph exists — v6 allows manifests without one
+    // (slice decomposition happens at codify), and there's nothing to be
+    // premature about when there are no slices.
+    const quality = manifest.phases?.quality;
+    const finalGate = quality?.["code-review-final"];
+    if (!finalGate || !finalGate["gate-passed"])
+        return;
+    if (!manifest.slice_graph)
+        return;
+    const slices = manifest.slice_graph.slices;
+    const nonTerminal = Object.entries(slices).filter(([, s]) => s.status !== "complete" && s.status !== "abandoned");
+    if (nonTerminal.length > 0) {
+        errors.push({
+            code: "E_PHASE_GATE_PREMATURE",
+            message: `code-review-final.gate-passed=true but ${nonTerminal.length} slice(s) not in terminal state: ${nonTerminal.map(([id]) => id).join(", ")}`,
+            path: "phases.quality.code-review-final",
+        });
+    }
+}
+// ============================================================================
+// DAG helpers
+// ============================================================================
+/**
+ * Returns the slices forming a cycle, in cycle order. Empty array if acyclic.
+ * Uses Kahn's algorithm: any nodes left after processing must be in cycles.
+ */
+function detectCycle(slices) {
+    const indegree = new Map();
+    for (const id of Object.keys(slices))
+        indegree.set(id, 0);
+    for (const slice of Object.values(slices)) {
+        for (const dep of slice.depends_on ?? []) {
+            indegree.set(dep, (indegree.get(dep) ?? 0) + 1);
+        }
+    }
+    const queue = [];
+    for (const [id, deg] of indegree) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const slice = slices[id];
+        for (const dep of slice?.depends_on ?? []) {
+            const newDeg = (indegree.get(dep) ?? 0) - 1;
+            indegree.set(dep, newDeg);
+            if (newDeg === 0)
+                queue.push(dep);
+        }
+    }
+    const remaining = [...indegree.entries()].filter(([, deg]) => deg > 0).map(([id]) => id);
+    return remaining;
+}
+/**
+ * Returns the set of slice IDs that transitively depend on `target` (i.e. can
+ * reach target by following depends_on edges). Used for §3.2 #6 skeleton
+ * ancestry: every non-skeleton slice should be in reverseReachableFrom(skeleton).
+ */
+function reverseReachableFrom(target, slices) {
+    const reachable = new Set();
+    const visit = (id) => {
+        if (reachable.has(id))
+            return;
+        reachable.add(id);
+        for (const [otherId, otherSlice] of Object.entries(slices)) {
+            if (otherSlice.depends_on?.includes(id) && !reachable.has(otherId)) {
+                visit(otherId);
+            }
+        }
+    };
+    visit(target);
+    reachable.delete(target); // we want descendants, not target itself
+    return reachable;
+}
+// ============================================================================
+// v4 → v5 migration synthesis (SCHEMA.md §6)
+// ============================================================================
+function synthesizeV5FromV4(root) {
+    const phases = root.phases ?? {};
+    const build = phases.build ?? {};
+    const tasks = Array.isArray(build.tasks) ? build.tasks : [];
+    // §6 derivation rules (first match wins)
+    let status;
+    let gatePassed;
+    if (tasks.length === 0) {
+        status = "pending";
+        gatePassed = false;
+    }
+    else if (tasks.every((t) => t.status === "complete")) {
+        status = "complete";
+        gatePassed = true;
+    }
+    else if (tasks.some((t) => t.status === "in-progress")) {
+        status = "in-progress";
+        gatePassed = false;
+    }
+    else if (tasks.every((t) => t.status === "pending")) {
+        status = "pending";
+        gatePassed = false;
+    }
+    else {
+        status = "in-progress";
+        gatePassed = false;
+    }
+    // Strip `phases.build` from the synthesized manifest so v5 invariants apply cleanly.
+    const phasesWithoutBuild = {};
+    for (const [k, v] of Object.entries(phases)) {
+        if (k !== "build") {
+            phasesWithoutBuild[k] = v;
+        }
+    }
+    const synthesizedManifest = {
+        schema_version: "5",
+        name: String(root.name ?? root.feature ?? ""),
+        type: (root.type ?? "feature"),
+        description: String(root.description ?? ""),
+        status: (root.status ?? "in-progress"),
+        created: String(root.created ?? ""),
+        command: String(root.command ?? ""),
+        phases: phasesWithoutBuild,
+        slice_graph: {
+            current_slice: "legacy-build",
+            slices: {
+                "legacy-build": {
+                    type: "feature-slice",
+                    depends_on: [],
+                    status,
+                    gates: {
+                        "build-tdd": {
+                            status: gatePassed ? "complete" : status === "pending" ? "pending" : "in-progress",
+                            "gate-passed": gatePassed,
+                        },
+                    },
+                },
+            },
+        },
+        artifacts: root.artifacts,
+    };
+    if (root.complexity)
+        synthesizedManifest.complexity = root.complexity;
+    if (root.escalated_from !== undefined)
+        synthesizedManifest.escalated_from = root.escalated_from;
+    if (root.successor_path !== undefined)
+        synthesizedManifest.successor_path = root.successor_path;
+    return synthesizedManifest;
+}