@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.822c9439

package/dist/resources/extensions/gsd/db/queries.js

@@ -0,0 +1,398 @@
+// Project/App: gsd-pi
+// File Purpose: Query Module — the read-only seam of the DB layer.
+// SELECT-only wrappers, read through the shared engine handle (getDbOrNull()).
+// Contains NO write SQL (asserted by tests/single-writer-invariant.test.ts).
+// Read-only callers (forensics, dashboard, doctor) depend on this seam, not on
+// the single-writer surface.
+import { getDbOrNull } from "./engine.js";
+import { isClosedStatus } from "../status-guards.js";
+import { getGateIdsForTurn } from "../gate-registry.js";
+import { emptyTaskStatusCounts, rowToActiveTaskSummary, rowToIdStatusSummary, rowToTaskStatusCounts, rowsToStringColumn, } from "../db-lightweight-query-rows.js";
+import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequirement, rowsToRequirementCounts, } from "../db-decision-requirement-rows.js";
+import { rowToGate } from "../db-gate-rows.js";
+import { rowToArtifact, rowToMilestone } from "../db-milestone-artifact-rows.js";
+import { rowToSlice, rowToTask } from "../db-task-slice-rows.js";
+function parseStringArrayColumn(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((entry) => typeof entry === "string");
+    if (typeof raw !== "string")
+        return [];
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed.filter((entry) => typeof entry === "string");
+        if (typeof parsed === "string")
+            return [parsed];
+    }
+    catch {
+        return trimmed.split(",");
+    }
+    return [];
+}
+function normalizeRepoPath(file) {
+    return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+export function getDecisionById(id) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM decisions WHERE id = ?").get(id);
+    if (!row)
+        return null;
+    return rowToDecision(row);
+}
+export function getActiveDecisions() {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM active_decisions").all();
+    return rows.map(rowToActiveDecision);
+}
+export function getRequirementById(id) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM requirements WHERE id = ?").get(id);
+    if (!row)
+        return null;
+    return rowToRequirement(row);
+}
+export function getActiveRequirements() {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM active_requirements").all();
+    return rows.map(rowToActiveRequirement);
+}
+export function getRequirementCounts() {
+    if (!getDbOrNull()) {
+        return { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+    }
+    const rows = getDbOrNull()
+        .prepare("SELECT lower(status) as status, COUNT(*) as count FROM requirements GROUP BY lower(status)")
+        .all();
+    return rowsToRequirementCounts(rows);
+}
+/**
+ * ADR-017 raw primitive: returns slice IDs in a milestone whose is_sketch flag
+ * is still 1. The stale-sketch-flag drift handler at
+ * `state-reconciliation/drift/sketch-flag.ts` composes this with PLAN.md
+ * existence checks to detect drift, then writes via `setSliceSketchFlag`.
+ */
+export function getSketchedSliceIds(milestoneId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare(`SELECT id FROM slices WHERE milestone_id = :mid AND is_sketch = 1`).all({ ":mid": milestoneId });
+    return rows.map((r) => r.id);
+}
+export function getSlice(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM slices WHERE milestone_id = :mid AND id = :sid").get({ ":mid": milestoneId, ":sid": sliceId });
+    if (!row)
+        return null;
+    return rowToSlice(row);
+}
+export function getTask(milestoneId, sliceId, taskId) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid").get({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId });
+    if (!row)
+        return null;
+    return rowToTask(row);
+}
+export function getSliceTasks(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid ORDER BY sequence, id").all({ ":mid": milestoneId, ":sid": sliceId });
+    return rows.map(rowToTask);
+}
+export function getCompletedMilestoneTaskFileHints(milestoneId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare(`SELECT files, key_files
+     FROM tasks
+     WHERE milestone_id = :mid AND status IN ('complete', 'done')`).all({ ":mid": milestoneId });
+    const hints = new Set();
+    for (const row of rows) {
+        for (const raw of [row["files"], row["key_files"]]) {
+            for (const file of parseStringArrayColumn(raw)) {
+                const normalized = normalizeRepoPath(file);
+                if (normalized)
+                    hints.add(normalized);
+            }
+        }
+    }
+    return [...hints];
+}
+/** Find the most recent resolved-but-unapplied escalation override in a slice. */
+export function findUnappliedEscalationOverride(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return null;
+    // Filter BOTH flags: escalation_pending=0 AND escalation_awaiting_review=0
+    // ensures we only claim overrides the user has explicitly resolved.
+    // Without the awaiting_review filter, continueWithDefault=true artifacts
+    // (not yet responded to) would be prematurely claimed, causing the override
+    // to be lost when the user later resolves (#ADR-011 Phase 2 peer-review Bug 2).
+    const row = getDbOrNull().prepare(`SELECT id, escalation_artifact_path AS path
+       FROM tasks
+      WHERE milestone_id = :mid AND slice_id = :sid
+        AND escalation_artifact_path IS NOT NULL
+        AND escalation_override_applied_at IS NULL
+        AND escalation_pending = 0
+        AND escalation_awaiting_review = 0
+      ORDER BY sequence DESC, id DESC
+      LIMIT 1`).get({ ":mid": milestoneId, ":sid": sliceId });
+    if (!row || !row.path)
+        return null;
+    return { taskId: row.id, artifactPath: row.path };
+}
+/** List tasks with active escalation artifacts across a milestone (for /gsd escalate list). */
+export function listEscalationArtifacts(milestoneId, includeResolved = false) {
+    if (!getDbOrNull())
+        return [];
+    const filter = includeResolved
+        ? "escalation_artifact_path IS NOT NULL"
+        : "(escalation_pending = 1 OR escalation_awaiting_review = 1) AND escalation_artifact_path IS NOT NULL";
+    const rows = getDbOrNull().prepare(`SELECT * FROM tasks WHERE milestone_id = :mid AND ${filter} ORDER BY slice_id, sequence, id`).all({ ":mid": milestoneId });
+    return rows.map(rowToTask);
+}
+export function getVerificationEvidence(milestoneId, sliceId, taskId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM verification_evidence WHERE milestone_id = :mid AND slice_id = :sid AND task_id = :tid ORDER BY id").all({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId });
+    return rows;
+}
+export function getAllMilestones() {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id").all();
+    return rows.map(rowToMilestone);
+}
+export function getMilestone(id) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM milestones WHERE id = :id").get({ ":id": id });
+    if (!row)
+        return null;
+    return rowToMilestone(row);
+}
+export function getActiveMilestoneFromDb() {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1").get();
+    if (!row)
+        return null;
+    return rowToMilestone(row);
+}
+export function getActiveSliceFromDb(milestoneId) {
+    if (!getDbOrNull())
+        return null;
+    // Single query: find the first non-complete slice whose dependencies are all satisfied.
+    // Uses json_each() to expand the JSON depends array and checks each dep is complete.
+    const row = getDbOrNull().prepare(`SELECT s.* FROM slices s
+     WHERE s.milestone_id = :mid
+       AND s.status NOT IN ('complete', 'done', 'skipped')
+       AND NOT EXISTS (
+         SELECT 1 FROM json_each(s.depends) AS dep
+         WHERE dep.value NOT IN (
+           SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done', 'skipped')
+         )
+       )
+     ORDER BY s.sequence, s.id
+     LIMIT 1`).get({ ":mid": milestoneId });
+    if (!row)
+        return null;
+    return rowToSlice(row);
+}
+export function getActiveTaskFromDb(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1").get({ ":mid": milestoneId, ":sid": sliceId });
+    if (!row)
+        return null;
+    return rowToTask(row);
+}
+export function getMilestoneSlices(milestoneId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId });
+    return rows.map(rowToSlice);
+}
+/**
+ * Consolidated DB read for dispatch/gate/completion decisions (ADR-017).
+ * `done` uses the canonical closed-status predicate (`isClosedStatus`) — the
+ * same vocabulary the SQL terminal-status fragment derives from. Decision
+ * paths must consume this instead of parsing `.gsd/*.md` projections.
+ * Rows keep `getMilestoneSlices` ordering (sequence, then id).
+ */
+export function getMilestoneSliceSummaries(milestoneId) {
+    return getMilestoneSlices(milestoneId).map((s) => ({
+        id: s.id,
+        title: s.title,
+        done: isClosedStatus(s.status),
+        depends: s.depends ?? [],
+    }));
+}
+/**
+ * Ids of slices closed per the canonical status vocabulary (ADR-017), in
+ * milestone order. Thin wrapper over `getMilestoneSliceSummaries` for the
+ * common "which slices are done?" decision-path read.
+ */
+export function getClosedSliceIds(milestoneId) {
+    return getMilestoneSliceSummaries(milestoneId)
+        .filter((s) => s.done)
+        .map((s) => s.id);
+}
+export function getArtifact(path) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT * FROM artifacts WHERE path = :path").get({ ":path": path });
+    if (!row)
+        return null;
+    return rowToArtifact(row);
+}
+/** Fast milestone status check — avoids deserializing JSON planning fields. */
+export function getActiveMilestoneIdFromDb() {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT id, status FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1").get();
+    if (!row)
+        return null;
+    return rowToIdStatusSummary(row);
+}
+/** Fast slice status check — avoids deserializing JSON depends/planning fields. */
+export function getSliceStatusSummary(milestoneId) {
+    if (!getDbOrNull())
+        return [];
+    return getDbOrNull().prepare("SELECT id, status FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId }).map(rowToIdStatusSummary);
+}
+/** Fast task status check — avoids deserializing JSON arrays and large text fields. */
+export function getActiveTaskIdFromDb(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare("SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1").get({ ":mid": milestoneId, ":sid": sliceId });
+    if (!row)
+        return null;
+    return rowToActiveTaskSummary(row);
+}
+/** Count tasks by status for a slice — useful for progress reporting without full row load. */
+export function getSliceTaskCounts(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return emptyTaskStatusCounts();
+    const row = getDbOrNull().prepare(`SELECT
+       COUNT(*) as total,
+       SUM(CASE WHEN status IN ('complete', 'done') THEN 1 ELSE 0 END) as done,
+       SUM(CASE WHEN status NOT IN ('complete', 'done') THEN 1 ELSE 0 END) as pending
+     FROM tasks WHERE milestone_id = :mid AND slice_id = :sid`).get({ ":mid": milestoneId, ":sid": sliceId });
+    return rowToTaskStatusCounts(row);
+}
+/** Get all slices that depend on a given slice. */
+export function getDependentSlices(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT slice_id FROM slice_dependencies WHERE milestone_id = :mid AND depends_on_slice_id = :sid").all({ ":mid": milestoneId, ":sid": sliceId });
+    return rowsToStringColumn(rows, "slice_id");
+}
+export function getReplanHistory(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return [];
+    if (sliceId) {
+        return getDbOrNull().prepare(`SELECT * FROM replan_history WHERE milestone_id = :mid AND slice_id = :sid ORDER BY created_at DESC`).all({ ":mid": milestoneId, ":sid": sliceId });
+    }
+    return getDbOrNull().prepare(`SELECT * FROM replan_history WHERE milestone_id = :mid ORDER BY created_at DESC`).all({ ":mid": milestoneId });
+}
+export function getAssessment(path) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare(`SELECT * FROM assessments WHERE path = :path`).get({ ":path": path });
+    return row ?? null;
+}
+export function getLatestAssessmentByScope(milestoneId, scope) {
+    if (!getDbOrNull())
+        return null;
+    const row = getDbOrNull().prepare(`SELECT * FROM assessments
+      WHERE milestone_id = :mid AND scope = :scope
+      ORDER BY created_at DESC
+      LIMIT 1`).get({ ":mid": milestoneId, ":scope": scope });
+    return row ?? null;
+}
+export function getPendingGates(milestoneId, sliceId, scope) {
+    if (!getDbOrNull())
+        return [];
+    const sql = scope
+        ? `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND scope = :scope AND status = 'pending'`
+        : `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND status = 'pending'`;
+    const params = { ":mid": milestoneId, ":sid": sliceId };
+    if (scope)
+        params[":scope"] = scope;
+    return getDbOrNull().prepare(sql).all(params).map(rowToGate);
+}
+export function getGateResults(milestoneId, sliceId, scope) {
+    if (!getDbOrNull())
+        return [];
+    const sql = scope
+        ? `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND scope = :scope`
+        : `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid`;
+    const params = { ":mid": milestoneId, ":sid": sliceId };
+    if (scope)
+        params[":scope"] = scope;
+    return getDbOrNull().prepare(sql).all(params).map(rowToGate);
+}
+export function getPendingSliceGateCount(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        return 0;
+    const row = getDbOrNull().prepare(`SELECT COUNT(*) as cnt FROM quality_gates
+     WHERE milestone_id = :mid AND slice_id = :sid AND scope = 'slice' AND status = 'pending'`).get({ ":mid": milestoneId, ":sid": sliceId });
+    return row ? row["cnt"] : 0;
+}
+/**
+ * Return pending gate rows owned by a specific workflow turn.
+ *
+ * Unlike `getPendingGates(..., scope)`, this filters by the registry's
+ * `ownerTurn` metadata so callers can distinguish Q3/Q4 (owned by
+ * gate-evaluate) from Q8 (owned by complete-slice) even though both are
+ * scope:"slice". Pass `taskId` to narrow task-scoped results to one task.
+ */
+export function getPendingGatesForTurn(milestoneId, sliceId, turn, taskId) {
+    if (!getDbOrNull())
+        return [];
+    const ids = getGateIdsForTurn(turn);
+    if (ids.size === 0)
+        return [];
+    const idList = [...ids];
+    const placeholders = idList.map((_, i) => `:gid${i}`).join(",");
+    const params = {
+        ":mid": milestoneId,
+        ":sid": sliceId,
+    };
+    idList.forEach((id, i) => {
+        params[`:gid${i}`] = id;
+    });
+    let sql = `SELECT * FROM quality_gates
+     WHERE milestone_id = :mid AND slice_id = :sid
+       AND status = 'pending'
+       AND gate_id IN (${placeholders})`;
+    if (taskId !== undefined) {
+        sql += ` AND task_id = :tid`;
+        params[":tid"] = taskId;
+    }
+    return getDbOrNull().prepare(sql).all(params).map(rowToGate);
+}
+/**
+ * Count pending gates for a turn. Convenience wrapper used by state
+ * derivation to decide whether a phase transition should pause.
+ */
+export function getPendingGateCountForTurn(milestoneId, sliceId, turn) {
+    return getPendingGatesForTurn(milestoneId, sliceId, turn).length;
+}
+export function getMilestoneCommitAttributionShas(milestoneId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare(`SELECT commit_sha
+     FROM milestone_commit_attributions
+     WHERE milestone_id = :mid
+     ORDER BY created_at, commit_sha`).all({ ":mid": milestoneId });
+    return rows
+        .map((row) => typeof row["commit_sha"] === "string" ? row["commit_sha"] : "")
+        .filter(Boolean);
+}

package/dist/resources/extensions/gsd/db/sql-constants.js

@@ -0,0 +1,11 @@
+// Project/App: gsd-pi
+// File Purpose: Shared SQL literal fragments for the single-writer layer.
+// Kept out of the barrel surface (imported as values, not re-exported) so it
+// stays an implementation detail of the writers.
+import { RAW_CLOSED_STATUSES } from "../status-guards.js";
+/** Status values that mean a unit is closed; used in ON CONFLICT guards to
+ *  prevent an upsert from reopening a completed slice/task. Derived from the
+ *  single source `RAW_CLOSED_STATUSES` (ADR-030) so the SQL fragment cannot
+ *  drift from `isClosedStatus()`. Renders as `'complete', 'done', 'skipped',
+ *  'closed'`. */
+export const TERMINAL_STATUS_SQL = RAW_CLOSED_STATUSES.map((s) => `'${s}'`).join(", ");

package/dist/resources/extensions/gsd/db/writers/cascades.js

@@ -0,0 +1,194 @@
+// Project/App: gsd-pi
+// File Purpose: Domain Write Operations (Hierarchy Status Cascades) for the
+// single-writer layer. Each operation owns its own transaction() and mutates
+// the related rows of one logical hierarchy change in a single commit, so the
+// atomicity rule lives in one place instead of being hand-rolled (or missed)
+// in callers. Operations own DB-row atomicity only — markdown re-projection,
+// validation, and messaging stay in callers / db-writer.ts.
+import { getDbOrNull, transaction } from "../engine.js";
+import { GSDError, GSD_STALE_STATE } from "../../errors.js";
+import { isClosedStatus } from "../../status-guards.js";
+import { getMilestone, getSlice, getSliceTasks, getMilestoneSlices } from "../queries.js";
+// completeSliceCascade reuses the complex hierarchy write primitives (ON CONFLICT
+// upserts with null sentinels) rather than re-inlining their SQL. This is a
+// back-edge to gsd-db.ts, which re-exports this module — safe because the
+// imported bindings are hoisted function declarations only called at runtime.
+// It dissolves when these primitives move to db/writers/hierarchy.ts.
+import { insertMilestone, insertSlice, updateSliceStatus, updateMilestoneStatus } from "../../gsd-db.js";
+function requireDb() {
+    if (!getDbOrNull())
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+}
+/**
+ * Reopen a completed slice: slice → "in_progress", all its tasks → "pending",
+ * completion timestamps cleared, in one commit. Folds the hand-rolled
+ * transaction-plus-cascade previously in tools/reopen-slice.ts. Guards run
+ * inside the transaction (TOCTOU-safe).
+ */
+export function reopenSliceCascade(milestoneId, sliceId) {
+    requireDb();
+    let outcome = { ok: true, tasksReset: 0 };
+    transaction(() => {
+        const milestone = getMilestone(milestoneId);
+        if (!milestone) {
+            outcome = { ok: false, reason: "milestone-not-found" };
+            return;
+        }
+        if (isClosedStatus(milestone.status)) {
+            outcome = { ok: false, reason: "milestone-closed", status: milestone.status };
+            return;
+        }
+        const slice = getSlice(milestoneId, sliceId);
+        if (!slice) {
+            outcome = { ok: false, reason: "slice-not-found" };
+            return;
+        }
+        if (!isClosedStatus(slice.status)) {
+            outcome = { ok: false, reason: "slice-not-complete", status: slice.status };
+            return;
+        }
+        const tasks = getSliceTasks(milestoneId, sliceId);
+        getDbOrNull().prepare(`UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
+        getDbOrNull().prepare(`UPDATE tasks SET status = 'pending', completed_at = NULL WHERE milestone_id = :mid AND slice_id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
+        outcome = { ok: true, tasksReset: tasks.length };
+    });
+    return outcome;
+}
+/**
+ * Reopen a closed milestone: milestone → "active", every slice → "in_progress",
+ * every task → "pending", completion timestamps cleared, in one commit. Folds
+ * the hand-rolled transaction-plus-cascade previously in tools/reopen-milestone.ts.
+ */
+export function reopenMilestoneCascade(milestoneId) {
+    requireDb();
+    let outcome = { ok: true, slicesReset: 0, tasksReset: 0 };
+    transaction(() => {
+        const milestone = getMilestone(milestoneId);
+        if (!milestone) {
+            outcome = { ok: false, reason: "milestone-not-found" };
+            return;
+        }
+        if (!isClosedStatus(milestone.status)) {
+            outcome = { ok: false, reason: "milestone-not-closed", status: milestone.status };
+            return;
+        }
+        const slices = getMilestoneSlices(milestoneId);
+        getDbOrNull().prepare(`UPDATE milestones SET status = 'active', completed_at = NULL WHERE id = :mid`).run({ ":mid": milestoneId });
+        getDbOrNull().prepare(`UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
+        const tasksResult = getDbOrNull().prepare(`UPDATE tasks SET status = 'pending', completed_at = NULL WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
+        const tasksReset = tasksResult.changes ?? 0;
+        outcome = { ok: true, slicesReset: slices.length, tasksReset };
+    });
+    return outcome;
+}
+/**
+ * Complete a slice: verify preconditions, auto-create the milestone/slice rows
+ * if absent, mark the slice "complete", and activate a still-"planned"
+ * milestone once all its slices are closed — all in one transaction. Folds the
+ * hand-rolled cascade previously in tools/complete-slice.ts.
+ *
+ * Returns a discriminated outcome. The `duplicate: true` success case means the
+ * slice was already closed (no writes performed); the caller handles the stale/
+ * idempotent path. `existingSummaryMd` carries the slice's prior summary so the
+ * caller can backfill omitted requirement fields. Markdown rendering, file
+ * writes, and summary persistence stay in the caller.
+ */
+export function completeSliceCascade(milestoneId, sliceId, opts) {
+    requireDb();
+    let outcome = { ok: true, duplicate: false, existingSummaryMd: "" };
+    transaction(() => {
+        // Preconditions inside the txn for atomicity. A missing milestone/slice is
+        // fine — they are auto-created below; only a closed one blocks.
+        const milestone = getMilestone(milestoneId);
+        if (milestone && isClosedStatus(milestone.status)) {
+            outcome = { ok: false, reason: "milestone-closed", status: milestone.status };
+            return;
+        }
+        const slice = getSlice(milestoneId, sliceId);
+        const existingSummaryMd = slice?.full_summary_md?.trim() ?? "";
+        if (slice && isClosedStatus(slice.status)) {
+            outcome = { ok: true, duplicate: true, existingSummaryMd };
+            return;
+        }
+        const tasks = getSliceTasks(milestoneId, sliceId);
+        if (tasks.length === 0) {
+            outcome = { ok: false, reason: "no-tasks" };
+            return;
+        }
+        const incomplete = tasks
+            .filter((t) => !isClosedStatus(t.status))
+            .map((t) => ({ id: t.id, status: t.status }));
+        if (incomplete.length > 0) {
+            outcome = { ok: false, reason: "incomplete-tasks", incomplete };
+            return;
+        }
+        // All guards passed — perform writes. Preserve existing planning metadata:
+        // completion must not overwrite title/risk/depends/demo/sequence.
+        insertMilestone({ id: milestoneId, title: milestoneId });
+        if (!slice) {
+            insertSlice({ id: sliceId, milestoneId, title: opts.sliceTitle || sliceId });
+        }
+        updateSliceStatus(milestoneId, sliceId, "complete", opts.completedAt);
+        const updatedSlices = getMilestoneSlices(milestoneId);
+        if (milestone?.status === "planned" &&
+            updatedSlices.length > 0 &&
+            updatedSlices.every((s) => isClosedStatus(s.status))) {
+            updateMilestoneStatus(milestoneId, "active");
+        }
+        outcome = { ok: true, duplicate: false, existingSummaryMd };
+    });
+    return outcome;
+}
+/**
+ * Skip a slice: slice → "skipped" (unless already skipped) and every non-closed
+ * task → "skipped", in one commit. Completed/done slices are rejected; closed
+ * tasks are never downgraded. Folds the hand-rolled cascade previously in
+ * tools/skip-slice.ts. Guards run inside the transaction (TOCTOU-safe).
+ */
+export function skipSliceCascade(milestoneId, sliceId) {
+    requireDb();
+    let outcome = { ok: true, tasksSkipped: 0, wasAlreadySkipped: false };
+    transaction(() => {
+        const slice = getSlice(milestoneId, sliceId);
+        if (!slice) {
+            outcome = { ok: false, reason: "slice-not-found" };
+            return;
+        }
+        if (slice.status === "complete" || slice.status === "done") {
+            outcome = { ok: false, reason: "slice-already-complete" };
+            return;
+        }
+        const wasAlreadySkipped = slice.status === "skipped";
+        if (!wasAlreadySkipped) {
+            getDbOrNull().prepare(`UPDATE slices SET status = 'skipped', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
+        }
+        // Cascade: skip every non-closed task so milestone completion doesn't trip
+        // the deep-task guard (#4375). Closed tasks are left untouched.
+        const tasks = getSliceTasks(milestoneId, sliceId);
+        let tasksSkipped = 0;
+        for (const task of tasks) {
+            if (!isClosedStatus(task.status)) {
+                getDbOrNull().prepare(`UPDATE tasks SET status = 'skipped', completed_at = NULL WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`).run({ ":mid": milestoneId, ":sid": sliceId, ":tid": task.id });
+                tasksSkipped++;
+            }
+        }
+        outcome = { ok: true, tasksSkipped, wasAlreadySkipped };
+    });
+    return outcome;
+}
+/**
+ * Reset a slice to "active" and all of its tasks to "pending" in one commit,
+ * clearing completion timestamps. Equivalent to the historical per-task
+ * updateTaskStatus loop + updateSliceStatus in undo's reset-slice, but atomic:
+ * an interruption can no longer leave some tasks reset and others not.
+ */
+export function resetSliceCascade(milestoneId, sliceId) {
+    if (!getDbOrNull())
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    transaction(() => {
+        getDbOrNull().prepare(`UPDATE tasks SET status = 'pending', completed_at = NULL
+       WHERE milestone_id = :mid AND slice_id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
+        getDbOrNull().prepare(`UPDATE slices SET status = 'active', completed_at = NULL
+       WHERE milestone_id = :mid AND id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId });
+    });
+}