gsd-pi 2.38.0-dev.8f5c161 → 2.38.0-dev.98b44dc

package/README.md

@@ -24,21 +24,25 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.37
+## What's New in v2.38
 
-- **cmux integration** — sidebar status, progress bars, and notifications for [cmux](https://cmux.com) terminal multiplexer users
-- **Redesigned dashboard** — two-column layout with redesigned widget
-- **Search budget enforcement** — session-level search budget prevents unbounded native web search
+- **Reactive task execution (ADR-004)** — graph-derived parallel task dispatch within slices. When enabled, GSD derives a dependency graph from IO annotations in task plans and dispatches multiple non-conflicting tasks in parallel via subagents. Backward compatible — disabled by default. Enable with `reactive_execution: true` in preferences.
+- **Anthropic Vertex AI provider** — run Claude models (Opus 4.6, Sonnet 4.6, Haiku 4.5) through Google Vertex AI. Set `ANTHROPIC_VERTEX_PROJECT_ID` to activate.
+- **CI optimization** — GitHub Actions minutes reduced ~60-70% (~10k → ~3-4k/month)
+- **Reactive batch verification** — dependency-based carry-forward for verification results across parallel task batches
+- **Backtick file path enforcement** — task plan IO sections now require backtick-wrapped paths for reliable parsing
+
+See the full [Changelog](./CHANGELOG.md) for details.
+
+### Previous highlights (v2.34–v2.37)
+
+- **cmux integration** — sidebar status, progress bars, and notifications for cmux terminal multiplexer users
+- **Redesigned dashboard** — two-column layout with 4 widget modes (full → small → min → off)
 - **AGENTS.md support** — deprecated `agent-instructions.md` in favor of standard `AGENTS.md` / `CLAUDE.md`
 - **AI-powered triage** — automated issue and PR triage via Claude Haiku
-- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API for always-current model support
-- **Extension manifest system** — user-managed enable/disable for bundled extensions
-- **Pipeline simplification (ADR-003)** — merged research into planning, mechanical completion
-- **Workflow templates** — right-sized workflows for every task type
-- **Health widget** — always-on environment health checks with progress scoring
+- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API
 - **`/gsd changelog`** — LLM-summarized release notes for any version
-
-See the full [Changelog](./CHANGELOG.md) for details.
+- **Search budget enforcement** — session-level cap prevents unbounded web search
 
 ---
 

package/dist/resource-loader.js

@@ -1,7 +1,7 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -217,6 +217,35 @@ function copyDirRecursive(src, dest) {
         }
     }
 }
+/**
+ * Creates (or updates) a symlink at agentDir/node_modules pointing to GSD's
+ * own node_modules directory.
+ *
+ * Native ESM `import()` ignores NODE_PATH — it resolves packages by walking
+ * up the directory tree from the importing file. Extension files synced to
+ * ~/.gsd/agent/extensions/ have no ancestor node_modules, so imports of
+ * @gsd/* packages fail. The symlink makes Node's standard resolution find
+ * them without requiring every call site to use jiti.
+ */
+function ensureNodeModulesSymlink(agentDir) {
+    const agentNodeModules = join(agentDir, 'node_modules');
+    const gsdNodeModules = join(packageRoot, 'node_modules');
+    try {
+        const existing = readlinkSync(agentNodeModules);
+        if (existing === gsdNodeModules)
+            return; // already correct
+        unlinkSync(agentNodeModules);
+    }
+    catch {
+        // readlinkSync throws if path doesn't exist or isn't a symlink — both are fine
+    }
+    try {
+        symlinkSync(gsdNodeModules, agentNodeModules, 'junction');
+    }
+    catch {
+        // Non-fatal — worst case, extensions fall back to NODE_PATH via jiti
+    }
+}
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
@@ -262,6 +291,10 @@ export function initResources(agentDir) {
     // Ensure all newly copied files are owner-writable so the next run can
     // overwrite them (covers extensions, agents, and skills in one walk).
     makeTreeWritable(agentDir);
+    // Ensure ~/.gsd/agent/node_modules symlinks to GSD's node_modules so that
+    // native ESM import() calls from synced extension files can resolve @gsd/*
+    // packages via ancestor directory lookup. NODE_PATH only applies to CJS/jiti.
+    ensureNodeModulesSymlink(agentDir);
     writeManagedResourceManifest(agentDir);
     ensureRegistryEntries(join(agentDir, 'extensions'));
 }

package/dist/resources/extensions/browser-tools/index.js

@@ -4,7 +4,7 @@ let registrationPromise = null;
 async function registerBrowserTools(pi) {
     if (!registrationPromise) {
         registrationPromise = (async () => {
-            const [lifecycle, capture, settle, refs, utils, navigation, screenshot, interaction, inspection, session, assertions, refTools, wait, pages, forms, intent, pdf, statePersistence, networkMock, device, extract, visualDiff, zoom, codegen, actionCache, injectionDetection,] = await Promise.all([
+            const [lifecycle, capture, settle, refs, utils, navigation, screenshot, interaction, inspection, session, assertions, refTools, wait, pages, forms, intent, pdf, statePersistence, networkMock, device, extract, visualDiff, zoom, codegen, actionCache, injectionDetection, verify,] = await Promise.all([
                 importExtensionModule(import.meta.url, "./lifecycle.js"),
                 importExtensionModule(import.meta.url, "./capture.js"),
                 importExtensionModule(import.meta.url, "./settle.js"),
@@ -31,6 +31,7 @@ async function registerBrowserTools(pi) {
                 importExtensionModule(import.meta.url, "./tools/codegen.js"),
                 importExtensionModule(import.meta.url, "./tools/action-cache.js"),
                 importExtensionModule(import.meta.url, "./tools/injection-detect.js"),
+                importExtensionModule(import.meta.url, "./tools/verify.js"),
             ]);
             const deps = {
                 ensureBrowser: lifecycle.ensureBrowser,
@@ -99,6 +100,7 @@ async function registerBrowserTools(pi) {
             codegen.registerCodegenTools(pi, deps);
             actionCache.registerActionCacheTools(pi, deps);
             injectionDetection.registerInjectionDetectionTools(pi, deps);
+            verify.registerVerifyTools(pi, deps);
         })().catch((error) => {
             registrationPromise = null;
             throw error;

package/dist/resources/extensions/browser-tools/tools/verify.js

@@ -0,0 +1,97 @@
+import { Type } from "@sinclair/typebox";
+export function registerVerifyTools(pi, deps) {
+    pi.registerTool({
+        name: "browser_verify",
+        label: "Browser Verify",
+        description: "Run a structured browser verification flow: navigate to a URL, run checks (element visibility, text content), capture screenshots as evidence, and return structured pass/fail results.",
+        promptGuidelines: [
+            "Use browser_verify for UAT verification flows that need structured evidence.",
+            "Each check produces a pass/fail result with captured evidence.",
+            "Prefer this over manual navigation + assertion sequences for verification tasks.",
+        ],
+        parameters: Type.Object({
+            url: Type.String({ description: "URL to navigate to" }),
+            checks: Type.Array(Type.Object({
+                description: Type.String({ description: "What this check verifies" }),
+                selector: Type.Optional(Type.String({ description: "CSS selector to check" })),
+                expectedText: Type.Optional(Type.String({ description: "Expected text content" })),
+                expectedVisible: Type.Optional(Type.Boolean({ description: "Whether element should be visible" })),
+                screenshot: Type.Optional(Type.Boolean({ description: "Capture screenshot as evidence" })),
+            }), { description: "Verification checks to run" }),
+            timeout: Type.Optional(Type.Number({ description: "Navigation timeout in ms", default: 10000 })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const startTime = Date.now();
+            const { page } = await deps.ensureBrowser();
+            const timeout = params.timeout ?? 10000;
+            try {
+                await page.goto(params.url, { waitUntil: "domcontentloaded", timeout });
+            }
+            catch (navErr) {
+                const msg = navErr instanceof Error ? navErr.message : String(navErr);
+                return {
+                    content: [{ type: "text", text: `Navigation failed: ${msg}` }],
+                    details: {
+                        url: params.url,
+                        passed: false,
+                        checks: params.checks.map((c) => ({ description: c.description, passed: false, error: msg })),
+                        duration: Date.now() - startTime,
+                    },
+                };
+            }
+            const results = [];
+            for (const check of params.checks) {
+                try {
+                    let passed = true;
+                    let actual;
+                    let evidence;
+                    if (check.selector) {
+                        const element = await page.$(check.selector);
+                        if (check.expectedVisible !== undefined) {
+                            const isVisible = element ? await element.isVisible() : false;
+                            passed = isVisible === check.expectedVisible;
+                            actual = `visible=${isVisible}`;
+                        }
+                        if (check.expectedText !== undefined && element) {
+                            const text = await element.textContent();
+                            passed = passed && (text?.includes(check.expectedText) ?? false);
+                            actual = `text="${text?.slice(0, 200)}"`;
+                        }
+                        if (!element && (check.expectedVisible === true || check.expectedText)) {
+                            passed = false;
+                            actual = "element not found";
+                        }
+                    }
+                    if (check.screenshot) {
+                        try {
+                            const buf = await page.screenshot({ type: "png" });
+                            evidence = `screenshot captured (${buf.length} bytes)`;
+                        }
+                        catch {
+                            evidence = "screenshot failed";
+                        }
+                    }
+                    results.push({ description: check.description, passed, actual, evidence });
+                }
+                catch (checkErr) {
+                    results.push({
+                        description: check.description,
+                        passed: false,
+                        error: checkErr instanceof Error ? checkErr.message : String(checkErr),
+                    });
+                }
+            }
+            const allPassed = results.every((r) => r.passed);
+            const summary = results.map((r) => `${r.passed ? "PASS" : "FAIL"}: ${r.description}${r.actual ? ` (${r.actual})` : ""}${r.error ? ` — ${r.error}` : ""}`).join("\n");
+            return {
+                content: [{ type: "text", text: `Verification ${allPassed ? "PASSED" : "FAILED"} (${results.filter(r => r.passed).length}/${results.length})\n\n${summary}` }],
+                details: {
+                    url: params.url,
+                    passed: allPassed,
+                    checks: results,
+                    duration: Date.now() - startTime,
+                },
+            };
+        },
+    });
+}

package/dist/resources/extensions/github-sync/cli.js

@@ -0,0 +1,284 @@
+/**
+ * Thin wrapper around the `gh` CLI.
+ *
+ * Every public function returns `GhResult<T>` — never throws.
+ * Uses `execFileSync` (not `execSync`) for safety.
+ */
+import { execFileSync } from "node:child_process";
+function ok(data) {
+    return { ok: true, data };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+// ─── gh Availability ────────────────────────────────────────────────────────
+let _ghAvailable = null;
+export function ghIsAvailable() {
+    if (_ghAvailable !== null)
+        return _ghAvailable;
+    try {
+        execFileSync("gh", ["--version"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        });
+        _ghAvailable = true;
+    }
+    catch {
+        _ghAvailable = false;
+    }
+    return _ghAvailable;
+}
+/** Reset cached availability (for testing). */
+export function _resetGhCache() {
+    _ghAvailable = null;
+}
+// ─── Rate Limit Check ───────────────────────────────────────────────────────
+let _rateLimitCheckedAt = 0;
+let _rateLimitOk = true;
+const RATE_LIMIT_CHECK_INTERVAL_MS = 300_000; // 5 minutes
+export function ghHasRateLimit(cwd) {
+    const now = Date.now();
+    if (now - _rateLimitCheckedAt < RATE_LIMIT_CHECK_INTERVAL_MS)
+        return _rateLimitOk;
+    _rateLimitCheckedAt = now;
+    try {
+        const raw = execFileSync("gh", ["api", "rate_limit", "--jq", ".rate.remaining"], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+        }).trim();
+        const remaining = parseInt(raw, 10);
+        _rateLimitOk = Number.isFinite(remaining) && remaining >= 100;
+    }
+    catch {
+        // Can't check — assume OK so we don't silently disable sync
+        _rateLimitOk = true;
+    }
+    return _rateLimitOk;
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+const GH_TIMEOUT = 15_000;
+const MAX_BODY_LENGTH = 65_000;
+function truncateBody(body) {
+    if (body.length <= MAX_BODY_LENGTH)
+        return body;
+    return body.slice(0, MAX_BODY_LENGTH) + "\n\n---\n*Body truncated (exceeded 65K characters)*";
+}
+function runGh(args, cwd) {
+    try {
+        const stdout = execFileSync("gh", args, {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: GH_TIMEOUT,
+        }).trim();
+        return ok(stdout);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return fail(msg);
+    }
+}
+function runGhJson(args, cwd) {
+    const result = runGh(args, cwd);
+    if (!result.ok)
+        return fail(result.error);
+    try {
+        return ok(JSON.parse(result.data));
+    }
+    catch {
+        return fail(`Failed to parse JSON: ${result.data}`);
+    }
+}
+// ─── Repo Detection ─────────────────────────────────────────────────────────
+export function ghDetectRepo(cwd) {
+    const result = runGh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    const repo = result.data.trim();
+    if (!repo || !repo.includes("/"))
+        return fail("Could not detect repo");
+    return ok(repo);
+}
+export function ghCreateIssue(cwd, opts) {
+    const args = [
+        "issue", "create",
+        "--repo", opts.repo,
+        "--title", opts.title,
+        "--body", truncateBody(opts.body),
+    ];
+    if (opts.labels?.length) {
+        args.push("--label", opts.labels.join(","));
+    }
+    if (opts.milestone) {
+        args.push("--milestone", String(opts.milestone));
+    }
+    const result = runGh(args, cwd);
+    if (!result.ok)
+        return fail(result.error);
+    // gh issue create returns the URL; extract issue number
+    const match = result.data.match(/\/issues\/(\d+)/);
+    if (!match)
+        return fail(`Could not parse issue number from: ${result.data}`);
+    const issueNumber = parseInt(match[1], 10);
+    // If parent specified, add as sub-issue via GraphQL
+    if (opts.parentIssue) {
+        ghAddSubIssue(cwd, opts.repo, opts.parentIssue, issueNumber);
+    }
+    return ok(issueNumber);
+}
+export function ghCloseIssue(cwd, repo, issueNumber, comment) {
+    if (comment) {
+        ghAddComment(cwd, repo, issueNumber, comment);
+    }
+    const result = runGh(["issue", "close", String(issueNumber), "--repo", repo], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(undefined);
+}
+export function ghAddComment(cwd, repo, issueNumber, body) {
+    const result = runGh(["issue", "comment", String(issueNumber), "--repo", repo, "--body", truncateBody(body)], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(undefined);
+}
+// ─── Sub-Issues (GraphQL) ───────────────────────────────────────────────────
+function ghAddSubIssue(cwd, repo, parentNumber, childNumber) {
+    // Get node IDs for both issues
+    const parentResult = runGhJson(["api", `repos/${repo}/issues/${parentNumber}`, "--jq", "{id: .node_id}"], cwd);
+    const childResult = runGhJson(["api", `repos/${repo}/issues/${childNumber}`, "--jq", "{id: .node_id}"], cwd);
+    if (!parentResult.ok || !childResult.ok) {
+        return fail("Could not resolve issue node IDs for sub-issue linking");
+    }
+    const mutation = `mutation { addSubIssue(input: { issueId: "${parentResult.data.id}", subIssueId: "${childResult.data.id}" }) { issue { id } } }`;
+    return runGh(["api", "graphql", "-f", `query=${mutation}`], cwd);
+}
+// ─── Milestones ─────────────────────────────────────────────────────────────
+export function ghCreateMilestone(cwd, repo, title, description) {
+    const result = runGhJson([
+        "api", `repos/${repo}/milestones`,
+        "-X", "POST",
+        "-f", `title=${title}`,
+        "-f", `description=${truncateBody(description)}`,
+        "-f", "state=open",
+        "--jq", "{number: .number}",
+    ], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(result.data.number);
+}
+export function ghCloseMilestone(cwd, repo, milestoneNumber) {
+    const result = runGh([
+        "api", `repos/${repo}/milestones/${milestoneNumber}`,
+        "-X", "PATCH",
+        "-f", "state=closed",
+    ], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(undefined);
+}
+export function ghCreatePR(cwd, opts) {
+    const args = [
+        "pr", "create",
+        "--repo", opts.repo,
+        "--base", opts.base,
+        "--head", opts.head,
+        "--title", opts.title,
+        "--body", truncateBody(opts.body),
+    ];
+    if (opts.draft)
+        args.push("--draft");
+    const result = runGh(args, cwd);
+    if (!result.ok)
+        return fail(result.error);
+    const match = result.data.match(/\/pull\/(\d+)/);
+    if (!match)
+        return fail(`Could not parse PR number from: ${result.data}`);
+    return ok(parseInt(match[1], 10));
+}
+export function ghMarkPRReady(cwd, repo, prNumber) {
+    const result = runGh(["pr", "ready", String(prNumber), "--repo", repo], cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(undefined);
+}
+export function ghMergePR(cwd, repo, prNumber, strategy = "squash") {
+    const args = [
+        "pr", "merge", String(prNumber),
+        "--repo", repo,
+        strategy === "squash" ? "--squash" : "--merge",
+        "--delete-branch",
+    ];
+    const result = runGh(args, cwd);
+    if (!result.ok)
+        return fail(result.error);
+    return ok(undefined);
+}
+// ─── Projects v2 ────────────────────────────────────────────────────────────
+export function ghAddToProject(cwd, repo, projectNumber, issueNumber) {
+    // Get the issue's node ID first
+    const issueResult = runGhJson(["api", `repos/${repo}/issues/${issueNumber}`, "--jq", "{id: .node_id}"], cwd);
+    if (!issueResult.ok)
+        return fail(issueResult.error);
+    // Get the project's node ID
+    const [owner] = repo.split("/");
+    const projectResult = runGhJson([
+        "api", "graphql",
+        "-f", `query=query { user(login: "${owner}") { projectV2(number: ${projectNumber}) { id } } }`,
+        "--jq", ".data.user.projectV2.id",
+    ], cwd);
+    // Try org if user fails
+    let projectId;
+    if (projectResult.ok && projectResult.data?.id) {
+        projectId = projectResult.data.id;
+    }
+    else {
+        const orgResult = runGhJson([
+            "api", "graphql",
+            "-f", `query=query { organization(login: "${owner}") { projectV2(number: ${projectNumber}) { id } } }`,
+            "--jq", ".data.organization.projectV2.id",
+        ], cwd);
+        if (orgResult.ok)
+            projectId = orgResult.data?.id;
+    }
+    if (!projectId)
+        return fail("Could not find project");
+    const mutation = `mutation { addProjectV2ItemById(input: { projectId: "${projectId}", contentId: "${issueResult.data.id}" }) { item { id } } }`;
+    return runGh(["api", "graphql", "-f", `query=${mutation}`], cwd);
+}
+// ─── Branch Operations ──────────────────────────────────────────────────────
+export function ghPushBranch(cwd, branch, setUpstream = true) {
+    const args = ["git", "push"];
+    if (setUpstream)
+        args.push("-u", "origin", branch);
+    else
+        args.push("origin", branch);
+    try {
+        execFileSync(args[0], args.slice(1), {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 30_000,
+        });
+        return ok(undefined);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+export function ghCreateBranch(cwd, branch, from) {
+    try {
+        execFileSync("git", ["branch", branch, from], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+        });
+        return ok(undefined);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/resources/extensions/github-sync/index.js

@@ -0,0 +1,73 @@
+/**
+ * GitHub Sync extension for GSD.
+ *
+ * Opt-in extension that syncs GSD lifecycle events to GitHub:
+ * milestones → GH Milestones + tracking issues, slices → draft PRs,
+ * tasks → sub-issues with auto-close on commit.
+ *
+ * Integration happens via a single dynamic import in auto-post-unit.ts.
+ * This index registers a `/github-sync` command for manual bootstrap
+ * and status display.
+ */
+import { bootstrapSync } from "./sync.js";
+import { loadSyncMapping } from "./mapping.js";
+import { ghIsAvailable } from "./cli.js";
+export default function (pi) {
+    pi.registerCommand("github-sync", {
+        description: "Bootstrap GitHub sync or show sync status",
+        handler: async (args, ctx) => {
+            const subcommand = args.trim().toLowerCase();
+            if (subcommand === "status") {
+                await showStatus(ctx);
+                return;
+            }
+            if (subcommand === "bootstrap" || subcommand === "") {
+                await runBootstrap(ctx);
+                return;
+            }
+            ctx.ui.notify("Usage: /github-sync [bootstrap|status]", "info");
+        },
+    });
+}
+async function showStatus(ctx) {
+    if (!ghIsAvailable()) {
+        ctx.ui.notify("GitHub sync: `gh` CLI not installed or not authenticated.", "warning");
+        return;
+    }
+    const mapping = loadSyncMapping(ctx.cwd);
+    if (!mapping) {
+        ctx.ui.notify("GitHub sync: No sync mapping found. Run `/github-sync bootstrap` to initialize.", "info");
+        return;
+    }
+    const milestoneCount = Object.keys(mapping.milestones).length;
+    const sliceCount = Object.keys(mapping.slices).length;
+    const taskCount = Object.keys(mapping.tasks).length;
+    const openMilestones = Object.values(mapping.milestones).filter(m => m.state === "open").length;
+    const openSlices = Object.values(mapping.slices).filter(s => s.state === "open").length;
+    const openTasks = Object.values(mapping.tasks).filter(t => t.state === "open").length;
+    ctx.ui.notify([
+        `GitHub sync: repo=${mapping.repo}`,
+        `  Milestones: ${milestoneCount} (${openMilestones} open)`,
+        `  Slices: ${sliceCount} (${openSlices} open)`,
+        `  Tasks: ${taskCount} (${openTasks} open)`,
+    ].join("\n"), "info");
+}
+async function runBootstrap(ctx) {
+    if (!ghIsAvailable()) {
+        ctx.ui.notify("GitHub sync: `gh` CLI not installed or not authenticated.", "warning");
+        return;
+    }
+    ctx.ui.notify("GitHub sync: bootstrapping...", "info");
+    try {
+        const counts = await bootstrapSync(ctx.cwd);
+        if (counts.milestones === 0 && counts.slices === 0 && counts.tasks === 0) {
+            ctx.ui.notify("GitHub sync: everything already synced (or no milestones found).", "info");
+        }
+        else {
+            ctx.ui.notify(`GitHub sync: created ${counts.milestones} milestone(s), ${counts.slices} slice(s), ${counts.tasks} task(s).`, "info");
+        }
+    }
+    catch (err) {
+        ctx.ui.notify(`GitHub sync bootstrap failed: ${err}`, "error");
+    }
+}

package/dist/resources/extensions/github-sync/mapping.js

@@ -0,0 +1,67 @@
+/**
+ * Persistence layer for the GitHub sync mapping.
+ *
+ * The mapping lives at `.gsd/github-sync.json` and tracks which GSD
+ * entities have been synced to which GitHub entities (issues, PRs,
+ * milestones) along with their numbers and sync timestamps.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "../gsd/atomic-write.js";
+const MAPPING_FILENAME = "github-sync.json";
+function mappingPath(basePath) {
+    return join(basePath, ".gsd", MAPPING_FILENAME);
+}
+// ─── Load / Save ────────────────────────────────────────────────────────────
+export function loadSyncMapping(basePath) {
+    const path = mappingPath(basePath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== 1)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSyncMapping(basePath, mapping) {
+    const path = mappingPath(basePath);
+    atomicWriteSync(path, JSON.stringify(mapping, null, 2) + "\n");
+}
+export function createEmptyMapping(repo) {
+    return {
+        version: 1,
+        repo,
+        milestones: {},
+        slices: {},
+        tasks: {},
+    };
+}
+// ─── Accessors ──────────────────────────────────────────────────────────────
+export function getMilestoneRecord(mapping, mid) {
+    return mapping.milestones[mid] ?? null;
+}
+export function getSliceRecord(mapping, mid, sid) {
+    return mapping.slices[`${mid}/${sid}`] ?? null;
+}
+export function getTaskRecord(mapping, mid, sid, tid) {
+    return mapping.tasks[`${mid}/${sid}/${tid}`] ?? null;
+}
+export function getTaskIssueNumber(mapping, mid, sid, tid) {
+    const record = getTaskRecord(mapping, mid, sid, tid);
+    return record?.issueNumber ?? null;
+}
+// ─── Mutators ───────────────────────────────────────────────────────────────
+export function setMilestoneRecord(mapping, mid, record) {
+    mapping.milestones[mid] = record;
+}
+export function setSliceRecord(mapping, mid, sid, record) {
+    mapping.slices[`${mid}/${sid}`] = record;
+}
+export function setTaskRecord(mapping, mid, sid, tid, record) {
+    mapping.tasks[`${mid}/${sid}/${tid}`] = record;
+}