@tekyzinc/gsd-t 2.39.12 → 2.39.13

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.39.12",
+  "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",