@tekyzinc/gsd-t 2.39.11 → 2.39.13

package/CHANGELOG.md

@@ -2,15 +2,17 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
-## [2.39.11] - 2026-03-19
+## [2.39.12] - 2026-03-19
 
 ### Added
 - **Graph auto-sync at command boundary** — every GSD-T command now checks index freshness automatically; both native JSON and CGC/Neo4j are re-indexed when files change (500ms TTL deduplication)
 - **Neo4j setup guide** — `docs/neo4j-setup.md` with full instructions for Docker container, CGC install, project indexing, and scanning
-- Backlog item #8: Auto-Setup Graph Dependencies feature
+- Backlog items #8 (Auto-Setup Graph Dependencies) and #9 (Provider Failure Warnings + Auto-Recovery)
 
 ### Fixed
 - CGC sync uses `cgc index` CLI instead of broken `add_code_to_graph` MCP tool call (CGC 0.3.1 Windows bug workaround)
+- CGC sync retries with `--force` on failure, warns user clearly instead of silently swallowing errors
+- CGC sync sets `PYTHONIOENCODING=utf-8` to prevent crash on emoji/Unicode in source code on Windows
 
 ## [2.39.10] - 2026-03-19
 

package/bin/graph-query.js

@@ -364,16 +364,39 @@ const grepProvider = {
 // --- CGC Sync (Phase 2: keep Neo4j in sync at command boundary) ---
 
 function _syncCgc(projectRoot) {
+  if (!cgcProvider.available()) return;
+  // Use CLI instead of MCP tool call — add_code_to_graph MCP is broken
+  // on Windows in CGC 0.3.1 (directory param arrives as None)
+  const { execFileSync } = require('child_process');
+  const cgcEnv = { ...process.env, PYTHONIOENCODING: 'utf-8' };
+  const cgcOpts = { timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'], env: cgcEnv };
+
+  // Attempt 1: normal sync
   try {
-    if (!cgcProvider.available()) return;
-    // Use CLI instead of MCP tool call — add_code_to_graph MCP is broken
-    // on Windows in CGC 0.3.1 (directory param arrives as None)
-    const { execFileSync } = require('child_process');
-    execFileSync('cgc', ['index', projectRoot], {
-      timeout: 30000,
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-  } catch { /* CGC sync is best-effort */ }
+    execFileSync('cgc', ['index', projectRoot], cgcOpts);
+    return;
+  } catch (err1) {
+    const msg1 = err1.stderr ? err1.stderr.toString() : err1.message;
+    // Attempt 2: force re-index to recover from corrupt state
+    try {
+      execFileSync('cgc', ['index', projectRoot, '--force'], cgcOpts);
+      process.stderr.write(
+        '[GSD-T] CGC sync recovered via force re-index for ' +
+        projectRoot + '\n'
+      );
+      return;
+    } catch (err2) {
+      const msg2 = err2.stderr ? err2.stderr.toString() : err2.message;
+      // Both attempts failed — warn the user clearly
+      process.stderr.write(
+        '[GSD-T] ⚠ CGC sync FAILED for ' + projectRoot + '\n' +
+        '  Error: ' + (msg2 || msg1).split('\n')[0] + '\n' +
+        '  Impact: Neo4j graph is stale — deep call chain analysis ' +
+        'may return outdated results\n' +
+        '  Fix: run "cgc index ' + projectRoot + ' --force" manually\n'
+      );
+    }
+  }
 }
 
 // --- Main query function ---

package/commands/gsd-t-complete-milestone.md

@@ -213,6 +213,26 @@ If `README.md` exists, update it to reflect the completed milestone:
 
 If `README.md` doesn't exist, create one with project name, description, version, tech stack, setup instructions, and link to `docs/`.
 
+## Step 8.5: Scan Doc Milestone Checkpoint
+
+Before tagging, ensure scan docs reflect the final state of the codebase after all milestone work. This is the full-refresh counterpart to the micro-updates done during execute/quick/debug.
+
+If `.gsd-t/scan/` exists (a prior scan has been run):
+1. Check `.gsd-t/scan/.cache.json` for staleness — count commits since last scan
+2. If **any dimension is stale** (>0 commits since scan):
+   - Log: "Running milestone scan checkpoint — refreshing all stale scan dimensions..."
+   - Re-run all stale dimensions using scan teammates (same team structure as `gsd-t-scan` Step 2):
+     - Stale `architecture.md` → architecture teammate (model: haiku)
+     - Stale `quality.md` → quality teammate (model: sonnet)
+     - Stale `security.md` → security teammate (model: sonnet)
+     - Stale `business-rules.md` → business-rules teammate (model: haiku)
+     - Stale `contract-drift.md` → contracts teammate (model: haiku)
+   - Update `.gsd-t/scan/.cache.json` after refresh
+   - Update `.gsd-t/techdebt.md` — mark any items resolved during this milestone as `[RESOLVED]`
+3. If all dimensions are fresh → skip with log: "Scan docs are fresh — no checkpoint refresh needed"
+
+If `.gsd-t/scan/` doesn't exist → skip (no scan data to maintain).
+
 ## Step 9: Document Ripple
 
 Before creating the git tag, verify all documentation is up to date:

package/commands/gsd-t-debug.md

@@ -262,6 +262,18 @@ After fixing, assess what documentation was affected by the change and update AL
 9. **Domain `tasks.md`** — If the bug was in an active milestone, update task status or add a remediation task
 10. **`CLAUDE.md`** — Did the fix establish a new convention or pattern that future work should follow? Add it
 
+### Scan Doc Micro-Update (if `.gsd-t/scan/` exists):
+Patch structural metadata in scan docs so they stay fresh between full scans. Near-zero cost — no LLM re-analysis.
+
+For each scan doc that exists, apply only the relevant patches:
+- **`.gsd-t/scan/architecture.md`** — Update file/directory counts if the fix added/removed files
+- **`.gsd-t/scan/quality.md`** — Mark resolved TODOs/FIXMEs, update test counts if tests were added
+- **`.gsd-t/scan/security.md`** — If the bug was a security issue, mark the finding `[RESOLVED]`
+- **`.gsd-t/scan/business-rules.md`** — If the fix changed validation/auth/workflow logic, update the rule
+- **`.gsd-t/scan/contract-drift.md`** — If contracts were updated as part of the fix, mark resolved drift items
+
+Skip scan docs not affected by this fix. Skip analytical sections — those require a full scan.
+
 ### Skip what's not affected — don't update docs for the sake of updating them.
 
 ## Step 5: Test Verification (run tests confirming fix)

package/commands/gsd-t-execute.md

@@ -259,6 +259,18 @@ Execute modifies source code, so the Pre-Commit Gate (referenced in Step 9) cove
 4. **`docs/architecture.md`** — Did a task add/change a component or data flow? Update it
 5. **`.gsd-t/techdebt.md`** — Did a task resolve a debt item? Mark it done. Did it reveal new debt? Add it
 
+### Scan Doc Micro-Update (if `.gsd-t/scan/` exists):
+After all tasks complete, patch structural metadata in scan docs so they stay fresh between full scans. This is near-zero cost — no LLM re-analysis, just updating counts and lists from code.
+
+For each scan doc that exists, apply only the relevant patches:
+- **`.gsd-t/scan/architecture.md`** — Update file/directory counts, add new files/modules created during execution
+- **`.gsd-t/scan/quality.md`** — Mark resolved TODOs/FIXMEs, update test counts (run `grep -rc "test\|it\|describe" tests/` or equivalent), append new files to Consumer Surfaces table if applicable
+- **`.gsd-t/scan/security.md`** — If a security finding was fixed during execution, mark it `[RESOLVED]`
+- **`.gsd-t/scan/business-rules.md`** — Append any new validation/auth/workflow rules added during execution
+- **`.gsd-t/scan/contract-drift.md`** — If contracts were updated, mark resolved drift items
+
+Skip any scan doc that wasn't affected by the executed tasks. Skip analytical sections (assessments, recommendations) — those require a full scan to update.
+
 $ARGUMENTS
 
 ## Auto-Clear

package/commands/gsd-t-feature.md

@@ -2,6 +2,24 @@
 
 You are the lead agent planning a significant new feature for an existing codebase. Unlike `/user:gsd-t-project` (greenfield), this command respects and builds on what already exists — existing patterns, schema, auth, conventions, and contracts.
 
+## Step 0.5: Scan Freshness Auto-Refresh
+
+Before reading scan data for impact analysis, check if scan docs are stale and auto-refresh if needed. This ensures feature planning is based on current code — no warnings, no user involvement.
+
+If `.gsd-t/scan/.cache.json` exists:
+1. Read the cache and check `scannedAt` for each dimension
+2. Count commits since the scan: `git rev-list --count --after="{scannedAt}" HEAD`
+3. If **>10 commits since scan** OR **scan is older than 14 days**:
+   - Log: "Auto-refreshing scan docs (stale by {N} commits / {N} days)..."
+   - Re-run only the stale dimensions by spawning the relevant scan teammates:
+     - If `quality.md` stale → spawn quality teammate (model: sonnet)
+     - If `architecture.md` stale → spawn architecture teammate (model: haiku)
+     - If `security.md` stale → spawn security teammate (model: sonnet)
+   - Update `.gsd-t/scan/.cache.json` after refresh
+4. If fresh → proceed silently
+
+If `.gsd-t/scan/` doesn't exist at all → skip (no scan data to refresh).
+
 ## Step 1: Understand What Exists
 
 Read everything:

package/commands/gsd-t-gap-analysis.md

@@ -2,6 +2,23 @@
 
 You are performing a gap analysis between a provided specification and the existing codebase. The user pastes requirements or a spec, and you systematically identify what's done, what's partial, what's wrong, and what's missing.
 
+## Step 0.5: Scan Freshness Auto-Refresh
+
+Before reading scan data for gap classification, check if scan docs are stale and auto-refresh if needed. This ensures gap analysis is based on current code — no warnings, no user involvement.
+
+If `.gsd-t/scan/.cache.json` exists:
+1. Read the cache and check `scannedAt` for each dimension
+2. Count commits since the scan: `git rev-list --count --after="{scannedAt}" HEAD`
+3. If **>10 commits since scan** OR **scan is older than 14 days**:
+   - Log: "Auto-refreshing scan docs (stale by {N} commits / {N} days)..."
+   - Re-run only the stale dimensions by spawning the relevant scan teammates:
+     - If `architecture.md` stale → spawn architecture teammate (model: haiku)
+     - If `quality.md` stale → spawn quality teammate (model: sonnet)
+   - Update `.gsd-t/scan/.cache.json` after refresh
+4. If fresh → proceed silently
+
+If `.gsd-t/scan/` doesn't exist at all → skip (no scan data to refresh).
+
 ## Step 1: Load Context
 
 Read (if they exist):

package/commands/gsd-t-partition.md

@@ -2,6 +2,23 @@
 
 You are the lead agent in a contract-driven development workflow. Your job is to decompose the current milestone into independent domains with explicit boundaries and contracts.
 
+## Step 0.5: Scan Freshness Auto-Refresh
+
+Before reading scan data, check if scan docs are stale and auto-refresh if needed. This ensures partition decisions are based on current code — no warnings, no user involvement.
+
+If `.gsd-t/scan/.cache.json` exists:
+1. Read the cache and check `dimensions.quality.scannedAt` and `dimensions.architecture.scannedAt`
+2. Count commits since the scan: `git rev-list --count --after="{scannedAt}" HEAD`
+3. If **>10 commits since scan** OR **scan is older than 14 days**:
+   - Log: "Auto-refreshing scan docs (stale by {N} commits / {N} days)..."
+   - Re-run only the stale dimensions by spawning the relevant scan teammates:
+     - If `quality.md` stale → spawn quality teammate (model: sonnet)
+     - If `architecture.md` stale → spawn architecture teammate (model: haiku)
+   - Update `.gsd-t/scan/.cache.json` after refresh
+4. If fresh → proceed silently
+
+If `.gsd-t/scan/` doesn't exist at all → skip (no scan data to refresh).
+
 ## Step 1: Understand the Project
 
 Read these files in order:

package/commands/gsd-t-quick.md

@@ -100,6 +100,18 @@ If `.gsd-t/progress.md` exists, assess what documentation was affected and updat
 8. **`.gsd-t/techdebt.md`** — Did this task resolve a debt item? Mark it done. Did it reveal new debt? Add it
 9. **`CLAUDE.md`** — Did this task establish a convention future work should follow? Add it
 
+### Scan Doc Micro-Update (if `.gsd-t/scan/` exists):
+Patch structural metadata in scan docs so they stay fresh between full scans. Near-zero cost — no LLM re-analysis.
+
+For each scan doc that exists, apply only the relevant patches:
+- **`.gsd-t/scan/architecture.md`** — Update file/directory counts, add new files/modules created
+- **`.gsd-t/scan/quality.md`** — Mark resolved TODOs/FIXMEs, update test counts, append new files to Consumer Surfaces if applicable
+- **`.gsd-t/scan/security.md`** — If a security finding was fixed, mark it `[RESOLVED]`
+- **`.gsd-t/scan/business-rules.md`** — Append any new validation/auth/workflow rules added
+- **`.gsd-t/scan/contract-drift.md`** — If contracts were updated, mark resolved drift items
+
+Skip scan docs not affected by this task. Skip analytical sections — those require a full scan.
+
 ### Skip what's not affected — most quick tasks will only touch 1-2 of these.
 
 ## Step 5: Test & Verify (MANDATORY)

package/commands/gsd-t-scan.md

@@ -497,6 +497,50 @@ After updating living documents, verify nothing was broken:
 2. **Verify passing**: If any tests fail that were passing before the scan began, investigate and fix
 3. **Log test baseline**: Record the current test state in `.gsd-t/scan/test-baseline.md` — this gives future milestones a starting point
 
+## Step 6.5: Generate Scan Freshness Cache
+
+After the scan completes and living docs are updated, generate a hash cache so downstream commands can detect staleness without re-scanning.
+
+Create `.gsd-t/scan/.cache.json` with this structure:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const root = process.argv[1];
+const scanDir = path.join(root, '.gsd-t', 'scan');
+
+// Hash all source files that affect each scan dimension
+const dimensions = {
+  architecture: ['**/*.js', '**/*.ts', '**/*.py', '**/*.json', '**/package.json', '**/tsconfig.json'],
+  quality: ['**/*.js', '**/*.ts', '**/*.py', '**/*.test.*', '**/*.spec.*'],
+  security: ['**/*.js', '**/*.ts', '**/*.py', '**/*.env*', '**/package.json', '**/package-lock.json'],
+  'business-rules': ['**/*.js', '**/*.ts', '**/*.py'],
+  'contract-drift': ['.gsd-t/contracts/**']
+};
+
+// For each dimension, hash the scan doc itself to track its version
+const cache = { generated: new Date().toISOString(), dimensions: {} };
+for (const [dim, _patterns] of Object.entries(dimensions)) {
+  const scanFile = path.join(scanDir, dim + '.md');
+  if (fs.existsSync(scanFile)) {
+    const content = fs.readFileSync(scanFile, 'utf8');
+    cache.dimensions[dim] = {
+      scanHash: crypto.createHash('md5').update(content).digest('hex'),
+      scannedAt: new Date().toISOString()
+    };
+  }
+}
+
+fs.writeFileSync(path.join(scanDir, '.cache.json'), JSON.stringify(cache, null, 2));
+console.log('Scan cache generated:', Object.keys(cache.dimensions).length, 'dimensions cached');
+" "$PROJECT_ROOT"
+```
+
+This cache enables downstream commands (`partition`, `feature`, `gap-analysis`) to check scan freshness and auto-refresh stale dimensions before consuming scan data.
+
 ## Step 7: Update Project State
 
 If `.gsd-t/progress.md` exists:

package/docs/neo4j-setup.md

@@ -150,11 +150,34 @@ docker volume rm neo4j_data neo4j_logs
 | `docker: command not found` | Install Docker Desktop |
 | Container not starting | Check `docker logs gsd-t-neo4j` for errors |
 | CGC MCP `add_code_to_graph` fails on Windows | Known CGC 0.3.1 bug — use `cgc index .` CLI instead |
+| `UnicodeEncodeError: 'charmap'` on Windows | CGC crashes on emoji/Unicode in source code. Fix: `set PYTHONIOENCODING=utf-8` before running `cgc index`, or use `PYTHONIOENCODING=utf-8 cgc index .` in bash. GSD-T's auto-sync sets this automatically. |
 | 0 entities indexed | Project may be docs-only (no `.js`/`.ts`/`.py` files) |
+| Very few entities (e.g., 1 function for a large project) | CGC likely crashed mid-index on a file with special characters. Force re-index with UTF-8: `PYTHONIOENCODING=utf-8 cgc index . --force` |
 | Neo4j connection refused | Ensure container is running: `docker start gsd-t-neo4j` |
+| `[GSD-T] CGC sync FAILED` warning | Auto-sync tried twice and failed. Run the manual fix command shown in the warning message. Check that Neo4j container is running and CGC is installed. |
 
 ## Known Limitations
 
-- **CGC 0.3.1 Windows bug:** The `add_code_to_graph` MCP tool call passes `None` for the directory parameter on Windows. Use `cgc index <path>` CLI as a workaround.
+- **CGC 0.3.1 Windows bugs:**
+  - The `add_code_to_graph` MCP tool call passes `None` for the directory parameter on Windows. GSD-T uses `cgc index` CLI as a workaround.
+  - CGC crashes with `UnicodeEncodeError` when source files contain emoji or non-ASCII characters on Windows. GSD-T sets `PYTHONIOENCODING=utf-8` automatically. For manual CLI use, prefix commands with `PYTHONIOENCODING=utf-8`.
 - **Language support:** Native indexer supports JS/TS/Python. CGC supports JS/TS/Python plus additional languages via Tree-sitter.
 - **Docs-only projects:** Projects without source code files produce 0 entities — this is expected behavior, not an error.
+
+## Auto-Sync Error Handling
+
+GSD-T's graph auto-sync (v2.39.11+) does not silently ignore failures. When CGC sync fails:
+
+1. **Attempt 1:** Normal `cgc index` with UTF-8 encoding
+2. **Attempt 2:** Force re-index (`cgc index --force`) to recover from corrupt state
+3. **If both fail:** Warns the user with the error, impact, and fix command
+
+You will see a message like:
+```
+[GSD-T] ⚠ CGC sync FAILED for C:\Users\david\MyProject
+  Error: UnicodeEncodeError: 'charmap' codec can't encode character...
+  Impact: Neo4j graph is stale — deep call chain analysis may return outdated results
+  Fix: run "cgc index C:\Users\david\MyProject --force" manually
+```
+
+The native JSON index is unaffected by CGC failures — it always updates successfully.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.39.11",
+  "version": "2.39.13",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 49 slash commands with graph-powered code analysis, real-time agent dashboard, execution intelligence, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",