@opengsd/gsd-pi 1.3.0-dev.72e3af2a → 1.3.0-dev.965d1788

package/README.md

@@ -158,7 +158,7 @@ Need help choosing settings? Use the [GSD Pi web configurator](https://pi.opengs
 gsd
 ```
 
-Run the setup flow, choose your preferred model provider, and open a project directory. GSD stores project planning and runtime state in `.gsd/`.
+Run the setup flow, choose your preferred model provider, and open a project directory. GSD stores project planning and runtime state in `.gsd/`, with gitignored sibling runtime directories such as `.gsd-backups/` for migration snapshots. Stale `.gsd-backups/migrate-*` snapshots are pruned after 30 days once the flat-phase `.gsd/phases/` migration is complete.
 
 For a full first-run walkthrough, see [Getting Started With gsd-pi](./docs/user-docs/getting-started.md).
 

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-f088e947f0ebb875
+377a5b3cd6318ed2

package/dist/resources/extensions/gsd/auto/verification-retry-policy.js

@@ -25,7 +25,7 @@ export function decideVerificationRetry(input) {
         return { action: "pause", reason: "missing-retry-context" };
     }
     const key = verificationRetryKey(unitType, retryInfo.unitId);
-    const failureHash = hashVerificationFailureContext(retryInfo.failureContext);
+    const failureHash = hashVerificationFailureContext(retryInfo.signature ?? retryInfo.failureContext);
     if (input.previousFailureHash === failureHash) {
         return {
             action: "pause",

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -1834,7 +1834,7 @@ export async function postUnitPreVerification(pctx, opts) {
                     saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                     s.pendingVerificationRetry = {
                         unitId: s.currentUnit.id,
-                        failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
+                        failureContext: failureDetails,
                         attempt,
                     };
                     debugLog("postUnit", { phase: "artifact-verify-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });

package/dist/resources/extensions/gsd/auto-verification.js

@@ -9,7 +9,7 @@ import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
-import { runVerificationGate, runVerificationGateForTargets, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
+import { runVerificationGate, runVerificationGateForTargets, formatFailureContext, formatFailureSignature, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
 import { runPostExecutionChecks } from "./post-execution-checks.js";
@@ -686,10 +686,13 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 ctx.ui.notify(`Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) during verification retry; keeping verification failure as the authoritative blocker.`, "warning");
             }
             const nextAttempt = attempt + 1;
+            const failureContext = verdict.failureContext || formatFailureContext(result);
+            const failureSignature = formatFailureSignature(result);
             s.verificationRetryCount.set(retryKey, nextAttempt);
             s.pendingVerificationRetry = {
                 unitId: s.currentUnit.id,
-                failureContext: verdict.failureContext || formatFailureContext(result),
+                failureContext,
+                ...(failureSignature ? { signature: failureSignature } : {}),
                 attempt: nextAttempt,
             };
             const failedCmds = result.checks

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -703,6 +703,12 @@ export function registerHooks(pi, ecosystemHandlers) {
                     }
                 }
             }
+            const projectRoot = resolveWorktreeProjectRoot(basePath);
+            const { pruneStaleFlatPhaseBackups } = await import("../flat-phase-migration.js");
+            const pruned = pruneStaleFlatPhaseBackups(projectRoot);
+            if (pruned > 0) {
+                safetyLogWarning("bootstrap", `pruned ${pruned} stale flat-phase migration backup(s) from .gsd-backups/ (retention exceeded)`);
+            }
         }
         catch (err) {
             safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, insertAssessment, isDbAvailable, transaction, } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk, } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
 import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
 import { relMilestoneFile, resolveSliceFile } from "./paths.js";
@@ -144,6 +144,8 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
         });
     }
     for (const slice of slices) {
+        if (isDeferredStatus(slice.status))
+            continue;
         if (!isClosedStatus(slice.status)) {
             return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
         }

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -387,6 +387,9 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
                 missing.push(".gsd-worktrees/");
             }
+            if (!existingLines.has(".gsd-backups/") && !existingLines.has(".gsd-backups")) {
+                missing.push(".gsd-backups/");
+            }
             if (!hasBlanketIgnore) {
                 missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
             }

package/dist/resources/extensions/gsd/flat-phase-migration.js

@@ -59,6 +59,51 @@ export function needsFlatPhaseMigration(basePath) {
     // Resume an interrupted migration where the legacy tree was renamed aside.
     return hasLegacyMilestoneSubdirs(legacyMigratingPath(basePath));
 }
+/** Retention window before flat-phase migration backups are auto-pruned. */
+export const FLAT_PHASE_BACKUP_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Remove stale flat-phase migration backups after the retention window.
+ * Only runs when migration is complete (.gsd/phases/ exists, legacy layout gone).
+ * Returns the number of migrate-* directories removed.
+ */
+export function pruneStaleFlatPhaseBackups(basePath) {
+    if (needsFlatPhaseMigration(basePath))
+        return 0;
+    const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+    if (!existsSync(phasesPath))
+        return 0;
+    const backupRoot = join(basePath, ".gsd-backups");
+    if (!existsSync(backupRoot))
+        return 0;
+    const now = Date.now();
+    let removed = 0;
+    for (const entry of readdirSync(backupRoot)) {
+        if (!entry.startsWith("migrate-"))
+            continue;
+        const dirPath = join(backupRoot, entry);
+        try {
+            const st = statSync(dirPath);
+            if (!st.isDirectory())
+                continue;
+            if (now - st.mtimeMs < FLAT_PHASE_BACKUP_RETENTION_MS)
+                continue;
+            rmSync(dirPath, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Non-fatal: leave backup for manual recovery.
+        }
+    }
+    try {
+        if (readdirSync(backupRoot).length === 0) {
+            rmSync(backupRoot, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Non-fatal.
+    }
+    return removed;
+}
 /**
  * Migrate from legacy nested .gsd/milestones/ to flat-phase .gsd/phases/.
  *

package/dist/resources/extensions/gsd/git-service.js

@@ -208,6 +208,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",

package/dist/resources/extensions/gsd/gitignore.js

@@ -24,6 +24,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  */
 const GSD_RUNTIME_PATTERNS = [
     ".gsd-worktrees/",
+    ".gsd-backups/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -48,6 +49,8 @@ const BASELINE_PATTERNS = [
     ".gsd",
     // Worktree container sibling — NOT covered by the ".gsd" pattern above.
     ".gsd-worktrees/",
+    // Flat-phase migration snapshots — NOT covered by the ".gsd" pattern above.
+    ".gsd-backups/",
     ".gsd-id",
     ".mcp.json",
     ".bg-shell/",

package/dist/resources/extensions/gsd/json-persistence.js

@@ -56,6 +56,26 @@ export function saveJsonFile(filePath, data) {
         // Non-fatal — don't let persistence failures break operation
     }
 }
+/**
+ * Save a JSON file atomically using compact serialization.
+ *
+ * Intended for machine-only ledgers where pretty-printing has no consumer.
+ * Keeps the same write-tmp-rename safety and non-fatal error behavior as
+ * saveJsonFile.
+ */
+export function saveJsonFileCompact(filePath, data) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        // Use randomized tmp suffix to prevent concurrent-write data loss
+        const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(data) + "\n", "utf-8");
+        renameSync(tmp, filePath);
+        // No cleanup needed — renameSync atomically removes tmp on success
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break operation
+    }
+}
 /**
  * Write a JSON file atomically (write to .tmp, then rename).
  * Creates parent directories as needed. Non-fatal on error.

package/dist/resources/extensions/gsd/knowledge-backfill.js

@@ -24,8 +24,8 @@ import { logWarning } from "./workflow-logger.js";
  * - Idempotent (per-row): each migrated memory carries
  *   `structured_fields.sourceKnowledgeId = "<P|L>NNN"`. Rows whose ID is
  *   already present in the memory store are skipped.
- * - Best-effort: never throws. Logs and returns 0 on failure so a broken
- *   backfill cannot block agent startup.
+ * - Best-effort: never throws. Failed memory inserts are logged and skipped;
+ *   setup/read failures log and return 0 so backfill cannot block startup.
  * - Rules (K###) are intentionally skipped — they remain manually maintained
  *   in `KNOWLEDGE.md` per ADR-013.
  *
@@ -56,15 +56,22 @@ export function backfillKnowledgeToMemories(basePath) {
             const matchPattern = `%"sourceKnowledgeId":"${synth.id}"%`;
             if (checkExisting.get({ ":pattern": matchPattern }))
                 continue;
-            const id = createMemory({
-                category: synth.category,
-                content: synth.content,
-                scope: synth.scope,
-                confidence: 0.85,
-                structuredFields: synth.structuredFields,
-            });
-            if (id)
-                written += 1;
+            try {
+                const id = createMemory({
+                    category: synth.category,
+                    content: synth.content,
+                    scope: synth.scope,
+                    confidence: 0.85,
+                    structuredFields: synth.structuredFields,
+                });
+                if (id)
+                    written += 1;
+            }
+            catch (rowErr) {
+                const message = rowErr instanceof Error ? rowErr.message : String(rowErr);
+                logWarning("knowledge-backfill", `KNOWLEDGE.md -> memories backfill skipped ${synth.id}: ${message}`);
+                continue;
+            }
         }
         return written;
     }

package/dist/resources/extensions/gsd/memory-backfill.js

@@ -33,8 +33,8 @@ import { logWarning } from "./workflow-logger.js";
  *   decision is checked individually; only decisions whose id is already
  *   present in the memory store are skipped. A user-authored memory with
  *   their own `sourceDecisionId` does NOT abort the backfill.
- * - Best-effort: never throws. Logs and returns 0 on failure so a broken
- *   backfill cannot block agent startup.
+ * - Best-effort: never throws. Failed memory inserts are logged and skipped;
+ *   setup/read failures log and return 0 so backfill cannot block startup.
  * - Full migration (ADR-013 Stage 2a): both active and superseded rows are
  *   migrated. `structured_fields.superseded_by` preserves the supersedes
  *   chain so the DECISIONS.md projection regen can source from memories
@@ -117,25 +117,32 @@ export function backfillDecisionsToMemories() {
                 continue;
             }
             const content = synthesizeDecisionMemoryContent(row);
-            const id = createMemory({
-                category: "architecture",
-                content,
-                scope: row.scope || "project",
-                confidence: 0.85,
-                structuredFields: {
-                    sourceDecisionId: row.id,
-                    when_context: row.when_context,
-                    scope: row.scope,
-                    decision: row.decision,
-                    choice: row.choice,
-                    rationale: row.rationale,
-                    made_by: row.made_by,
-                    revisable: row.revisable,
-                    superseded_by: row.superseded_by,
-                },
-            });
-            if (id)
-                written += 1;
+            try {
+                const id = createMemory({
+                    category: "architecture",
+                    content,
+                    scope: row.scope || "project",
+                    confidence: 0.85,
+                    structuredFields: {
+                        sourceDecisionId: row.id,
+                        when_context: row.when_context,
+                        scope: row.scope,
+                        decision: row.decision,
+                        choice: row.choice,
+                        rationale: row.rationale,
+                        made_by: row.made_by,
+                        revisable: row.revisable,
+                        superseded_by: row.superseded_by,
+                    },
+                });
+                if (id)
+                    written += 1;
+            }
+            catch (rowErr) {
+                const message = rowErr instanceof Error ? rowErr.message : String(rowErr);
+                logWarning("memory-backfill", `decisions->memories backfill skipped ${row.id}: ${message}`);
+                continue;
+            }
         }
         if (healed > 0) {
             logWarning("memory-backfill", `decisions->memories drift healed: ${healed} row${healed === 1 ? "" : "s"} updated superseded_by`);

package/dist/resources/extensions/gsd/metrics.js

@@ -17,7 +17,7 @@ import { join } from "node:path";
 import { openSync, closeSync, unlinkSync, statSync, writeFileSync } from "node:fs";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
-import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { loadJsonFile, loadJsonFileOrNull, saveJsonFileCompact } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -636,7 +636,7 @@ export function pruneMetricsLedger(base, keepCount) {
         return 0;
     const removed = disk.units.length - keepCount;
     disk.units = keepNewestUnits(disk.units, keepCount);
-    saveJsonFile(metricsPath(base), disk);
+    saveJsonFileCompact(metricsPath(base), disk);
     // Keep the in-memory ledger in sync if it is loaded for this session.
     if (ledger) {
         ledger.units = keepNewestUnits(ledger.units, keepCount);
@@ -799,7 +799,7 @@ function saveLedger(base, data) {
                 : dataUnits;
             merged.sort(compareUnitsByTime);
             data.units = keepNewestUnits(merged);
-            saveJsonFile(path, data);
+            saveJsonFileCompact(path, data);
         }
         finally {
             releaseLock(lockPath);
@@ -813,6 +813,6 @@ function saveLedger(base, data) {
         // read-merge-write sequence without mutual exclusion.
         logWarning("fs", "saveLedger: lock not acquired — falling back to direct write (no merge)");
         data.units = keepNewestUnits(data.units);
-        saveJsonFile(path, data);
+        saveJsonFileCompact(path, data);
     }
 }

package/dist/resources/extensions/gsd/orphan-stash-audit.js

@@ -26,16 +26,78 @@ function _isAlreadyRestoredApplyError(err) {
     return /already exists, no checkout/i.test(message);
 }
 export { _isAlreadyRestoredApplyError };
+function gitOutput(basePath, args) {
+    return execFileSync("git", args, {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+    });
+}
+function listStashUntrackedPaths(basePath, stashRef) {
+    try {
+        return gitOutput(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]).split("\0").filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+function listStashTrackedPaths(basePath, stashRef) {
+    try {
+        return gitOutput(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]).split("\0").filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+function readWorkingTreeStatus(basePath) {
+    try {
+        return gitOutput(basePath, ["status", "--porcelain", "-z", "--untracked-files=all"])
+            .split("\0")
+            .filter(Boolean)
+            .map((entry) => ({ code: entry.slice(0, 2), path: entry.slice(3) }));
+    }
+    catch {
+        return null;
+    }
+}
+function isAlreadyRestoredUntrackedStatus(basePath, stashRef, statusEntries) {
+    if (statusEntries.length === 0 || statusEntries.some((entry) => entry.code !== "??"))
+        return false;
+    const stashTrackedPaths = listStashTrackedPaths(basePath, stashRef);
+    if (!stashTrackedPaths || stashTrackedPaths.length > 0)
+        return false;
+    const stashUntrackedPaths = listStashUntrackedPaths(basePath, stashRef);
+    if (!stashUntrackedPaths || stashUntrackedPaths.length === 0)
+        return false;
+    const stashUntrackedPathSet = new Set(stashUntrackedPaths);
+    const workingTreeUntrackedPathSet = new Set(statusEntries.map((entry) => entry.path));
+    // "Already restored" requires the working tree's untracked paths to match the
+    // stash's untracked paths exactly, in BOTH directions:
+    //   1. every current untracked path comes from the stash (no unexplained user
+    //      work that an apply would clobber), AND
+    //   2. every stash untracked path is already present in the working tree.
+    // Without (2), a partial restore (where only some stash files were recovered)
+    // would be misread as fully restored: the audit would no-op without applying
+    // or warning, leaving the remaining pre-merge files missing.
+    return (statusEntries.every((entry) => stashUntrackedPathSet.has(entry.path)) &&
+        stashUntrackedPaths.every((path) => workingTreeUntrackedPathSet.has(path)));
+}
+function manualApplyWarning(stashRef, milestoneId, reason) {
+    return (`Pre-merge stash ${stashRef} for milestone ${milestoneId} not auto-applied: ${reason}; ` +
+        `run \`git stash apply ${stashRef}\` manually to restore your pre-merge changes.`);
+}
 /**
  * Audit `git stash list` for orphaned `gsd-preflight-stash:M00x:*` entries.
  *
  * The matching merge code in `phases.ts` previously skipped the postflight
  * pop whenever `mergeAndExit` threw, leaking the user's pre-merge working
- * tree into the stash list. For every preflight-stash entry whose milestone
- * is now complete (per the supplied callback), `git stash apply` is invoked —
+ * tree into the stash list. Completed-milestone stashes are only auto-applied
+ * when the working tree is clean and the stash does not modify tracked files.
+ * Dirty trees and tracked-file stashes are left untouched with a manual
+ * recovery warning. When auto-apply is safe, `git stash apply` is invoked —
  * NOT `pop`. The stash entry stays in the list so the user retains a backup
- * if the apply produces unexpected merge results. Idempotent across repeated
- * startup runs.
+ * if the apply produces unexpected merge results.
  *
  * Failures are best-effort: a list error (no repo, git unavailable) returns
  * an empty result. An apply error becomes a warning the user sees alongside
@@ -45,12 +107,7 @@ export function auditOrphanedPreflightStashes(basePath, isMilestoneComplete) {
     const result = { applied: [], warnings: [] };
     let listOutput;
     try {
-        listOutput = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-            env: GIT_NO_PROMPT_ENV,
-        });
+        listOutput = gitOutput(basePath, ["stash", "list", "--format=%gd%x00%s"]);
     }
     catch {
         return result;
@@ -78,13 +135,32 @@ export function auditOrphanedPreflightStashes(basePath, isMilestoneComplete) {
         }
         if (!complete)
             continue;
+        const statusEntries = readWorkingTreeStatus(basePath);
+        if (!statusEntries) {
+            result.warnings.push(manualApplyWarning(ref, milestoneId, "could not verify working tree status"));
+            continue;
+        }
+        if (statusEntries.length > 0) {
+            if (isAlreadyRestoredUntrackedStatus(basePath, ref, statusEntries))
+                continue;
+            result.warnings.push(manualApplyWarning(ref, milestoneId, "working tree not clean"));
+            continue;
+        }
+        const trackedPaths = listStashTrackedPaths(basePath, ref);
+        if (trackedPaths === null) {
+            result.warnings.push(manualApplyWarning(ref, milestoneId, "could not inspect tracked paths in stash"));
+            continue;
+        }
+        if (trackedPaths.length > 0) {
+            // A retained tracked-file stash has no durable marker showing whether a
+            // clean tree needs first recovery or would be re-mutated by an old backup.
+            const preview = trackedPaths.slice(0, 5).join(", ");
+            const suffix = trackedPaths.length > 5 ? `, and ${trackedPaths.length - 5} more` : "";
+            result.warnings.push(manualApplyWarning(ref, milestoneId, `stash modifies tracked files (${preview}${suffix})`));
+            continue;
+        }
         try {
-            execFileSync("git", ["stash", "apply", "--quiet", ref], {
-                cwd: basePath,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-                env: GIT_NO_PROMPT_ENV,
-            });
+            gitOutput(basePath, ["stash", "apply", "--quiet", ref]);
             result.applied.push({ milestoneId, stashRef: ref });
         }
         catch (err) {

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -45,7 +45,7 @@ If slice research is inlined, trust its architectural findings, but verify every
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
+9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. Any npm package name in a task description's install/add instructions (`npm install`, `yarn add`, `pnpm add`) or in `require('...')` or `import ... from '...'` code examples is subject to pre-execution registry validation; reference only packages that exist on the public npm registry, and remove or correct any package name that is not real. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -44,8 +44,11 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles, file
     const actualFiles = getChangedFilesFromLastCommit(basePath);
     if (!actualFiles)
         return null;
-    // Filter out .gsd/ internal files — only validate project source files
-    const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
+    // Filter out GSD-internal paths — only validate project source files.
+    const projectFiles = actualFiles.filter((f) => !f.startsWith(".gsd/") &&
+        !f.startsWith(".gsd\\") &&
+        !f.startsWith(".gsd-backups/") &&
+        !f.startsWith(".gsd-backups\\"));
     // Normalize expected paths (strip leading ./ or /)
     const normalizedExpected = new Set([...allExpected].map((f) => normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, "")));
     // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).

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

@@ -13,7 +13,7 @@ import { existsSync } from "node:fs";
 import { transaction, getMilestone, getMilestoneSlices, getSliceTasks, getLatestAssessmentByScope, updateMilestoneStatus, } from "../gsd-db.js";
 import { clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { stripIdPrefix } from "../workflow-projections.js";
@@ -118,7 +118,7 @@ export async function handleCompleteMilestone(params, basePath) {
             guardError = `no slices found for milestone ${params.milestoneId}`;
             return;
         }
-        const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
+        const incompleteSlices = slices.filter(s => !isClosedStatus(s.status) && !isDeferredStatus(s.status));
         if (incompleteSlices.length > 0) {
             const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
             guardError = `incomplete slices: ${incompleteIds}`;
@@ -126,6 +126,8 @@ export async function handleCompleteMilestone(params, basePath) {
         }
         // Deep check: verify all tasks in all slices are complete
         for (const slice of slices) {
+            if (isDeferredStatus(slice.status))
+                continue;
             const tasks = getSliceTasks(params.milestoneId, slice.id);
             const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
             if (incompleteTasks.length > 0) {

package/dist/resources/extensions/gsd/undo.js

@@ -13,6 +13,7 @@ import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveSliceFile, resolveTa
 import { sendDesktopNotification } from "./notifications.js";
 import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
+import { UNIT_REGISTRY } from "./unit-registry.js";
 /**
  * Undo the last completed unit: revert git commits,
  * delete summary artifacts, and uncheck the task in PLAN.
@@ -35,15 +36,19 @@ export async function handleUndo(args, ctx, _pi, basePath) {
         ctx.ui.notify("Nothing to undo — no activity logs found.", "info");
         return;
     }
-    // Extract unit type and ID from the most recent activity log filename
-    // Format: <seq>-<unitType>-<unitId>.jsonl
-    const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
-    if (!match) {
+    // Extract unit type and ID from the most recent activity log filename.
+    // Both the unit type and the unit ID may contain hyphens, so anchor on the
+    // known unit-type vocabulary instead of guessing the unit-ID shape: a regex
+    // tuned to milestone-shaped IDs rejects project-level units whose IDs are
+    // symbolic (e.g. discuss-project uses PROJECT, workflow-preferences uses
+    // WORKFLOW-PREFS).
+    const parsed = parseActivityLogFilename(files[0]);
+    if (!parsed) {
         ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
         return;
     }
-    const unitType = match[1];
-    const unitId = match[2].replace(/-/g, "/");
+    const unitType = parsed.unitType;
+    const unitId = parsed.unitId.replace(/-/g, "/");
     if (!force) {
         ctx.ui.notify(`Will undo: ${unitType} (${unitId})\n` +
             `This will:\n` +
@@ -87,6 +92,11 @@ export async function handleUndo(args, ctx, _pi, basePath) {
     if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
         const [mid, sid, tid] = [milestone, slice, task];
         planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+        if (getTask(mid, sid, tid)) {
+            updateTaskStatus(mid, sid, tid, "pending");
+            await renderPlanCheckboxes(basePath, mid, sid);
+            planUpdated = true;
+        }
     }
     // 3. Try to revert git commits from activity log
     let commitsReverted = 0;
@@ -318,6 +328,33 @@ export async function handleResetSlice(args, ctx, _pi, basePath) {
     ctx.ui.notify(results.join("\n"), "success");
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+// Known unit types sorted longest-first so a more specific type (e.g.
+// "execute-task-simple") matches before a prefix of it ("execute-task") when
+// splitting "<seq>-<unitType>-<unitId>.jsonl".
+const UNIT_TYPES_BY_LENGTH_DESC = Object.keys(UNIT_REGISTRY).sort((a, b) => b.length - a.length);
+/**
+ * Parse an activity-log filename of the form `<seq>-<unitType>-<unitId>.jsonl`
+ * (the format written by activity-log.ts). Both the unit type and the unit ID
+ * may contain hyphens, so we anchor on the known unit-type vocabulary rather
+ * than guessing the ID shape. This keeps non-milestone IDs (e.g. PROJECT,
+ * WORKFLOW-PREFS) parseable. Returns null when the name has no sequence prefix
+ * or does not start with a recognised unit type.
+ */
+export function parseActivityLogFilename(filename) {
+    const seqMatch = filename.match(/^\d+-(.+)\.jsonl$/);
+    if (!seqMatch)
+        return null;
+    const rest = seqMatch[1];
+    for (const unitType of UNIT_TYPES_BY_LENGTH_DESC) {
+        const prefix = `${unitType}-`;
+        if (rest.startsWith(prefix)) {
+            const unitId = rest.slice(prefix.length);
+            if (unitId.length > 0)
+                return { unitType, unitId };
+        }
+    }
+    return null;
+}
 export function uncheckTaskInPlan(basePath, mid, sid, tid) {
     const slicePath = resolveSlicePath(basePath, mid, sid);
     if (!slicePath)