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

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -94,27 +94,48 @@ function getActiveDecisions() {
         return [];
     }
 }
-/**
- * True when a memory row has a `structured_fields` JSON payload containing
- * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
- * `backfillDecisionsToMemories` so the scanner is consistent with the
- * backfill's idempotency check.
- */
-function memoryHasSourceMarker(markerKey, value) {
+function emptyMemorySourceMarkers() {
+    return { decisionIds: new Set(), knowledgeIds: new Set() };
+}
+function getMemorySourceMarkers() {
+    const markers = emptyMemorySourceMarkers();
     if (!isDbAvailable())
-        return false;
+        return markers;
     const adapter = _getAdapter();
     if (!adapter)
-        return false;
+        return markers;
     try {
-        const pattern = `%"${markerKey}":"${value}"%`;
-        const row = adapter
-            .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
-            .get({ ":pattern": pattern });
-        return row !== undefined;
+        const rows = adapter
+            .prepare("SELECT structured_fields FROM memories WHERE structured_fields IS NOT NULL")
+            .all();
+        for (const row of rows) {
+            collectMemorySourceMarker(markers, row["structured_fields"]);
+        }
     }
     catch {
-        return false;
+        return markers;
+    }
+    return markers;
+}
+function collectMemorySourceMarker(markers, raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const fields = parsed;
+        const decisionId = fields["sourceDecisionId"];
+        if (typeof decisionId === "string" && decisionId.length > 0) {
+            markers.decisionIds.add(decisionId);
+        }
+        const knowledgeId = fields["sourceKnowledgeId"];
+        if (typeof knowledgeId === "string" && knowledgeId.length > 0) {
+            markers.knowledgeIds.add(knowledgeId);
+        }
+    }
+    catch {
+        return;
     }
 }
 // ─── Public API ──────────────────────────────────────────────────────────────
@@ -127,10 +148,14 @@ const SAMPLE_LIMIT = 5;
 export function scanConsolidationGaps(basePath) {
     // ── Decisions ────────────────────────────────────────────────────────
     const decisions = getActiveDecisions();
+    const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+    const memorySourceMarkers = decisions.length > 0 || knowledgeRows.length > 0
+        ? getMemorySourceMarkers()
+        : emptyMemorySourceMarkers();
     const decisionSamples = [];
     let decisionMigrated = 0;
     for (const decision of decisions) {
-        if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+        if (memorySourceMarkers.decisionIds.has(decision.id)) {
             decisionMigrated += 1;
             continue;
         }
@@ -142,16 +167,14 @@ export function scanConsolidationGaps(basePath) {
         }
     }
     // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
-    const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
     const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
     const knowledgeSamples = [];
     let knowledgeMigrated = 0;
     for (const row of knowledgeRows) {
         knowledgeByTable[row.table] += 1;
-        // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
-        // KNOWLEDGE.md backfill. Until that path ships, this check returns
-        // false for every row, which is the honest state of the consolidation.
-        if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+        // KNOWLEDGE.md backfill writes `sourceKnowledgeId`; rows without that
+        // marker are still reported as consolidation gaps.
+        if (memorySourceMarkers.knowledgeIds.has(row.id)) {
             knowledgeMigrated += 1;
             continue;
         }

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/migration-auto-check.js

@@ -45,6 +45,27 @@ function scanHasExtraIdentities(a, b) {
         hasExtra(a.slices, b.slices) ||
         hasExtra(a.tasks, b.tasks));
 }
+function paddedMilestoneId(id) {
+    return /^\d+$/.test(id) ? `M${id.padStart(3, "0")}` : null;
+}
+function replaceSetPrefix(values, from, to) {
+    for (const value of [...values]) {
+        if (value !== from && !value.startsWith(`${from}/`))
+            continue;
+        values.delete(value);
+        values.add(`${to}${value.slice(from.length)}`);
+    }
+}
+function alignNumericMarkdownIdsWithDb(markdownScan, dbScan) {
+    for (const dbId of dbScan.milestones) {
+        const paddedId = paddedMilestoneId(dbId);
+        if (!paddedId || dbScan.milestones.has(paddedId) || !markdownScan.milestones.has(paddedId))
+            continue;
+        replaceSetPrefix(markdownScan.milestones, paddedId, dbId);
+        replaceSetPrefix(markdownScan.slices, paddedId, dbId);
+        replaceSetPrefix(markdownScan.tasks, paddedId, dbId);
+    }
+}
 /**
  * True when the DB holds any milestone/slice/task identity the markdown lacks —
  * i.e. a `/gsd recover --confirm` (markdown → DB) would DELETE authoritative DB
@@ -126,6 +147,7 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
     refreshWorkflowDatabaseFromDisk();
     const dbScan = scanDbHierarchy();
     const beforeDb = dbScan.counts;
+    alignNumericMarkdownIdsWithDb(markdownScan, dbScan);
     // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
     // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
     // queued DB row is inserted only at discussion handoff). Treating it as

package/dist/resources/extensions/gsd/milestone-ids.js

@@ -123,7 +123,8 @@ export function clearReservedMilestoneIds() {
     reservedMilestoneIds.clear();
 }
 // ─── Discovery ──────────────────────────────────────────────────────────────
-function scanMilestoneIdsFromDir(dir) {
+function scanMilestoneIdsFromDir(basePath, dir) {
+    const legacyNumericIds = idsWithLegacyNumericDirs(basePath);
     return readdirSync(dir, { withFileTypes: true })
         .filter((d) => d.isDirectory())
         .map((d) => {
@@ -131,6 +132,12 @@ function scanMilestoneIdsFromDir(dir) {
         if (MILESTONE_ID_RE.test(d.name)) {
             return d.name;
         }
+        // Legacy recovery/imports may contain bare numeric milestone directories
+        // (for example `milestones/15/15-ROADMAP.md`). The DB can preserve that
+        // id, and rebuild renders it, so drift scans must see it too.
+        if (/^\d+$/.test(d.name)) {
+            return d.name;
+        }
         // Legacy layout: M001-abcdef-slug descriptor directories
         const legacyMatch = d.name.match(/^(M\d{3}(?:-[a-z0-9]{6})?)-/);
         if (legacyMatch) {
@@ -144,12 +151,35 @@ function scanMilestoneIdsFromDir(dir) {
             if (MILESTONE_ID_RE.test(fromSlug)) {
                 return fromSlug;
             }
+            const numericId = String(phaseNum);
+            if (legacyNumericIds.has(numericId)) {
+                return numericId;
+            }
             return `M${String(phaseNum).padStart(3, "0")}`;
         }
         return null;
     })
         .filter((id) => id !== null);
 }
+function idsWithLegacyNumericDirs(basePath) {
+    const legacyDir = join(gsdProjectionRoot(basePath), "milestones");
+    const ids = new Set();
+    try {
+        for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && /^\d+$/.test(entry.name))
+                ids.add(entry.name);
+        }
+    }
+    catch (err) {
+        // A missing legacy directory is the common, benign case (nothing to
+        // consult). Only surface a real failure when the directory exists but
+        // could not be read.
+        if (existsSync(legacyDir)) {
+            logWarning("engine", `idsWithLegacyNumericDirs: ${legacyDir} exists but readdirSync failed — ${getErrorMessage(err)}`);
+        }
+    }
+    return ids;
+}
 /** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
 export function findMilestoneIds(basePath) {
     const root = gsdProjectionRoot(basePath);
@@ -163,7 +193,7 @@ export function findMilestoneIds(basePath) {
     const ids = new Set();
     for (const dir of dirs) {
         try {
-            for (const id of scanMilestoneIdsFromDir(dir))
+            for (const id of scanMilestoneIdsFromDir(basePath, dir))
                 ids.add(id);
         }
         catch (err) {

package/dist/resources/extensions/gsd/milestone-implementation-evidence.js

@@ -10,6 +10,8 @@ import { logWarning } from "./workflow-logger.js";
 import { resolveTasksDir } from "./paths.js";
 /** Large enough for unbounded milestone-history git log scans in big repos. */
 const GIT_LOG_MAX_BUFFER = 16 * 1024 * 1024;
+const LOG_FIELD_SEPARATOR = "\x1f";
+const LOG_RECORD_SEPARATOR = "\x1e";
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
  * files) in git history. The primary signal is the branch diff against the
@@ -179,7 +181,7 @@ function getChangedFilesFromMilestoneTaggedCommits(basePath, milestoneId) {
     // Primary: path-scoped log against .gsd/milestones/<id>. Fast and unbounded
     // by depth when .gsd/ is tracked in git.
     const scoped = scanGsdTaggedCommits(basePath, milestoneId, [
-        "log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
+        "log", "--full-diff", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
     ]);
     if (!scoped.ok)
         return scoped;
@@ -195,7 +197,7 @@ function getChangedFilesFromMilestoneTaggedCommits(basePath, milestoneId) {
     // reintroducing the rolling-depth failure class removed in #4699 where
     // milestone evidence aged out behind unrelated activity.
     const unscoped = scanGsdTaggedCommits(basePath, milestoneId, [
-        "log", "--format=%H%x1f%B%x1e", "HEAD",
+        "log", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD",
     ]);
     if (!unscoped.ok)
         return scoped.matched ? scoped : unscoped;
@@ -280,8 +282,7 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(basePath, milestoneId)
                 continue;
             if (commitMessageHasGsdTrailer(record.message))
                 continue;
-            const commitFiles = getChangedFilesForCommit(basePath, record.hash);
-            const implementationFiles = commitFiles.map(normalizeRepoPath).filter(isImplementationPath);
+            const implementationFiles = record.files.map(normalizeRepoPath).filter(isImplementationPath);
             if (implementationFiles.length === 0)
                 continue;
             if (!implementationFiles.some((file) => hintSet.has(file)))
@@ -306,24 +307,28 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(basePath, milestoneId)
     }
 }
 function getCommitRecords(basePath) {
-    const logOutput = execFileSync("git", ["log", "--format=%H%x1f%P%x1f%cI%x1f%B%x1e", "HEAD"], {
+    const logOutput = execFileSync("git", ["log", "--name-only", "--format=%x1e%H%x1f%P%x1f%cI%x1f%B%x1f", "HEAD"], {
         cwd: basePath,
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf-8",
         maxBuffer: GIT_LOG_MAX_BUFFER,
     });
     return logOutput
-        .split("\x1e")
-        .map((record) => record.trim())
+        .split(LOG_RECORD_SEPARATOR)
         .filter(Boolean)
         .flatMap((record) => {
-        const parts = record.split("\x1f");
-        if (parts.length < 4)
+        const parts = record.split(LOG_FIELD_SEPARATOR);
+        if (parts.length < 5)
             return [];
-        const [hash, parents, committedAt, ...messageParts] = parts;
-        return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message: messageParts.join("\x1f") }];
+        const [hash, parents, committedAt] = parts;
+        const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+        const message = parts.slice(3, -1).join(LOG_FIELD_SEPARATOR);
+        return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message, files }];
     });
 }
+function parseNameOnlyFiles(rawFiles) {
+    return rawFiles.split(/\r?\n/).map((file) => file.trim()).filter(Boolean);
+}
 function isFullCommitSha(value) {
     return /^[0-9a-f]{40}$/i.test(value);
 }
@@ -336,23 +341,24 @@ function scanGsdTaggedCommits(basePath, milestoneId, gitArgs) {
             maxBuffer: GIT_LOG_MAX_BUFFER,
         });
         const records = logOutput
-            .split("\x1e")
-            .map((record) => record.trim())
+            .split(LOG_RECORD_SEPARATOR)
             .filter(Boolean)
             .flatMap((record) => {
-            const sep = record.indexOf("\x1f");
-            if (sep === -1)
+            const parts = record.split(LOG_FIELD_SEPARATOR);
+            if (parts.length < 3)
+                return [];
+            const hash = parts[0].trim();
+            if (!hash)
                 return [];
-            const hash = record.slice(0, sep).trim();
-            const message = record.slice(sep + 1);
-            return [{ hash, message }];
+            const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+            const message = parts.slice(1, -1).join(LOG_FIELD_SEPARATOR);
+            return [{ message, files }];
         });
         const files = new Set();
         let matched = false;
-        for (const { hash, message } of records) {
+        for (const { message, files: commitFiles } of records) {
             if (!commitMessageHasGsdTrailer(message))
                 continue;
-            const commitFiles = getChangedFilesForCommit(basePath, hash);
             if (!commitMatchesMilestone(basePath, message, milestoneId, commitFiles))
                 continue;
             matched = true;

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/code-review.md

@@ -16,18 +16,20 @@ You are running the GSD **code-review** workflow — review source files changed
 
 1. **Determine the file set.** Use the explicit `--files` list if provided. Otherwise derive the changed source files from the active slice's recent commits / SUMMARY, or fall back to the git diff against the base branch. Exclude `.gsd/`, lockfiles, generated/vendored code, and docs unless `--files` names them.
 
-2. **Review each file** at the requested depth:
+2. **Gather diff-first context.** Run `git diff` for the file set (or the relevant commit range) and use that as the primary review evidence. Use `read` only when the diff is insufficient — new/untracked files, truncated hunks, or missing surrounding context needed for a finding. Do **not** read every changed file when the diff already covers the edits. If the Tool Call Loop Guard blocks a tool, stop calling tools for the rest of this turn and continue in text.
+
+3. **Review at the requested depth:**
    - **quick** — bugs, security, and correctness only.
    - **standard** (default) — quick + maintainability, error handling, edge cases.
    - **deep** — standard + performance, concurrency, API design, test coverage gaps.
 
    Ground every finding in the actual code with file path + line reference. Categorize each by severity (critical / warning / nit) and type (bug, security, quality, performance).
 
-3. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
+4. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
 
-4. **Present results.** Summarize counts by severity and list the critical findings first.
+5. **Present results.** Summarize counts by severity and list the critical findings first.
 
-5. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
+6. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
 
 ## Success criteria
 

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/quick.js

@@ -8,8 +8,8 @@
  * Quick tasks live in `.gsd/quick/` and are tracked in STATE.md's
  * "Quick Tasks Completed" table.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -19,6 +19,7 @@ import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat } from ".
 import { nativeHasStagedChanges } from "./native-git-bridge.js";
 import { resolveUokFlags } from "./uok/flags.js";
 let pendingQuickReturn = null;
+const pendingQuickReturnMisses = new Map();
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from a description.
@@ -169,11 +170,36 @@ export function buildQuickCommitInstruction(basePath, root) {
         "   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.",
     ].join("\n");
 }
+function readHeadBranchName(basePath) {
+    try {
+        const gitPath = join(basePath, ".git");
+        if (!existsSync(gitPath))
+            return null;
+        let headPath;
+        if (lstatSync(gitPath).isDirectory()) {
+            headPath = join(gitPath, "HEAD");
+        }
+        else {
+            const gitFile = readFileSync(gitPath, "utf-8").trim();
+            if (!gitFile.startsWith("gitdir: "))
+                return null;
+            headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+        }
+        const head = readFileSync(headPath, "utf-8").trim();
+        if (!head.startsWith("ref: refs/heads/"))
+            return null;
+        return head.slice("ref: refs/heads/".length);
+    }
+    catch {
+        return null;
+    }
+}
 function quickReturnStatePath(basePath) {
     return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 function persistPendingReturn(state) {
     pendingQuickReturn = state;
+    pendingQuickReturnMisses.delete(state.basePath);
     mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
     writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -181,6 +207,13 @@ function readPendingReturn(basePath) {
     if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
         return pendingQuickReturn;
     }
+    if (pendingQuickReturnMisses.has(basePath)) {
+        const statePath = quickReturnStatePath(basePath);
+        if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+            return null;
+        }
+        pendingQuickReturnMisses.delete(basePath);
+    }
     try {
         const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
         const parsed = JSON.parse(raw);
@@ -191,6 +224,7 @@ function readPendingReturn(basePath) {
             && typeof parsed.slug === "string"
             && typeof parsed.description === "string") {
             pendingQuickReturn = parsed;
+            pendingQuickReturnMisses.delete(basePath);
             return pendingQuickReturn;
         }
     }
@@ -200,14 +234,23 @@ function readPendingReturn(basePath) {
     const inferred = inferQuickReturnFromBranch(basePath);
     if (inferred) {
         pendingQuickReturn = inferred;
+        pendingQuickReturnMisses.delete(basePath);
         return inferred;
     }
+    const branchAtMiss = readHeadBranchName(basePath);
+    if (branchAtMiss) {
+        pendingQuickReturnMisses.set(basePath, branchAtMiss);
+    }
     return null;
 }
 function clearPendingReturn(basePath) {
     if (pendingQuickReturn?.basePath === basePath) {
         pendingQuickReturn = null;
     }
+    const branchAtMiss = readHeadBranchName(basePath);
+    if (branchAtMiss) {
+        pendingQuickReturnMisses.set(basePath, branchAtMiss);
+    }
     rmSync(quickReturnStatePath(basePath), { force: true });
 }
 function hasStagedChanges(basePath) {

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).