gsd-antigravity-kit 2.0.1 → 2.1.0

package/.agent/skills/gsd/assets/templates/spec.md

@@ -0,0 +1,307 @@
+# Phase Spec Template
+
+Template for `.planning/phases/XX-name/{phase_num}-SPEC.md` — locks requirements before discuss-phase.
+
+**Purpose:** Capture WHAT a phase delivers and WHY, with enough precision that requirements are falsifiable. discuss-phase reads this file and focuses on HOW to implement (skipping "what/why" questions already answered here).
+
+**Key principle:** Every requirement must be falsifiable — you can write a test or check that proves it was met or not. Vague requirements like "improve performance" are not allowed.
+
+**Downstream consumers:**
+- `discuss-phase` — reads SPEC.md at startup; treats Requirements, Boundaries, and Acceptance Criteria as locked; skips "what/why" questions
+- `gsd-planner` — reads locked requirements to constrain plan scope
+- `gsd-verifier` — uses acceptance criteria as explicit pass/fail checks
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] — Specification
+
+**Created:** [date]
+**Ambiguity score:** [score] (gate: ≤ 0.20)
+**Requirements:** [N] locked
+
+## Goal
+
+[One precise sentence — specific and measurable. NOT "improve X" — instead "X changes from A to B".]
+
+## Background
+
+[Current state from codebase — what exists today, what's broken or missing, what triggers this work. Grounded in code reality, not abstract description.]
+
+## Requirements
+
+1. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check — how a verifier confirms this was met]
+
+2. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check]
+
+[Continue for all requirements. Each must have Current/Target/Acceptance.]
+
+## Boundaries
+
+**In scope:**
+- [Explicit list of what this phase produces]
+- [Each item is a concrete deliverable or behavior]
+
+**Out of scope:**
+- [Explicit list of what this phase does NOT do] — [brief reason why it's excluded]
+- [Adjacent problems excluded from this phase] — [brief reason]
+
+## Constraints
+
+[Performance, compatibility, data volume, dependency, or platform constraints.
+If none: "No additional constraints beyond standard project conventions."]
+
+## Acceptance Criteria
+
+- [ ] [Pass/fail criterion — unambiguous, verifiable]
+- [ ] [Pass/fail criterion]
+- [ ] [Pass/fail criterion]
+
+[Every acceptance criterion must be a checkbox that resolves to PASS or FAIL.
+No "should feel good", "looks reasonable", or "generally works" — those are not checkboxes.]
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                              |
+|--------------------|-------|------|--------|------------------------------------|
+| Goal Clarity       |       | 0.75 |        |                                    |
+| Boundary Clarity   |       | 0.70 |        |                                    |
+| Constraint Clarity |       | 0.65 |        |                                    |
+| Acceptance Criteria|       | 0.70 |        |                                    |
+| **Ambiguity**      |       | ≤0.20|        |                                    |
+
+Status: ✓ = met minimum, ⚠ = below minimum (planner treats as assumption)
+
+## Interview Log
+
+[Key decisions made during the Socratic interview. Format: round → question → answer → decision locked.]
+
+| Round | Perspective    | Question summary         | Decision locked                    |
+|-------|----------------|-------------------------|------------------------------------|
+| 1     | Researcher     | [what was asked]        | [what was decided]                 |
+| 2     | Simplifier     | [what was asked]        | [what was decided]                 |
+| 3     | Boundary Keeper| [what was asked]        | [what was decided]                 |
+
+[If --auto mode: note "auto-selected" decisions with the reasoning Antigravity used.]
+
+---
+
+*Phase: [XX-name]*
+*Spec created: [date]*
+*Next step: /gsd-discuss-phase [X] — implementation decisions (how to build what's specified above)*
+```
+
+<good_examples>
+
+**Example 1: Feature addition (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.12
+**Requirements:** 4 locked
+
+## Goal
+
+Users can scroll through posts from accounts they follow, with new posts available after pull-to-refresh.
+
+## Background
+
+The database has a `posts` table and `follows` table. No feed query or feed UI exists today. The home screen shows a placeholder "Your feed will appear here." This phase builds the feed query, API endpoint, and the feed list component.
+
+## Requirements
+
+1. **Feed query**: Returns posts from followed accounts ordered by creation time, descending.
+   - Current: No feed query exists — `posts` table is queried directly only from profile pages
+   - Target: `GET /api/feed` returns paginated posts from followed accounts, newest first, max 20 per page
+   - Acceptance: Query returns correct posts for a user who follows 3 accounts with known post counts; cursor-based pagination advances correctly
+
+2. **Feed display**: Posts display in a scrollable card list.
+   - Current: Home screen shows static placeholder text
+   - Target: Home screen renders feed cards with author, timestamp, post content, and reaction count
+   - Acceptance: Feed renders without error for 0 posts (empty state shown), 1 post, and 20+ posts
+
+3. **Pull-to-refresh**: User can refresh the feed manually.
+   - Current: No refresh mechanism exists
+   - Target: Pull-down gesture triggers refetch; new posts appear at top of list
+   - Acceptance: After a new post is created in test, pull-to-refresh shows the new post without full app restart
+
+4. **New posts indicator**: When new posts arrive, a banner appears instead of auto-scrolling.
+   - Current: No such mechanism
+   - Target: "3 new posts" banner appears when refetch returns posts newer than the oldest visible post; tapping banner scrolls to top and shows new posts
+   - Acceptance: Banner appears for ≥1 new post, does not appear when no new posts, tap navigates to top
+
+## Boundaries
+
+**In scope:**
+- Feed query (backend) — posts from followed accounts, paginated
+- Feed list UI (frontend) — post cards with author, timestamp, content, reaction counts
+- Pull-to-refresh gesture
+- New posts indicator banner
+- Empty state when user follows no one or no posts exist
+
+**Out of scope:**
+- Creating posts — that is Phase 4
+- Reacting to posts — that is Phase 5
+- Following/unfollowing accounts — that is Phase 2 (already done)
+- Push notifications for new posts — separate backlog item
+
+## Constraints
+
+- Feed query must use cursor-based pagination (not offset) — the database has 500K+ posts and offset pagination is unacceptably slow beyond page 3
+- The feed card component must reuse the existing `<AvatarImage>` component from Phase 2
+
+## Acceptance Criteria
+
+- [ ] `GET /api/feed` returns posts only from followed accounts (not all posts)
+- [ ] `GET /api/feed` supports `cursor` parameter for pagination
+- [ ] Feed renders correctly at 0, 1, and 20+ posts
+- [ ] Pull-to-refresh triggers refetch
+- [ ] New posts indicator appears when posts newer than current view exist
+- [ ] Empty state renders when user follows no one
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                            |
+|--------------------|-------|------|--------|----------------------------------|
+| Goal Clarity       | 0.92  | 0.75 | ✓      |                                  |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list       |
+| Constraint Clarity | 0.80  | 0.65 | ✓      | Cursor pagination required       |
+| Acceptance Criteria| 0.85  | 0.70 | ✓      | 6 pass/fail criteria             |
+| **Ambiguity**      | 0.12  | ≤0.20| ✓      |                                  |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What exists in posts today?  | posts + follows tables exist, no feed  |
+| 2     | Simplifier      | Minimum viable feed?         | Cards + pull-refresh, no auto-scroll   |
+| 3     | Boundary Keeper | What's NOT this phase?       | Creating posts, reactions out of scope |
+| 3     | Boundary Keeper | What does done look like?    | Scrollable feed with 4 card fields     |
+
+---
+
+*Phase: 03-post-feed*
+*Spec created: 2025-01-20*
+*Next step: /gsd-discuss-phase 3 — implementation decisions (card layout, loading skeleton, etc.)*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.15
+**Requirements:** 3 locked
+
+## Goal
+
+A `gsd backup` CLI command creates a reproducible database snapshot that can be restored by `gsd restore` (a separate phase).
+
+## Background
+
+No backup tooling exists. The project uses PostgreSQL. Developers currently use `pg_dump` manually — there is no standardized process, no output naming convention, and no CI integration. Three incidents in the last quarter involved restoring from wrong or corrupt dumps.
+
+## Requirements
+
+1. **Backup creation**: CLI command executes a full database backup.
+   - Current: No `backup` subcommand exists in the CLI
+   - Target: `gsd backup` connects to the database (via `DATABASE_URL` env or `--db` flag), runs pg_dump, writes output to `./backups/YYYY-MM-DD_HH-MM-SS.dump`
+   - Acceptance: Running `gsd backup` on a test database creates a `.dump` file; running `pg_restore` on that file recreates the database without error
+
+2. **Network retry**: Transient network failures are retried automatically.
+   - Current: pg_dump fails immediately on network error
+   - Target: Backup retries up to 3 times with 5-second delay; 4th failure exits with code 1 and a message to stderr
+   - Acceptance: Simulating 2 sequential network failures causes 2 retries then success; simulating 4 failures causes exit code 1 and stderr message
+
+3. **Partial cleanup**: Failed backups do not leave corrupt files.
+   - Current: Manual pg_dump leaves partial files on failure
+   - Target: If backup fails after starting, the partial `.dump` file is deleted before exit
+   - Acceptance: After a simulated failure mid-dump, no `.dump` file exists in `./backups/`
+
+## Boundaries
+
+**In scope:**
+- `gsd backup` subcommand (full dump only)
+- Output to `./backups/` directory (created if missing)
+- Network retry (3 attempts)
+- Partial file cleanup on failure
+
+**Out of scope:**
+- `gsd restore` — that is Phase 3
+- Incremental backups — separate backlog item (full dump only for now)
+- S3 or remote storage — separate backlog item
+- Encryption — separate backlog item
+- Scheduled/cron backups — separate backlog item
+
+## Constraints
+
+- Must use `pg_dump` (not a custom query) — ensures compatibility with standard `pg_restore`
+- `--no-retry` flag must be available for CI use (fail fast, no retries)
+
+## Acceptance Criteria
+
+- [ ] `gsd backup` creates a `.dump` file in `./backups/YYYY-MM-DD_HH-MM-SS.dump` format
+- [ ] `gsd backup` uses `DATABASE_URL` env var or `--db` flag for connection
+- [ ] 3 retries on network failure, then exit code 1 with stderr message
+- [ ] `--no-retry` flag skips retries and fails immediately on first error
+- [ ] No partial `.dump` file left after a failed backup
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                          |
+|--------------------|-------|------|--------|--------------------------------|
+| Goal Clarity       | 0.90  | 0.75 | ✓      |                                |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list     |
+| Constraint Clarity | 0.75  | 0.65 | ✓      | pg_dump required               |
+| Acceptance Criteria| 0.80  | 0.70 | ✓      | 5 pass/fail criteria           |
+| **Ambiguity**      | 0.15  | ≤0.20| ✓      |                                |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What backup tooling exists?  | None — pg_dump manual only             |
+| 2     | Simplifier      | Minimum viable backup?       | Full dump only, local only             |
+| 3     | Boundary Keeper | What's NOT this phase?       | Restore, S3, encryption excluded       |
+| 4     | Failure Analyst | What goes wrong on failure?  | Partial files, CI fail-fast needed     |
+
+---
+
+*Phase: 02-backup-command*
+*Spec created: 2025-01-20*
+*Next step: /gsd-discuss-phase 2 — implementation decisions (progress reporting, flag design, etc.)*
+```
+
+</good_examples>
+
+<guidelines>
+**Every requirement needs all three fields:**
+- Current: grounds the requirement in reality — what exists today?
+- Target: the concrete change — not "improve X" but "X becomes Y"
+- Acceptance: the falsifiable check — how does a verifier confirm this?
+
+**Ambiguity Report must reflect the actual interview.** If a dimension is below minimum, mark it ⚠ — the planner knows to treat it as an assumption rather than a locked requirement.
+
+**Interview Log is evidence of rigor.** Don't skip it. It shows that requirements came from discovery, not assumption.
+
+**Boundaries protect the phase from scope creep.** The out-of-scope list with reasoning is as important as the in-scope list. Future phases that touch adjacent areas can point to this SPEC.md to understand what was intentionally excluded.
+
+**SPEC.md is a one-way door for requirements.** discuss-phase will treat these as locked. If requirements change after SPEC.md is written, the user should update SPEC.md first, then re-run discuss-phase.
+
+**SPEC.md does NOT replace CONTEXT.md.** They serve different purposes:
+- SPEC.md: what the phase delivers (requirements, boundaries, acceptance criteria)
+- CONTEXT.md: how the phase will be implemented (decisions, patterns, tradeoffs)
+
+discuss-phase generates CONTEXT.md after reading SPEC.md.
+</guidelines>

package/.agent/skills/gsd/assets/templates/state.md

@@ -66,6 +66,14 @@ None yet.
 
 None yet.
 
+## Deferred Items
+
+Items acknowledged and carried forward from previous milestone close:
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* | | | |
+
 ## Session Continuity
 
 Last session: [YYYY-MM-DD HH:MM]

package/.agent/skills/gsd/bin/gsd-tools.cjs

@@ -182,6 +182,17 @@ async function main() {
   args.splice(pickIdx, 2);
   }
 
+  // --default <value>: for config-get, return this value instead of erroring
+  // when the key is absent. Allows workflows to express optional config reads
+  // without defensive `2>/dev/null || true` boilerplate (#1893).
+  const defaultIdx = args.indexOf('--default');
+  let defaultValue = undefined;
+  if (defaultIdx !== -1) {
+  defaultValue = args[defaultIdx + 1];
+  if (defaultValue === undefined) defaultValue = '';
+  args.splice(defaultIdx, 2);
+  }
+
   const command = args[0];
 
   if (!command) {
@@ -203,7 +214,7 @@ async function main() {
   // filesystem traversal on every invocation.
   const SKIP_ROOT_RESOLUTION = new Set([
   'generate-slug', 'current-timestamp', 'verify-path-exists',
-  'verify-summary', 'template', 'frontmatter',
+  'verify-summary', 'template', 'frontmatter', 'detect-custom-files',
   ]);
   if (!SKIP_ROOT_RESOLUTION.has(command)) {
   cwd = findProjectRoot(cwd);
@@ -234,7 +245,7 @@ async function main() {
     }
   };
   try {
-    await runCommand(command, args, cwd, raw);
+    await runCommand(command, args, cwd, raw, defaultValue);
     cleanup();
   } catch (e) {
     fs.writeSync = origWriteSync;
@@ -243,7 +254,27 @@ async function main() {
   return;
   }
 
-  await runCommand(command, args, cwd, raw);
+  // Intercept stdout to transparently resolve @file: references (#1891).
+  // core.cjs output() writes @file:<path> when JSON > 50KB. The --pick path
+  // already resolves this, but the normal path wrote @file: to stdout, forcing
+  // every workflow to have a bash-specific `if [[ "$INIT" == @file:* ]]` check
+  // that breaks on PowerShell and other non-bash shells.
+  const origWriteSync2 = fs.writeSync;
+  const outChunks = [];
+  fs.writeSync = function (fd, data, ...rest) {
+  if (fd === 1) { outChunks.push(String(data)); return; }
+  return origWriteSync2.call(fs, fd, data, ...rest);
+  };
+  try {
+  await runCommand(command, args, cwd, raw, defaultValue);
+  } finally {
+  fs.writeSync = origWriteSync2;
+  }
+  let captured = outChunks.join('');
+  if (captured.startsWith('@file:')) {
+  captured = fs.readFileSync(captured.slice(6), 'utf-8');
+  }
+  origWriteSync2.call(fs, 1, captured);
 }
 
 /**
@@ -269,7 +300,7 @@ function extractField(obj, fieldPath) {
   return current;
 }
 
-async function runCommand(command, args, cwd, raw) {
+async function runCommand(command, args, cwd, raw, defaultValue) {
   switch (command) {
   case 'state': {
     const subcommand = args[1];
@@ -323,6 +354,9 @@ async function runCommand(command, args, cwd, raw) {
     } else if (subcommand === 'sync') {
     const { verify } = parseNamedArgs(args, [], ['verify']);
     state.cmdStateSync(cwd, { verify }, raw);
+    } else if (subcommand === 'prune') {
+    const { 'keep-recent': keepRecent, 'dry-run': dryRun } = parseNamedArgs(args, ['keep-recent'], ['dry-run']);
+    state.cmdStatePrune(cwd, { keepRecent: keepRecent || '3', dryRun: !!dryRun }, raw);
     } else {
     state.cmdStateLoad(cwd, raw);
     }
@@ -477,7 +511,7 @@ async function runCommand(command, args, cwd, raw) {
   }
 
   case 'config-get': {
-    config.cmdConfigGet(cwd, args[1], raw);
+    config.cmdConfigGet(cwd, args[1], raw, defaultValue);
     break;
   }
 
@@ -486,11 +520,21 @@ async function runCommand(command, args, cwd, raw) {
     break;
   }
 
+  case 'config-path': {
+    config.cmdConfigPath(cwd, raw);
+    break;
+  }
+
   case 'agent-skills': {
     init.cmdAgentSkills(cwd, args[1], raw);
     break;
   }
 
+  case 'skill-manifest': {
+    init.cmdSkillManifest(cwd, args, raw);
+    break;
+  }
+
   case 'history-digest': {
     commands.cmdHistoryDigest(cwd, raw);
     break;
@@ -556,6 +600,16 @@ async function runCommand(command, args, cwd, raw) {
       }
     }
     phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId);
+    } else if (subcommand === 'add-batch') {
+    // Accepts JSON array of descriptions via --descriptions '[...]' or positional args
+    const descFlagIdx = args.indexOf('--descriptions');
+    let descriptions;
+    if (descFlagIdx !== -1 && args[descFlagIdx + 1]) {
+      try { descriptions = JSON.parse(args[descFlagIdx + 1]); } catch (e) { error('--descriptions must be a JSON array'); }
+    } else {
+      descriptions = args.slice(2).filter(a => a !== '--raw');
+    }
+    phase.cmdPhaseAddBatch(cwd, descriptions, raw);
     } else if (subcommand === 'insert') {
     phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
     } else if (subcommand === 'remove') {
@@ -564,7 +618,7 @@ async function runCommand(command, args, cwd, raw) {
     } else if (subcommand === 'complete') {
     phase.cmdPhaseComplete(cwd, args[2], raw);
     } else {
-    error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+    error('Unknown phase subcommand. Available: next-decimal, add, add-batch, insert, remove, complete');
     }
     break;
   }
@@ -608,6 +662,18 @@ async function runCommand(command, args, cwd, raw) {
     break;
   }
 
+  case 'audit-open': {
+    const { auditOpenArtifacts, formatAuditReport } = require('./lib/audit.cjs');
+    const includeRaw = args.includes('--json');
+    const result = auditOpenArtifacts(cwd);
+    if (includeRaw) {
+    core.output(result, raw);
+    } else {
+    core.output(formatAuditReport(result), raw);
+    }
+    break;
+  }
+
   case 'uat': {
     const subcommand = args[1];
     const uat = require('./lib/uat.cjs');
@@ -653,13 +719,13 @@ async function runCommand(command, args, cwd, raw) {
     const includes = parseIncludeFlag(args);
     switch (workflow) {
     case 'execute-phase': {
-      const { validate: epValidate } = parseNamedArgs(args, [], ['validate']);
-      init.cmdInitExecutePhase(cwd, args[2], includes, raw, { validate: epValidate });
+      const { validate: epValidate, tdd: epTdd } = parseNamedArgs(args, [], ['validate', 'tdd']);
+      init.cmdInitExecutePhase(cwd, args[2], includes, raw, { validate: epValidate, tdd: epTdd });
       break;
     }
     case 'plan-phase': {
-      const { validate: ppValidate } = parseNamedArgs(args, [], ['validate']);
-      init.cmdInitPlanPhase(cwd, args[2], includes, raw, { validate: ppValidate });
+      const { validate: ppValidate, tdd: ppTdd } = parseNamedArgs(args, [], ['validate', 'tdd']);
+      init.cmdInitPlanPhase(cwd, args[2], includes, raw, { validate: ppValidate, tdd: ppTdd });
       break;
     }
     case 'new-project':
@@ -866,7 +932,15 @@ async function runCommand(command, args, cwd, raw) {
     core.output(intel.intelQuery(term, planningDir), raw);
     } else if (subcommand === 'status') {
     const planningDir = path.join(cwd, '.planning');
-    core.output(intel.intelStatus(planningDir), raw);
+    const status = intel.intelStatus(planningDir);
+    if (!raw && status.files) {
+      for (const file of Object.values(status.files)) {
+      if (file.updated_at) {
+        file.updated_at = core.timeAgo(new Date(file.updated_at));
+      }
+      }
+    }
+    core.output(status, raw);
     } else if (subcommand === 'diff') {
     const planningDir = path.join(cwd, '.planning');
     core.output(intel.intelDiff(planningDir), raw);
@@ -893,6 +967,33 @@ async function runCommand(command, args, cwd, raw) {
     break;
   }
 
+  // ─── Graphify ──────────────────────────────────────────────────────────
+
+  case 'graphify': {
+    const graphify = require('./lib/graphify.cjs');
+    const subcommand = args[1];
+    if (subcommand === 'query') {
+    const term = args[2];
+    if (!term) error('Usage: gsd-tools graphify query <term>');
+    const budgetIdx = args.indexOf('--budget');
+    const budget = budgetIdx !== -1 ? parseInt(args[budgetIdx + 1], 10) : null;
+    core.output(graphify.graphifyQuery(cwd, term, { budget }), raw);
+    } else if (subcommand === 'status') {
+    core.output(graphify.graphifyStatus(cwd), raw);
+    } else if (subcommand === 'diff') {
+    core.output(graphify.graphifyDiff(cwd), raw);
+    } else if (subcommand === 'build') {
+    if (args[2] === 'snapshot') {
+      core.output(graphify.writeSnapshot(cwd), raw);
+    } else {
+      core.output(graphify.graphifyBuild(cwd), raw);
+    }
+    } else {
+    error('Unknown graphify subcommand. Available: build, query, status, diff');
+    }
+    break;
+  }
+
   // ─── Documentation ────────────────────────────────────────────────────
 
   case 'docs-init': {
@@ -928,6 +1029,106 @@ async function runCommand(command, args, cwd, raw) {
     break;
   }
 
+  // ─── detect-custom-files ───────────────────────────────────────────────
+  // Detect user-added files inside GSD-managed directories that are not
+  // tracked in gsd-file-manifest.json. Used by the update workflow to back
+  // up custom files before the installer wipes those directories.
+  //
+  // This replaces the fragile bash pattern:
+  //   MANIFEST_FILES=$(node -e "require('$RUNTIME_DIR/...')" 2>/dev/null)
+  //   ${filepath#$RUNTIME_DIR/}   # unreliable path stripping
+  // which silently returns CUSTOM_COUNT=0 when $RUNTIME_DIR is unset or
+  // when the stripped path does not match the manifest key format (#1997).
+
+  case 'detect-custom-files': {
+    const configDirIdx = args.indexOf('--config-dir');
+    const configDir = configDirIdx !== -1 ? args[configDirIdx + 1] : null;
+    if (!configDir) {
+    error('Usage: gsd-tools detect-custom-files --config-dir <path>');
+    }
+    const resolvedConfigDir = path.resolve(configDir);
+    if (!fs.existsSync(resolvedConfigDir)) {
+    error(`Config directory not found: ${resolvedConfigDir}`);
+    }
+
+    const manifestPath = path.join(resolvedConfigDir, 'gsd-file-manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+    // No manifest — cannot determine what is custom. Return empty list
+    // (same behaviour as saveLocalPatches in install.js when no manifest).
+    const out = { custom_files: [], custom_count: 0, manifest_found: false };
+    process.stdout.write(JSON.stringify(out, null, 2));
+    break;
+    }
+
+    let manifest;
+    try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch {
+    const out = { custom_files: [], custom_count: 0, manifest_found: false, error: 'manifest parse error' };
+    process.stdout.write(JSON.stringify(out, null, 2));
+    break;
+    }
+
+    const manifestKeys = new Set(Object.keys(manifest.files || {}));
+
+    // GSD-managed directories to scan for user-added files.
+    // These are the directories the installer wipes on update.
+    const GSD_MANAGED_DIRS = [
+    'get-shit-done',
+    'agents',
+    path.join('commands', 'gsd'),
+    'hooks',
+    // OpenCode/Kilo flat command dir
+    'command',
+    // Codex/Copilot skills dir
+    'skills',
+    ];
+
+    function walkDir(dir, baseDir) {
+    const results = [];
+    if (!fs.existsSync(dir)) return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, baseDir));
+      } else {
+      // Use forward slashes for cross-platform manifest key compatibility
+      const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+      results.push(relPath);
+      }
+    }
+    return results;
+    }
+
+    const customFiles = [];
+    for (const managedDir of GSD_MANAGED_DIRS) {
+    const absDir = path.join(resolvedConfigDir, managedDir);
+    if (!fs.existsSync(absDir)) continue;
+    for (const relPath of walkDir(absDir, resolvedConfigDir)) {
+      if (!manifestKeys.has(relPath)) {
+      customFiles.push(relPath);
+      }
+    }
+    }
+
+    const out = {
+    custom_files: customFiles,
+    custom_count: customFiles.length,
+    manifest_found: true,
+    manifest_version: manifest.version || null,
+    };
+    process.stdout.write(JSON.stringify(out, null, 2));
+    break;
+  }
+
+  // ─── GSD-2 Reverse Migration ───────────────────────────────────────────
+
+  case 'from-gsd2': {
+    const gsd2Import = require('./lib/gsd2-import.cjs');
+    gsd2Import.cmdFromGsd2(args.slice(1), cwd, raw);
+    break;
+  }
+
   default:
     error(`Unknown command: ${command}`);
   }