@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

package/dist/resources/extensions/gsd/branch-patterns.js

@@ -11,3 +11,5 @@ export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6
 export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 /** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
 export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;
+/** Auto-mode milestone branch prefix: milestone/<MID>. */
+export const MILESTONE_BRANCH_PREFIX = "milestone/";

package/dist/resources/extensions/gsd/browser-daemon-auto-prep.js

@@ -0,0 +1,83 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution, resolveBrowserEngineResolution, } from "../browser-tools/engine/selection.js";
+import { resolveGsdBrowserCliAvailability, resolveGsdBrowserDaemonStartInvocation, } from "../shared/gsd-browser-cli.js";
+import { uatTypeIncludesBrowser } from "./uat-policy.js";
+const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+function isEnvDisabled(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "0" || normalized === "false" || normalized === "off";
+}
+function isWarmUpDisabled(env = process.env) {
+    const value = env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
+    return value === "0" || value === "false" || value === "off";
+}
+/** Active engine for warm-up: explicit env override, else session-committed ambient resolution. */
+function resolveActiveBrowserEngine(projectRoot, env) {
+    if (env.GSD_BROWSER_ENGINE?.trim()) {
+        return resolveBrowserEngineResolution(env, projectRoot).engine;
+    }
+    return resolveAmbientBrowserEngineResolution(projectRoot).engine;
+}
+export function shouldWarmBrowserDaemonForUat(ctx) {
+    if (!uatTypeIncludesBrowser(ctx.uatType))
+        return false;
+    const env = ctx.env ?? process.env;
+    if (isWarmUpDisabled(env))
+        return false;
+    if (isEnvDisabled(env.GSD_BROWSER_MCP_ENABLED))
+        return false;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available)
+        return false;
+    const projectRoot = resolve(ctx.projectRoot);
+    return resolveActiveBrowserEngine(projectRoot, env) === "gsd-browser";
+}
+export function ensureBrowserDaemonStarted(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available) {
+        return { ok: false, error: availability.detail };
+    }
+    let invocation;
+    try {
+        invocation = resolveGsdBrowserDaemonStartInvocation(projectRoot, env);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        execFileSync(invocation.command, invocation.args, {
+            cwd: invocation.cwd,
+            env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: options.timeoutMs ?? DEFAULT_DAEMON_START_TIMEOUT_MS,
+            encoding: "utf-8",
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Best-effort pre-warm of the gsd-browser session daemon before browser-backed
+ * run-uat dispatch. Returns an actionable stop reason when warm-up is required
+ * but fails; returns null when warm-up is skipped or succeeds.
+ */
+export function prepareBrowserDaemonForUat(ctx) {
+    if (!shouldWarmBrowserDaemonForUat(ctx))
+        return null;
+    const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
+    if (result.ok)
+        return null;
+    return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
+}

package/dist/resources/extensions/gsd/browser-evidence.js

@@ -1,8 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
-export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
+import { BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES } from "../shared/browser-contract.js";
+// Alternation fragment over the contract's evidence-signal names, e.g.
+// `browser_(?:assert|batch|...)`. The names are `browser_`-prefixed
+// identifiers (pinned by tests/browser-contract.test.ts), so no escaping is
+// needed.
+const BROWSER_TOOL_SIGNAL = `browser_(?:${BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES.map((name) => name.slice("browser_".length)).join("|")})`;
+export const BROWSER_REQUIREMENT_RE = new RegExp(String.raw `\b(?:file://|localhost|playwright|chrome|screenshot|snapshot|${BROWSER_TOOL_SIGNAL})\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file://)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b`, "i");
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
-export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
+export const BROWSER_RUNTIME_RE = new RegExp(String.raw `\b(?:browser|playwright|chrome|camoufox|${BROWSER_TOOL_SIGNAL}|screenshot|snapshot|file://|localhost)\b`, "i");
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
 const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;

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

@@ -8,9 +8,10 @@
  * `.gsd/CAPTURES.md`, not the worktree's local `.gsd/`.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CAPTURES_FILENAME = "CAPTURES.md";
 const VALID_CLASSIFICATIONS = [
@@ -29,20 +30,9 @@ const VALID_CLASSIFICATIONS = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath) {
-    const resolved = resolve(basePath);
-    // Direct layout: /.gsd/worktrees/
-    const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-    let idx = resolved.indexOf(worktreeMarker);
-    if (idx === -1) {
-        // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-        const symlinkRe = new RegExp(`\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`);
-        const match = resolved.match(symlinkRe);
-        if (match && match.index !== undefined)
-            idx = match.index;
-    }
-    if (idx !== -1) {
-        // basePath is inside a worktree — resolve to project root
-        const projectRoot = resolved.slice(0, idx);
+    // If basePath is inside a worktree, resolve to the project root.
+    const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+    if (projectRoot) {
         return join(projectRoot, ".gsd", CAPTURES_FILENAME);
     }
     return join(gsdRoot(basePath), CAPTURES_FILENAME);

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

@@ -1,7 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
-import { getDbPath, getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, isDbAvailable, refreshOpenDatabaseFromDisk, } from "./gsd-db.js";
+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 { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
+import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
+import { relMilestoneFile, resolveSliceFile } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
 export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
 function blocked(reason, message) {
     return {
@@ -14,30 +21,128 @@ function blocked(reason, message) {
 function isFileBackedDbPath(path) {
     return Boolean(path && path !== ":memory:");
 }
+function artifactBasePathFromDb() {
+    const dbPath = getWorkflowDatabasePath();
+    if (!isFileBackedDbPath(dbPath))
+        return undefined;
+    return dirname(dirname(dbPath));
+}
+function allSlicesHaveCloseoutSummaryEvidence(milestoneId, artifactBasePath) {
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0)
+        return false;
+    return slices.every((slice) => {
+        if (!isClosedStatus(slice.status))
+            return false;
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+            if (!isClosedStatus(task.status))
+                return false;
+        }
+        const summaryPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "SUMMARY");
+        return Boolean(summaryPath && existsSync(summaryPath));
+    });
+}
+function renderCloseoutPassThroughValidation(milestoneId) {
+    return [
+        "---",
+        "verdict: pass",
+        "skip_validation: true",
+        "skip_validation_reason: closeout-recovery",
+        "remediation_round: 0",
+        "---",
+        "",
+        "# Milestone Validation (skipped)",
+        "",
+        `Milestone validation was recorded during closeout for ${milestoneId} because all slices already had SUMMARY evidence and no milestone-validation assessment was present.`,
+        "",
+    ].join("\n");
+}
+function recordCloseoutPassThroughValidationIfReady(milestoneId, artifactBasePath) {
+    const basePath = artifactBasePath ?? artifactBasePathFromDb();
+    if (!basePath)
+        return false;
+    const existing = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (existing?.status === "pass")
+        return true;
+    if (existing)
+        return false;
+    if (!allSlicesHaveCloseoutSummaryEvidence(milestoneId, basePath))
+        return false;
+    const validationPath = join(basePath, relMilestoneFile(basePath, milestoneId, "VALIDATION"));
+    const content = renderCloseoutPassThroughValidation(milestoneId);
+    mkdirSync(dirname(validationPath), { recursive: true });
+    writeFileSync(validationPath, content, "utf-8");
+    try {
+        transaction(() => {
+            insertAssessment({
+                path: validationPath,
+                milestoneId,
+                sliceId: null,
+                taskId: null,
+                status: "pass",
+                scope: "milestone-validation",
+                fullContent: content,
+            });
+            const gateSliceId = getMilestoneSlices(milestoneId)[0]?.id;
+            if (gateSliceId) {
+                insertMilestoneValidationGates(milestoneId, gateSliceId, "pass", new Date().toISOString());
+            }
+        });
+    }
+    catch (err) {
+        try {
+            unlinkSync(validationPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw err;
+    }
+    invalidateAllCaches();
+    return true;
+}
 export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
     if (!isDbAvailable()) {
         return blocked("db-unavailable", `Closeout consistency blocked for ${milestoneId}: canonical DB is unavailable.`);
     }
-    if (options.refreshFromDisk && isFileBackedDbPath(getDbPath()) && !refreshOpenDatabaseFromDisk()) {
+    if (options.refreshFromDisk && isFileBackedDbPath(getWorkflowDatabasePath()) && !refreshWorkflowDatabaseFromDisk()) {
         return blocked("db-refresh-failed", `Closeout consistency blocked for ${milestoneId}: canonical DB refresh failed.`);
     }
     const milestone = getMilestone(milestoneId);
     if (!milestone) {
         return blocked("milestone-missing", `Closeout consistency blocked for ${milestoneId}: milestone is missing from canonical DB.`);
     }
-    if (!isClosedStatus(milestone.status)) {
+    if (!isClosedStatus(milestone.status) && !options.allowOpenMilestone) {
         return blocked("milestone-open", `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`);
     }
+    let validation = milestone.status === "skipped"
+        ? null
+        : getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (milestone.status !== "skipped" &&
+        validation?.status !== "pass" &&
+        options.allowPassThroughValidation &&
+        recordCloseoutPassThroughValidationIfReady(milestoneId, options.artifactBasePath ?? artifactBasePathFromDb())) {
+        validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    }
     if (milestone.status !== "skipped") {
-        const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
         if (validation?.status !== "pass") {
-            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`);
+            const validationStatus = validation?.status ?? "absent";
+            const recovery = validationStatus === "absent"
+                ? ` Run \`/gsd validate-milestone ${milestoneId}\` to create the validation, or set \`phases.skip_milestone_validation: true\` in .gsd/PREFERENCES.md to skip it.`
+                : "";
+            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validationStatus}".${recovery}`);
         }
     }
     const slices = getMilestoneSlices(milestoneId);
     if (slices.length === 0 && milestone.status !== "skipped") {
         return blocked("slice-missing", `Closeout consistency blocked for ${milestoneId}: no slices exist in canonical DB.`);
     }
+    if (milestone.status !== "skipped") {
+        closeQualityGatesFromEvidence(milestoneId, {
+            artifactBasePath: options.artifactBasePath ?? artifactBasePathFromDb(),
+            milestoneValidationPassed: validation?.status === "pass",
+        });
+    }
     for (const slice of slices) {
         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/closeout-recovery.js

@@ -2,12 +2,13 @@
 // File Purpose: Closeout git failure discovery, retry, and manual resolution helpers.
 import { execFileSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { runTurnGitAction } from "./git-service.js";
 import { _getAdapter, upsertTurnGitTransaction } from "./gsd-db.js";
 import { probeGitConflictState } from "./git-conflict-state.js";
 import { parseUnitId } from "./unit-id.js";
+import { worktreePathFor } from "./worktree-placement.js";
 function parseMetadata(value) {
     if (typeof value !== "string" || !value.trim())
         return {};
@@ -121,7 +122,7 @@ export function resolveCloseoutRecoveryBasePath(projectRoot, record) {
     const parsed = parseUnitId(record.unitId);
     const milestoneId = parsed.milestone ?? (/^M\d+(?:-[a-z0-9]{6})?/.exec(record.unitId)?.[0] ?? "");
     if (milestoneId) {
-        const worktreePath = existingRealPath(join(projectRoot, ".gsd", "worktrees", milestoneId));
+        const worktreePath = existingRealPath(worktreePathFor(projectRoot, milestoneId));
         if (worktreePath)
             return worktreePath;
     }

package/dist/resources/extensions/gsd/closeout-wizard.js

@@ -1,22 +1,112 @@
 // Project/App: gsd-pi
 // File Purpose: Shared closeout detection and merge actions for /gsd home and smart entry.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { setAutoOutcomeWidget } from "./auto-dashboard.js";
 import { invalidateAllCaches } from "./cache.js";
+import { isDbAvailable } from "./db/engine.js";
+import { getMilestone } from "./db/queries.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { mergeCompletedMilestone } from "./parallel-merge.js";
 import { cleanupQuickBranch, detectStrandedQuickBranch } from "./quick.js";
+import { isClosedStatus } from "./status-guards.js";
 import { findUnmergedCompletedMilestones, } from "./unmerged-milestone-guard.js";
 import { appendRequirementsBacklogToSummary } from "./requirements-backlog.js";
+import { nativeBranchList, nativeIsRepo } from "./native-git-bridge.js";
+import { allWorktreesDirs, isMilestoneWorktreeResidueCandidate, pruneEphemeralGhostWorktreeDirectories, } from "./worktree-manager.js";
 const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
     "/gsd status for overview",
     "/gsd visualize to inspect",
     "/gsd notifications for history",
     "/gsd start for new work",
 ];
+function listMilestoneWorktreeIds(basePath) {
+    const ids = new Set();
+    for (const wtDir of allWorktreesDirs(basePath)) {
+        if (!existsSync(wtDir))
+            continue;
+        for (const entry of readdirSync(wtDir)) {
+            if (!MILESTONE_ID_RE.test(entry))
+                continue;
+            const fullPath = join(wtDir, entry);
+            try {
+                if (!statSync(fullPath).isDirectory())
+                    continue;
+                if (!isMilestoneWorktreeResidueCandidate(basePath, fullPath))
+                    continue;
+                ids.add(entry);
+            }
+            catch {
+                // skip unreadable entries
+            }
+        }
+    }
+    return [...ids].sort();
+}
+function listMilestoneBranchIds(basePath) {
+    try {
+        return nativeBranchList(basePath, "milestone/*")
+            .map((branch) => branch.replace(/^milestone\//, ""))
+            .filter((id) => MILESTONE_ID_RE.test(id))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A milestone ID is "stranded residue" only when its worktree/branch artifacts
+ * exist for a milestone the DB does not consider currently in flight — i.e. the
+ * row is closed (complete/done/skipped/closed) or absent. Active, pending,
+ * blocked, parked, queued, and deferred rows describe normal in-flight or
+ * intentionally-preserved state, never residue. Returning `false` skips the ID;
+ * returning `true` keeps it in the hint.
+ */
+function isStrandedMilestoneId(milestoneId) {
+    if (!isDbAvailable())
+        return true;
+    const row = getMilestone(milestoneId);
+    if (!row)
+        return true;
+    return isClosedStatus(row.status);
+}
+/** Surface stranded milestone git residue when closeout guards did not classify it. */
+export function detectIdleMilestoneResidueHint(basePath) {
+    if (!nativeIsRepo(basePath))
+        return null;
+    pruneEphemeralGhostWorktreeDirectories(basePath);
+    const gsdDir = join(basePath, ".gsd");
+    const dbPath = join(gsdDir, "gsd.db");
+    if (!existsSync(gsdDir) || !existsSync(dbPath)) {
+        return {
+            milestoneIds: [],
+            message: "This git repo has no local GSD workflow database (.gsd/gsd.db). " +
+                "Workflow state may live in an external worktree, or run /gsd new-project to initialize here.",
+        };
+    }
+    const worktreeIds = listMilestoneWorktreeIds(basePath);
+    const branchIds = listMilestoneBranchIds(basePath);
+    const candidateIds = [...new Set([...worktreeIds, ...branchIds])].sort();
+    const milestoneIds = candidateIds.filter(isStrandedMilestoneId);
+    if (milestoneIds.length === 0)
+        return null;
+    const listed = milestoneIds.join(", ");
+    const recovery = milestoneIds.length === 1
+        ? `/gsd dispatch complete-milestone ${milestoneIds[0]}`
+        : "/gsd doctor --fix";
+    return {
+        milestoneIds,
+        message: `Stranded milestone git residue detected (${listed}: worktree dir and/or milestone/* branch). ` +
+            `Run ${recovery} or /gsd status to recover closeout before starting new work.`,
+    };
+}
 export async function loadCloseoutContext(basePath) {
     const unmergedMilestones = await findUnmergedCompletedMilestones(basePath);
+    const idleResidueHint = unmergedMilestones.length === 0 ? detectIdleMilestoneResidueHint(basePath) : null;
     return {
         strandedQuick: detectStrandedQuickBranch(basePath),
         unmergedMilestones,
+        idleResidueHint,
     };
 }
 export function getPrimaryCloseoutRecommendation(closeout) {
@@ -62,6 +152,13 @@ export function buildIdleMenuSummary(state, closeout) {
             `${blocker.milestoneId} is complete but not merged into ${blocker.integrationBranch}.`,
         ];
     }
+    // Surface idle residue before the completion summary so smart entry shows
+    // the same recovery text /gsd home would: a closed/unknown milestone with
+    // lingering worktree/branch artifacts must not be hidden behind the
+    // "all milestones complete" message.
+    if (closeout.idleResidueHint) {
+        return [closeout.idleResidueHint.message];
+    }
     if (state.phase === "complete") {
         const last = state.lastCompletedMilestone;
         return appendRequirementsBacklogToSummary(state, [

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -330,6 +330,7 @@ export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
     const force = ensureOptions?.force === true;
     const now = Date.now();
+    // TTL short-circuit: avoid spawning git on the per-turn freshness path.
     if (!force && ttlMs > 0) {
         const cached = freshnessCache.get(cacheKey);
         if (cached && now - cached.checkedAt < ttlMs) {

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -1,8 +1,11 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
+import { GSD_CORE_ALIAS_CATALOG } from "./gsd-core-aliases.js";
+import { GSD_CORE_IMPLEMENTED_CATALOG } from "../commands-gsd-core.js";
 export const GSD_COMMAND_DESCRIPTION = "GSD — Git Ship Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|report|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|closeout|rebuild|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|memory|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|upgrade|fast|mcp|rethink|workflow|codebase|notifications|ship|do|usage|context|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -83,6 +86,10 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
     { cmd: "worktree", desc: "Manage worktrees from the TUI (list, merge, clean, remove)" },
     { cmd: "eval-review", desc: "Audit a slice's AI evaluation strategy and write a scored EVAL-REVIEW.md (--force, --show)" },
+    // Additional commands (commands-gsd-core.ts) run real prompt-driven workflows;
+    // namespace aliases (gsd-core-aliases.ts) redirect to /gsd help.
+    ...GSD_CORE_IMPLEMENTED_CATALOG,
+    ...GSD_CORE_ALIAS_CATALOG,
 ];
 const NESTED_COMPLETIONS = {
     brief: VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
@@ -380,70 +387,13 @@ function getExtensionCompletions(prefix, action) {
         return [];
     }
 }
-function normalizePathForCompare(path) {
-    return path.replaceAll("\\", "/").replace(/\/+$/, "");
-}
-function findWorktreeSegment(normalizedPath) {
-    const directMarker = "/.gsd/worktrees/";
-    const directIdx = normalizedPath.indexOf(directMarker);
-    if (directIdx !== -1) {
-        return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
-    }
-    const symlinkMatch = normalizedPath.match(/\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//);
-    if (symlinkMatch?.index !== undefined) {
-        return { gsdIdx: symlinkMatch.index, afterWorktrees: symlinkMatch.index + symlinkMatch[0].length };
-    }
-    return null;
-}
-function resolveProjectRootFromGitFile(worktreePath) {
-    try {
-        let dir = worktreePath;
-        for (let i = 0; i < 30; i++) {
-            const gitPath = join(dir, ".git");
-            if (existsSync(gitPath)) {
-                const content = readFileSync(gitPath, "utf8").trim();
-                if (content.startsWith("gitdir: ")) {
-                    const gitDir = resolve(dir, content.slice(8));
-                    const dotGitDir = resolve(gitDir, "..", "..");
-                    if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
-                        return resolve(dotGitDir, "..");
-                    }
-                    const commonDirPath = join(gitDir, "commondir");
-                    if (existsSync(commonDirPath)) {
-                        const commonDir = readFileSync(commonDirPath, "utf8").trim();
-                        return resolve(resolve(gitDir, commonDir), "..");
-                    }
-                }
-                break;
-            }
-            const parent = resolve(dir, "..");
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    catch {
-        // Completion must stay best-effort.
-    }
-    return null;
-}
 function resolveProjectRootForCompletion(basePath) {
+    // Completion honors GSD_PROJECT_ROOT unconditionally (worker processes may
+    // complete from any cwd); resolveWorktreeProjectRoot only honors it for
+    // worktree paths.
     if (process.env.GSD_PROJECT_ROOT)
         return process.env.GSD_PROJECT_ROOT;
-    const normalizedPath = normalizePathForCompare(basePath);
-    const segment = findWorktreeSegment(normalizedPath);
-    if (!segment)
-        return basePath;
-    const separator = basePath.includes("\\") ? "\\" : "/";
-    const gsdMarker = `${separator}.gsd${separator}`;
-    const gsdIdx = basePath.indexOf(gsdMarker);
-    const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
-    const normalizedGsdHome = normalizePathForCompare(gsdHome());
-    const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
-    if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
-        return resolveProjectRootFromGitFile(basePath) ?? basePath;
-    }
-    return candidate;
+    return resolveWorktreeProjectRoot(basePath);
 }
 export function getGsdArgumentCompletions(prefix) {
     const hasTrailingSpace = prefix.endsWith(" ");

package/dist/resources/extensions/gsd/commands/context.js

@@ -1,4 +1,4 @@
-import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
+import { checkRemoteAutoSession, forceStopAutoRemote, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
 import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
@@ -135,5 +135,19 @@ export async function guardRemoteSession(ctx, pi) {
         }
         return false;
     }
-    return choice === "force";
+    if (choice === "force") {
+        const result = forceStopAutoRemote(projectRoot());
+        if (result.error) {
+            ctx.ui.notify(`Failed to force-stop remote auto-mode: ${result.error}`, "error");
+            return false;
+        }
+        if (result.found) {
+            ctx.ui.notify(`Force-stopped auto-mode session (PID ${result.pid}). Starting a new session.`, "warning");
+        }
+        else {
+            ctx.ui.notify("Remote session is no longer running. Starting a new session.", "info");
+        }
+        return true;
+    }
+    return false;
 }

package/dist/resources/extensions/gsd/commands/dispatcher.js

@@ -6,6 +6,7 @@ import { handleCoreCommand } from "./handlers/core.js";
 import { handleOpsCommand } from "./handlers/ops.js";
 import { handleParallelCommand } from "./handlers/parallel.js";
 import { handleWorkflowCommand } from "./handlers/workflow.js";
+import { handleGsdCoreAlias } from "./gsd-core-aliases-handler.js";
 import { getValidationBlockMessageForBase, isValidationBlockAllowedCommand, } from "../validation-block-guard.js";
 import { getUnmergedMilestoneBlockMessageForBase, isUnmergedMilestoneAllowedCommand, } from "../unmerged-milestone-guard.js";
 import { getWorkspaceGitBlockMessageForBase } from "../workspace-git-guard.js";
@@ -24,6 +25,8 @@ function emitVisibleCommandBlock(ctx, pi, message) {
 export async function handleGSDCommand(args, ctx, pi) {
     const trimmed = (typeof args === "string" ? args : "").trim();
     const handlers = [
+        // Namespace alias redirects (ns-*) run first so they resolve before the standard handlers.
+        () => handleGsdCoreAlias(trimmed, ctx, pi),
         () => handleCoreCommand(trimmed, ctx, pi),
         () => handleAutoCommand(trimmed, ctx, pi),
         () => handleParallelCommand(trimmed, ctx, pi),

package/dist/resources/extensions/gsd/commands/gsd-core-aliases-handler.js

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Handler that resolves namespace alias redirects (ns-*).
+//
+// Returns true (handled) when the input matches a namespace alias. Redirects
+// re-dispatch through the main dispatcher so safety guards apply to the target
+// command too. Unavailable aliases print a helpful message and stop.
+import { matchGsdCoreAlias } from "./gsd-core-aliases.js";
+function formatUnavailable(cmd, alias) {
+    const lines = [
+        `/gsd ${cmd} is not available.`,
+        `Previously it: ${alias.legacy}`,
+    ];
+    if (alias.alternative)
+        lines.push(`Alternative: ${alias.alternative}`);
+    lines.push("Run /gsd help for the command reference.");
+    return lines.join("\n");
+}
+export async function handleGsdCoreAlias(trimmed, ctx, pi) {
+    const match = matchGsdCoreAlias(trimmed);
+    if (!match)
+        return false;
+    const { alias, cmd, rest } = match;
+    if (alias.kind === "unavailable") {
+        ctx.ui.notify(formatUnavailable(cmd, alias), "warning");
+        return true;
+    }
+    // Redirect: rebuild the target command with any trailing args, then re-dispatch
+    // through the main dispatcher so guards + handlers run against the target.
+    const targetWithArgs = rest ? `${alias.target} ${rest}` : alias.target;
+    if (alias.note) {
+        ctx.ui.notify(`${cmd} → /gsd ${alias.target} (${alias.note})`, "info");
+    }
+    else {
+        ctx.ui.notify(`${cmd} → /gsd ${alias.target}`, "info");
+    }
+    const { handleGSDCommand } = await import("./dispatcher.js");
+    await handleGSDCommand(targetWithArgs, ctx, pi);
+    return true;
+}