@opengsd/gsd-pi 1.8.0 → 1.8.1-dev.897b3c90

package/dist/resources/extensions/gsd/state-reconciliation/drift/project-md.js

@@ -5,8 +5,8 @@
 // instruction. Markdown hierarchy import is reserved for operator-controlled
 // migration/recovery commands, not automatic runtime reconciliation.
 import { existsSync } from "node:fs";
-import { getMilestone, isDbAvailable } from "../../gsd-db.js";
-import { findMilestoneIds } from "../../milestone-ids.js";
+import { getAllMilestones, getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { findMilestoneIds, parseMilestoneId } from "../../milestone-ids.js";
 import { resolveMilestoneFile, resolveMilestonePath } from "../../paths.js";
 function milestoneHasContent(basePath, milestoneId) {
     const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -16,6 +16,26 @@ function milestoneHasContent(basePath, milestoneId) {
         (context !== null && existsSync(context)) ||
         (summary !== null && existsSync(summary)));
 }
+/**
+ * A directory extracted to a bare `M{NNN}` id is not unregistered when the
+ * milestone is actually registered under a `unique_milestone_ids` suffixed id
+ * (`M{NNN}-<suffix>`) for the same sequence number. The flat-phase extractor in
+ * `milestone-ids` cannot recover the suffix from a descriptive slug (e.g.
+ * `07-v40fmq-m007-...-footer-system`), so it falls through to the bare `M007`.
+ * Probing the DB for a suffixed row on that sequence resolves the directory to
+ * its registered identity instead of firing a false-positive drift (issue
+ * #1281).
+ */
+function hasRegisteredSuffixedVariant(milestoneId) {
+    const { suffix, num } = parseMilestoneId(milestoneId);
+    // Only bare, well-formed `M{NNN}` ids can be ambiguous with a suffixed row.
+    if (suffix || num === 0)
+        return false;
+    return getAllMilestones().some((m) => {
+        const parsed = parseMilestoneId(m.id);
+        return parsed.num === num && parsed.suffix !== undefined;
+    });
+}
 export function detectUnregisteredMilestoneDrift(_state, ctx) {
     if (!isDbAvailable())
         return [];
@@ -23,6 +43,8 @@ export function detectUnregisteredMilestoneDrift(_state, ctx) {
     for (const milestoneId of findMilestoneIds(ctx.basePath)) {
         if (getMilestone(milestoneId))
             continue;
+        if (hasRegisteredSuffixedVariant(milestoneId))
+            continue;
         if (!milestoneHasContent(ctx.basePath, milestoneId))
             continue;
         drifts.push({ kind: "unregistered-milestone", milestoneId });
@@ -30,29 +52,47 @@ export function detectUnregisteredMilestoneDrift(_state, ctx) {
     return drifts;
 }
 /**
- * Repair intentionally fails closed. The project-root DB is authoritative at
- * runtime; markdown-only milestones must be reconciled through an explicit,
- * operator-controlled action so operators opt into changing canonical state.
- *
- * The hint deliberately leads with the *targeted*, non-destructive options. The
- * common cause of this drift is a directory left under an old ID after a
- * `unique_milestone_ids` rename, where the right fix is to rename (move) the
- * directory — not a full DB reimport. `/gsd recover --confirm` is a destructive
- * clear-and-reimport of the entire DB and is offered only as a last resort, so
- * users do not reach for it expecting a targeted repair (see issue #826).
+ * The recovery hint deliberately leads with the *targeted*, non-destructive
+ * options. The common cause of this drift is a directory left under an old ID
+ * after a `unique_milestone_ids` rename, where the right fix is to rename (move)
+ * the directory — not a full DB reimport. `/gsd recover --confirm` is a
+ * destructive clear-and-reimport of the entire DB and is offered only as a last
+ * resort, so users do not reach for it expecting a targeted repair (see issue
+ * #826).
  */
-export function repairUnregisteredMilestone(record, ctx) {
+function unregisteredMilestoneGuidance(record, ctx) {
     const dir = resolveMilestonePath(ctx.basePath, record.milestoneId);
     const dirHint = dir ?? `the .gsd directory for ${record.milestoneId}`;
-    throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection ` +
+    return (`Milestone ${record.milestoneId} exists only as markdown projection ` +
         "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
         "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
         `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
         `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
         "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones.");
 }
+/**
+ * Terminal blocker for an unregistered milestone. The project-root DB is
+ * authoritative at runtime; markdown-only milestones must be reconciled through
+ * an explicit, operator-controlled action so operators opt into changing
+ * canonical state. Exposing this as a `blocker` (matching the `artifact-db`
+ * convention) surfaces the drift as a pause-with-hint that gates dispatch,
+ * instead of a guaranteed repair throw that escalates auto-mode health to red
+ * (see issue #1281).
+ */
+export function describeUnregisteredMilestoneBlocker(record, ctx) {
+    return unregisteredMilestoneGuidance(record, ctx);
+}
+/**
+ * Repair intentionally fails closed. Retained as a defensive fallback for the
+ * reconciliation engine; in practice `blocker` short-circuits this drift into a
+ * non-fatal pause before repair is ever attempted.
+ */
+export function repairUnregisteredMilestone(record, ctx) {
+    throw new Error(unregisteredMilestoneGuidance(record, ctx));
+}
 export const unregisteredMilestoneHandler = {
     kind: "unregistered-milestone",
     detect: detectUnregisteredMilestoneDrift,
+    blocker: describeUnregisteredMilestoneBlocker,
     repair: repairUnregisteredMilestone,
 };

package/dist/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.js

@@ -7,8 +7,9 @@
 //   2. Flag-OFF downgrade: when progressive_planning is off, dispatch routes
 //      sketch slices to plan-slice, which writes PLAN.md but leaves
 //      is_sketch=1 — the next reconciliation pass clears it.
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { getSketchedSliceIds, isDbAvailable, setSliceSketchFlag, } from "../../gsd-db.js";
+import { parsePlan } from "../../parsers-legacy.js";
 import { resolveSliceFile } from "../../paths.js";
 export function detectStaleSketchFlags(state, ctx) {
     if (!isDbAvailable())
@@ -18,12 +19,54 @@ export function detectStaleSketchFlags(state, ctx) {
         return [];
     const sliceIds = getSketchedSliceIds(mid);
     return sliceIds
-        .filter((sid) => {
-        const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
-        return planPath !== null && existsSync(planPath);
-    })
+        .filter((sid) => sketchIsPlanned(ctx.basePath, mid, sid))
         .map((sid) => ({ kind: "stale-sketch-flag", mid, sid }));
 }
+/**
+ * True when a task title is a synthetic placeholder emitted by a projection
+ * round-trip rather than a real, refined task. `migrate/transformer.buildTaskTitle`
+ * produces two shapes when a plan was never decomposed:
+ *   - `Plan NN`            (fallback when phase/plan frontmatter is absent)
+ *   - `${phase} ${plan}`   (e.g. `00 01`, `00 03b`, `29-auth-system 01`)
+ * Neither carries genuine planning intent, so both must be treated as stubs.
+ */
+function isPlaceholderTaskTitle(title) {
+    const t = title.trim();
+    if (/^Plan\s+\d+[a-z]*$/i.test(t))
+        return true;
+    // buildTaskTitle returns `${phase} ${plan}` when frontmatter has both fields.
+    // Phase slugs are digit-led (e.g. `00`, `29-auth-system`); require that so
+    // legitimate titles like `Step 1` are not misclassified as stubs.
+    return /^\d[\w-]*\s+\d+[a-z]*$/i.test(t);
+}
+/**
+ * A sketch slice counts as "planned" (so its is_sketch flag may be cleared)
+ * only when it has a *real* plan on disk — not merely any PLAN file.
+ *
+ * File existence alone (#1287) is too weak: a stub/placeholder PLAN, a
+ * crash-leftover, or a projection round-trip that emits synthetic placeholder
+ * task titles (migrate/transformer.buildTaskTitle) all satisfy existsSync yet
+ * were never actually refined. Clearing the flag for one strips the `refining`
+ * guard in phase derivation and lets a phantom task drive dispatch.
+ *
+ * A legitimate plan-slice always decomposes into >= 1 genuine task, so require
+ * at least one non-placeholder task. This is strictly stricter than the old
+ * existence check — the documented crash-recovery scenarios (a real plan-slice
+ * that wrote its tasks) still clear, a bare stub no longer does.
+ */
+function sketchIsPlanned(basePath, mid, sid) {
+    const planPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+    if (planPath === null || !existsSync(planPath))
+        return false;
+    try {
+        const plan = parsePlan(readFileSync(planPath, "utf-8"));
+        return plan.tasks.some((t) => !isPlaceholderTaskTitle(t.title));
+    }
+    catch {
+        // A PLAN we cannot parse is not a trustworthy "planning done" signal.
+        return false;
+    }
+}
 export function repairStaleSketchFlag(record) {
     setSliceSketchFlag(record.mid, record.sid, false);
 }

package/dist/resources/extensions/gsd/stop-notice.js

@@ -50,8 +50,22 @@ export function isTerminalNotice(message) {
 export function isNonBlockingPauseNotice(message) {
     return message.includes("idempotent advance: unit already active");
 }
+/**
+ * A picker / next-action menu that could not render in a non-interactive
+ * (headless / RPC) session. Both wordings originate from the menu-unavailable
+ * helpers (`notifyCommandMenuUnavailable` and `notifyPickerCommandNeedsInteractiveMenu`
+ * in next-action-ui.ts / command-feedback.ts). Headless `auto`/`next` cannot
+ * answer such a menu, so the run has dead-ended and needs operator intervention.
+ * Classify it as blocked so the headless host exits 10 instead of idling
+ * forever waiting for a completion signal that never comes. (#1294)
+ */
+export function isInteractiveMenuUnavailableNotice(message) {
+    return (message.includes("menu could not be shown in this session") ||
+        message.includes("did not start:"));
+}
 export function isBlockedNoticeMessage(message) {
     return (message.includes("blocked:") ||
         (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
-        isManualResolutionNotice(message));
+        isManualResolutionNotice(message) ||
+        isInteractiveMenuUnavailableNotice(message));
 }

package/dist/resources/extensions/gsd/sync-lock.js

@@ -6,8 +6,9 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unl
 import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
 const DEFAULT_TIMEOUT_MS = 0; // fail fast; sync waits block the JS event loop
-function lockFilePath(basePath) {
-    return join(basePath, ".gsd", "sync.lock");
+const DEFAULT_LOCK_NAME = "sync.lock";
+function lockFilePath(basePath, lockName = DEFAULT_LOCK_NAME) {
+    return join(basePath, ".gsd", lockName);
 }
 /** True if the given PID is alive in the current process namespace. */
 function isPidAlive(pid) {
@@ -71,8 +72,8 @@ function tryCreateLockFile(lp, payload) {
  * I/O, and UI work on Node's single JS thread. The timeout argument remains
  * accepted for compatibility but is intentionally not used for sync waiting.
  */
-export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS) {
-    const lp = lockFilePath(basePath);
+export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS, lockName = DEFAULT_LOCK_NAME) {
+    const lp = lockFilePath(basePath, lockName);
     const lockData = JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }, null, 2);
     while (true) {
         // First try the fast path: atomic create. No check-then-write race.
@@ -82,7 +83,12 @@ export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS) {
             }
         }
         catch {
-            /* unexpected — fall through to retry */
+            // tryCreateLockFile only throws for non-EEXIST errors — a persistently
+            // uncreatable lock path (dangling-symlink parent, ENOTDIR, read-only FS).
+            // Retrying would spin the loop forever with no progress condition,
+            // blocking the JS event loop. Fail open like a contended lock so callers
+            // proceed (racy but functional) instead of hanging.
+            return { acquired: false };
         }
         // File exists. Decide whether to steal (stale + owner dead) or skip.
         let canSteal = false;
@@ -125,8 +131,8 @@ export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS) {
 /**
  * Release the advisory sync lock. No-op if lock file does not exist.
  */
-export function releaseSyncLock(basePath) {
-    const lp = lockFilePath(basePath);
+export function releaseSyncLock(basePath, lockName = DEFAULT_LOCK_NAME) {
+    const lp = lockFilePath(basePath, lockName);
     try {
         if (existsSync(lp)) {
             unlinkSync(lp);

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -12,7 +12,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { isClosedStatus } from "../status-guards.js";
-import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
+import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, getUnresolvedBlockingReworkFindingsForTask, getBlockingReworkFindingsForTask, applyReworkResolutions, } from "../gsd-db.js";
 import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
@@ -107,6 +107,44 @@ export function normalizeListParam(value) {
  * Build a TaskRow-shaped object from CompleteTaskParams so the unified
  * renderSummaryContent() can be used at completion time (#2720).
  */
+function normalizeReworkResolution(params) {
+    return (params.reworkResolution ?? []).map((resolution) => ({
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        taskId: params.taskId,
+        findingId: resolution.findingId,
+        status: resolution.status,
+        evidence: resolution.evidence,
+        decisionRef: resolution.decisionRef,
+    }));
+}
+function unresolvedReworkError(missingFindingIds) {
+    const plural = missingFindingIds.length === 1 ? "finding" : "findings";
+    return `unresolved blocking rework ${plural}: ${missingFindingIds.join(", ")} — provide reworkResolution entries with status resolved and evidence, or status deferred-with-override with evidence and decisionRef, before completing the task`;
+}
+function satisfiesBlockingReworkFinding(resolution) {
+    if (resolution.evidence.trim().length === 0)
+        return false;
+    if (resolution.status === "resolved")
+        return true;
+    return (resolution.decisionRef ?? "").trim().length > 0;
+}
+/**
+ * Restore rework findings to their pre-completion state.
+ *
+ * The completion transaction flips blocking findings to resolved/
+ * deferred-with-override via applyReworkResolutions. When a later projection
+ * or escalation write fails and we compensate by reverting the task to
+ * `pending`, we must also revert those findings. Otherwise a retry sees no
+ * unresolved blocking findings (getUnresolvedBlockingReworkFindingsForTask
+ * only returns `pending` rows) and completes the task with the blocking gate
+ * silently skipped.
+ */
+function revertAppliedReworkResolutions(snapshot) {
+    if (snapshot.length === 0)
+        return;
+    applyReworkResolutions(snapshot);
+}
 function paramsToTaskRow(params, completedAt) {
     return {
         milestone_id: params.milestoneId,
@@ -182,6 +220,7 @@ export async function handleCompleteTask(params, basePath) {
     let guardError = null;
     let summaryMd = "";
     let repairTaskSummaryRow = null;
+    let appliedReworkSnapshot = [];
     const rollbackDbPath = getWorkflowDatabasePath();
     // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
     // Building the artifact runs the full shape validation (2-4 options, unique
@@ -192,6 +231,7 @@ export async function handleCompleteTask(params, basePath) {
     // no escalation recorded, and the loop would silently advance past it.
     // The filesystem write happens later (after side effects) because that's
     // the cheapest ordering and validation is where 99% of failures live.
+    const reworkResolutions = normalizeReworkResolution(params);
     let validatedEscalationArtifact = null;
     let escalationWriteEnabled = false;
     if (params.escalation) {
@@ -231,6 +271,17 @@ export async function handleCompleteTask(params, basePath) {
             return;
         }
         const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
+        const unresolvedRework = getUnresolvedBlockingReworkFindingsForTask(params.milestoneId, params.sliceId, params.taskId);
+        const resolvedFindingIds = new Set(reworkResolutions
+            .filter(satisfiesBlockingReworkFinding)
+            .map((resolution) => resolution.findingId));
+        const missingFindingIds = unresolvedRework
+            .filter((finding) => !resolvedFindingIds.has(finding.finding_id))
+            .map((finding) => finding.finding_id);
+        if (missingFindingIds.length > 0) {
+            guardError = unresolvedReworkError(missingFindingIds);
+            return;
+        }
         if (existingTask && isClosedStatus(existingTask.status)) {
             // Stale-turn path: a timed-out turn that was superseded by recovery
             // can still reach this code when its LLM call eventually returns and
@@ -278,6 +329,33 @@ export async function handleCompleteTask(params, basePath) {
             keyDecisions: params.keyDecisions ?? [],
             fullSummaryMd: summaryMd,
         });
+        // Only persist resolutions that actually satisfy the evidence
+        // requirement. The guard above admits a finding as long as ONE satisfying
+        // entry exists, but applyReworkResolutions writes by findingId and lets the
+        // last entry win. Persisting every entry would let a later non-satisfying
+        // duplicate (empty evidence, or deferred-with-override without decisionRef)
+        // overwrite a valid resolution and leave the finding non-pending without
+        // acceptable evidence. Filtering with the same predicate the guard uses
+        // keeps the applied set and the gate consistent.
+        const resolutionsToApply = reworkResolutions.filter(satisfiesBlockingReworkFinding);
+        if (resolutionsToApply.length > 0) {
+            // Snapshot the pre-resolution state of the findings we're about to
+            // change so a compensating rollback can restore them exactly (see
+            // revertAppliedReworkResolutions).
+            const resolvedFindingIdsForSnapshot = new Set(resolutionsToApply.map((r) => r.findingId));
+            appliedReworkSnapshot = getBlockingReworkFindingsForTask(params.milestoneId, params.sliceId, params.taskId)
+                .filter((finding) => resolvedFindingIdsForSnapshot.has(finding.finding_id))
+                .map((finding) => ({
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                taskId: params.taskId,
+                findingId: finding.finding_id,
+                status: finding.status,
+                evidence: finding.evidence,
+                decisionRef: finding.decision_ref,
+            }));
+            applyReworkResolutions(resolutionsToApply);
+        }
         for (const evidence of (params.verificationEvidence ?? [])) {
             insertVerificationEvidence({
                 taskId: params.taskId,
@@ -340,6 +418,7 @@ export async function handleCompleteTask(params, basePath) {
             ensureWorkflowDbAtPath(rollbackDbPath);
             deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
             updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+            revertAppliedReworkResolutions(appliedReworkSnapshot);
             invalidateStateCache();
             rollbackSucceeded = true;
         }
@@ -430,6 +509,7 @@ export async function handleCompleteTask(params, basePath) {
                 try {
                     deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
                     updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+                    revertAppliedReworkResolutions(appliedReworkSnapshot);
                     invalidateStateCache();
                     logWarning("tool", `complete-task rolled back DB completion for ${params.milestoneId}/${params.sliceId}/${params.taskId} after escalation write failure; SUMMARY.md left on disk for retry.`);
                 }
@@ -447,6 +527,7 @@ export async function handleCompleteTask(params, basePath) {
             try {
                 deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
                 updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+                revertAppliedReworkResolutions(appliedReworkSnapshot);
                 invalidateStateCache();
                 logWarning("tool", `complete-task rolled back DB completion for ${params.milestoneId}/${params.sliceId}/${params.taskId} because hard-blocker escalation handling is disabled; SUMMARY.md left on disk for retry.`);
             }

package/dist/resources/extensions/gsd/tools/plan-task.js

@@ -5,7 +5,7 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning, insertGateRow, setSliceSketchFlag } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
-import { resolveTasksDir } from "../paths.js";
+import { resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -193,21 +193,19 @@ export async function handlePlanTask(rawParams, basePath) {
         return { error: guardError };
     }
     try {
-        const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
-        // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
-        // not as standalone TID-PLAN.md files. Re-render the slice plan so the
-        // new/updated task appears in the plan file that gsd-core reads.
-        // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists).
+        const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+        const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+        const isLegacySliceLayout = Boolean(milestonePath && slicePath && slicePath !== milestonePath);
+        let renderedPath;
         let slicePlanSynced = false;
-        try {
-            const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-            if (!tDir) {
-                await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
-                slicePlanSynced = true;
-            }
+        if (isLegacySliceLayout) {
+            const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+            renderedPath = renderResult.taskPlanPath;
         }
-        catch (syncErr) {
-            logWarning("tool", `plan-task: slice-plan sync failed: ${syncErr.message}`);
+        else {
+            const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+            renderedPath = renderResult.planPath;
+            slicePlanSynced = true;
         }
         if (slicePlanSynced) {
             setSliceSketchFlag(params.milestoneId, params.sliceId, false);
@@ -234,7 +232,7 @@ export async function handlePlanTask(rawParams, basePath) {
             milestoneId: params.milestoneId,
             sliceId: params.sliceId,
             taskId: params.taskId,
-            taskPlanPath: renderResult.taskPlanPath,
+            taskPlanPath: renderedPath,
         };
     }
     catch (err) {

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -1,6 +1,6 @@
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { relSliceFile, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
+import { join, relative } from "node:path";
+import { gsdProjectionRoot, gsdRoot, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -11,6 +11,14 @@ import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+function assessmentDbPathForRenderedFile(basePath, absPath) {
+    const projectionRoot = gsdProjectionRoot(basePath);
+    const projectionRel = relative(projectionRoot, absPath);
+    const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+        ? projectionRoot
+        : gsdRoot(basePath);
+    return `.gsd/${relative(root, absPath).replace(/\\/g, "/")}`;
+}
 function validateParams(params) {
     if (!isNonEmptyString(params?.milestoneId))
         throw new Error("milestoneId is required");
@@ -74,10 +82,6 @@ export async function handleReassessRoadmap(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
-    // ── Compute assessment artifact path ──────────────────────────────
-    // Assessment lives in the completed slice's directory.
-    // Use relSliceFile so the path is layout-aware (flat-phase or legacy).
-    const assessmentRelPath = relSliceFile(basePath, params.milestoneId, params.completedSliceId, "ASSESSMENT");
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     // Guards must be inside the transaction so the state they check cannot
     // change between the read and the write (#2723).
@@ -152,15 +156,6 @@ export async function handleReassessRoadmap(rawParams, basePath) {
                     }
                 }
             }
-            // Record assessment
-            insertAssessment({
-                path: assessmentRelPath,
-                milestoneId: params.milestoneId,
-                sliceId: params.completedSliceId,
-                status: params.verdict,
-                scope: "roadmap",
-                fullContent: params.assessment,
-            });
             // Apply slice modifications
             for (const mod of params.sliceChanges.modified) {
                 updateSliceFields(params.milestoneId, mod.sliceId, {
@@ -220,6 +215,14 @@ export async function handleReassessRoadmap(rawParams, basePath) {
             assessment: params.assessment,
             completedSliceId: params.completedSliceId,
         });
+        insertAssessment({
+            path: assessmentDbPathForRenderedFile(basePath, assessmentResult.assessmentPath),
+            milestoneId: params.milestoneId,
+            sliceId: params.completedSliceId,
+            status: params.verdict,
+            scope: "roadmap",
+            fullContent: params.assessment,
+        });
         // ── Remove stale VALIDATION file from disk (#2957) ────────────
         const hasStructuralChanges = params.sliceChanges.added.length > 0 ||
             params.sliceChanges.modified.length > 0 ||

package/dist/resources/extensions/gsd/tools/replan-task.js

@@ -0,0 +1,128 @@
+import { clearParseCache } from "../files.js";
+import { getSlice, getTask, insertReplanHistory, transaction, upsertTaskPlanning, } from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { isClosedStatus } from "../status-guards.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { renderPlanFromDb, renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { resolveMilestonePath, resolveSlicePath } from "../paths.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
+import { logWarning } from "../workflow-logger.js";
+function validateParams(params) {
+    if (!isNonEmptyString(params?.milestoneId))
+        throw new Error("milestoneId is required");
+    if (!isNonEmptyString(params?.sliceId))
+        throw new Error("sliceId is required");
+    if (!isNonEmptyString(params?.taskId))
+        throw new Error("taskId is required");
+    if (!isNonEmptyString(params?.title))
+        throw new Error("title is required");
+    if (!isNonEmptyString(params?.description))
+        throw new Error("description is required");
+    if (!isNonEmptyString(params?.estimate))
+        throw new Error("estimate is required");
+    if (!isNonEmptyString(params?.verify))
+        throw new Error("verify is required");
+    return {
+        ...params,
+        files: validateStringArray(params.files, "files"),
+        inputs: validateStringArray(params.inputs, "inputs"),
+        expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
+    };
+}
+function replanSummary(params) {
+    const ref = params.reworkBriefRef?.trim();
+    return ref
+        ? `Task ${params.taskId} replanned from rework brief ${ref}`
+        : `Task ${params.taskId} replanned`;
+}
+export async function handleReplanTask(rawParams, basePath) {
+    let params;
+    try {
+        params = validateParams(rawParams);
+    }
+    catch (err) {
+        return { error: `validation failed: ${err.message}` };
+    }
+    let guardError = null;
+    try {
+        transaction(() => {
+            const parentSlice = getSlice(params.milestoneId, params.sliceId);
+            if (!parentSlice) {
+                guardError = `missing parent slice: ${params.milestoneId}/${params.sliceId}`;
+                return;
+            }
+            if (isClosedStatus(parentSlice.status)) {
+                guardError = `cannot replan a task in a closed slice: ${params.sliceId} (status: ${parentSlice.status})`;
+                return;
+            }
+            const task = getTask(params.milestoneId, params.sliceId, params.taskId);
+            if (!task) {
+                guardError = `task not found: ${params.milestoneId}/${params.sliceId}/${params.taskId}`;
+                return;
+            }
+            if (isClosedStatus(task.status)) {
+                guardError = `cannot replan completed task ${params.taskId} — use gsd_task_reopen first`;
+                return;
+            }
+            upsertTaskPlanning(params.milestoneId, params.sliceId, params.taskId, {
+                title: params.title,
+                description: params.description,
+                estimate: params.estimate,
+                files: params.files,
+                verify: params.verify,
+                inputs: params.inputs,
+                expectedOutput: params.expectedOutput,
+                fullPlanMd: params.fullPlanMd,
+            });
+            insertReplanHistory({
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                taskId: params.taskId,
+                summary: replanSummary(params),
+                previousArtifactPath: params.reworkBriefRef ?? null,
+            });
+        });
+    }
+    catch (err) {
+        return { error: `db write failed: ${err.message}` };
+    }
+    if (guardError)
+        return { error: guardError };
+    try {
+        const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+        const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+        const isLegacySliceLayout = Boolean(milestonePath && slicePath && slicePath !== milestonePath);
+        const renderResult = isLegacySliceLayout
+            ? await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId)
+            : await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+        const taskPlanPath = "taskPlanPath" in renderResult ? renderResult.taskPlanPath : renderResult.planPath;
+        invalidateStateCache();
+        clearParseCache();
+        try {
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
+            writeManifest(basePath);
+            appendEvent(basePath, {
+                cmd: "replan-task",
+                params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
+        catch (hookErr) {
+            logWarning("tool", `replan-task post-mutation hook warning: ${hookErr.message}`);
+        }
+        return {
+            milestoneId: params.milestoneId,
+            sliceId: params.sliceId,
+            taskId: params.taskId,
+            taskPlanPath,
+        };
+    }
+    catch (err) {
+        return { error: `render failed: ${err.message}` };
+    }
+}