@tekyzinc/gsd-t 2.39.13 → 2.46.11

package/bin/rule-engine.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Declarative Rule Engine — Pattern detection via JSONL rules
+ *
+ * Loads rules from .gsd-t/metrics/rules.jsonl, evaluates them against
+ * task-metrics data, manages activation tracking and rule lifecycle.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+module.exports = {
+  getActiveRules, evaluateRules, getPreMortemRules, getPatchTemplate,
+  recordActivation, flagInactiveRules, consolidateRules,
+};
+
+// ── getActiveRules ───────────────────────────────────────────────────────────
+
+/** @param {string} [projectDir] @returns {object[]} Active rules */
+function getActiveRules(projectDir) {
+  return loadJsonl(rulesPath(projectDir)).filter((r) => r.status === "active");
+}
+
+// ── evaluateRules ────────────────────────────────────────────────────────────
+
+/** @param {string} domain @param {object} [opts] @returns {object[]} Matches */
+function evaluateRules(domain, opts) {
+  const o = opts || {};
+  const dir = o.projectDir || process.cwd();
+  const rules = getActiveRules(dir);
+  const { readTaskMetrics } = require("./metrics-collector.js");
+  const filters = o.milestone ? { milestone: o.milestone } : {};
+  const allRecs = readTaskMetrics(filters, dir);
+  const domRecs = allRecs.filter((r) => r.domain === domain);
+  const matches = [];
+  for (const rule of rules) {
+    const win = rule.trigger.window || 0;
+    const scope = rule.trigger.scope || "domain";
+    let recs;
+    if (scope === "global") recs = win > 0 ? allRecs.slice(-win) : allRecs;
+    else if (scope === "milestone") {
+      recs = allRecs.filter((r) => r.milestone === o.milestone);
+      if (win > 0) recs = recs.slice(-win);
+    } else recs = win > 0 ? domRecs.slice(-win) : domRecs;
+    if (recs.length === 0) continue;
+    const matched = evalTrigger(rule.trigger, recs);
+    if (matched.length > 0) matches.push({ rule, matchedRecords: matched, severity: rule.severity });
+  }
+  return matches;
+}
+
+// ── getPreMortemRules ────────────────────────────────────────────────────────
+
+/** @param {string} domainType @param {string} [projectDir] @returns {object[]} */
+function getPreMortemRules(domainType, projectDir) {
+  return getActiveRules(projectDir || process.cwd()).filter((r) => r.activation_count > 0);
+}
+
+// ── getPatchTemplate ─────────────────────────────────────────────────────────
+
+/** @param {string} templateId @param {string} [projectDir] @returns {object|null} */
+function getPatchTemplate(templateId, projectDir) {
+  return loadJsonl(templatesPath(projectDir)).find((t) => t.id === templateId) || null;
+}
+
+// ── recordActivation ─────────────────────────────────────────────────────────
+
+/** @param {string} ruleId @param {string} [projectDir] */
+function recordActivation(ruleId, projectDir) {
+  const fp = rulesPath(projectDir);
+  const rules = loadJsonl(fp);
+  const r = rules.find((x) => x.id === ruleId);
+  if (!r) return;
+  r.activation_count = (r.activation_count || 0) + 1;
+  r.last_activated = new Date().toISOString();
+  atomicWriteJsonl(fp, rules);
+}
+
+// ── flagInactiveRules ────────────────────────────────────────────────────────
+
+/** @param {number} threshold @param {string} [projectDir] @returns {object[]} */
+function flagInactiveRules(threshold, projectDir) {
+  const rules = loadJsonl(rulesPath(projectDir));
+  return rules.filter((r) => {
+    if (r.status !== "active" || r.activation_count > 0) return false;
+    const num = parseMilestoneNum(r.milestone_created);
+    if (num === null) return false;
+    // Compare against highest milestone number among all rules as proxy for "current"
+    const maxM = rules.reduce((m, x) => Math.max(m, parseMilestoneNum(x.milestone_created) || 0), 0);
+    return (maxM - num) >= threshold;
+  });
+}
+
+// ── consolidateRules ─────────────────────────────────────────────────────────
+
+/** @param {string[]} ruleIds @param {object} consolidated @param {string} [projectDir] */
+function consolidateRules(ruleIds, consolidated, projectDir) {
+  const fp = rulesPath(projectDir);
+  const rules = loadJsonl(fp);
+  for (const rule of rules) { if (ruleIds.includes(rule.id)) rule.status = "consolidated"; }
+  rules.push(consolidated);
+  atomicWriteJsonl(fp, rules);
+}
+
+// ── Trigger evaluation ───────────────────────────────────────────────────────
+
+function evalTrigger(trigger, records) {
+  const { metric, operator, threshold } = trigger;
+  if (operator === "pattern_count") {
+    const m = records.filter((r) => fieldVal(r, metric) != null);
+    return m.length >= threshold ? m : [];
+  }
+  return records.filter((r) => {
+    const v = fieldVal(r, metric);
+    return v != null && cmp(v, operator, threshold);
+  });
+}
+
+function cmp(v, op, t) {
+  switch (op) {
+    case "gt": return v > t;   case "gte": return v >= t;
+    case "lt": return v < t;   case "lte": return v <= t;
+    case "eq": return v === t;  case "neq": return v !== t;
+    case "in": return Array.isArray(t) && t.includes(v);
+    default: return false;
+  }
+}
+
+function fieldVal(rec, metric) {
+  return metric === "first_pass_rate" ? (rec.pass ? 1 : 0) : rec[metric];
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function rulesPath(d) { return path.join(d || process.cwd(), ".gsd-t", "metrics", "rules.jsonl"); }
+function templatesPath(d) { return path.join(d || process.cwd(), ".gsd-t", "metrics", "patch-templates.jsonl"); }
+
+function loadJsonl(fp) {
+  if (!fs.existsSync(fp)) return [];
+  const c = fs.readFileSync(fp, "utf8").trim();
+  return c ? c.split("\n").map(safeParse).filter(Boolean) : [];
+}
+
+function safeParse(l) { try { return JSON.parse(l); } catch { return null; } }
+
+function atomicWriteJsonl(fp, records) {
+  const dir = path.dirname(fp);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = fp + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, records.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  fs.renameSync(tmp, fp);
+}
+
+function parseMilestoneNum(s) {
+  const m = (s || "").match(/M(\d+)/);
+  return m ? parseInt(m[1], 10) : null;
+}

package/commands/desktop.ini

@@ -0,0 +1,2 @@
+[.ShellClassInfo]
+IconResource=C:\Program Files\Google\Drive File Stream\122.0.1.0\GoogleDriveFS.exe,27

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

@@ -3,7 +3,8 @@
 You are finalizing a completed milestone. Your job is to archive the milestone documentation, create a git tag, and prepare for the next milestone.
 
 This command is:
-- **Auto-invoked** at the end of `/user:gsd-t-wave` after verify passes
+- **Auto-invoked** by `/user:gsd-t-verify` (Step 8) after all quality gates pass — at ALL autonomy levels
+- **Auto-invoked** by `/user:gsd-t-wave` as part of the VERIFY+COMPLETE phase
 - **Standalone** when user wants to manually close a milestone
 
 ## Step 1: Verify Completion
@@ -50,6 +51,58 @@ Do not proceed to archiving. Create the smoke test now, run it, confirm it passe
 
 > This gate exists because complete-milestone is the last opportunity to catch "shipped blind" features before they become user-facing bugs requiring 15 debug sessions to resolve.
 
+## Step 1.75: Goal-Backward Verification Gate (MANDATORY)
+
+Before archiving, verify that milestone goals are actually achieved end-to-end — not just structurally present. This catches placeholder implementations that passed all quality gates.
+
+Refer to `.gsd-t/contracts/goal-backward-contract.md` for the full verification flow, placeholder patterns, and findings report format.
+
+### 1.75.1 Check for Existing Goal-Backward Results
+
+1. Read `.gsd-t/verify-report.md` — check if it contains a `Goal-Backward:` line
+2. If the verify-report already shows `Goal-Backward: PASS` or `Goal-Backward: WARN` (no CRITICAL/HIGH), skip to Step 2
+3. If no goal-backward results exist, or verify was run without this step, execute the full goal-backward check now (follow the same logic as `gsd-t-verify.md` Step 5.5)
+
+### 1.75.2 Evaluate Goal-Backward Status
+
+**If CRITICAL or HIGH findings exist:**
+- Display findings report to user in the contract format
+- **BLOCK milestone completion** — do not proceed to archiving
+- Prompt:
+  ```
+  ⛔ Goal-Backward Verification FAILED — milestone completion blocked.
+
+  Findings:
+  {findings table}
+
+  Options:
+  1. Fix the findings and re-run /user:gsd-t-verify
+  2. Override with explicit acknowledgment: re-run this command with --force-goal-backward
+
+  Proceed with option 1 (recommended) or acknowledge to force completion?
+  ```
+- If user provides `--force-goal-backward` flag or explicit acknowledgment: log the override and proceed with warning
+- Log to `.gsd-t/progress.md` Decision Log:
+  ```
+  - {date}: [goal-backward-override] Milestone "{name}" completed with unresolved goal-backward findings — user acknowledged. Findings: {summary}
+  ```
+
+**If only MEDIUM findings (warnings):**
+- Log findings to `.gsd-t/progress.md` Decision Log:
+  ```
+  - {date}: [goal-backward-warn] Goal-backward check found {N} medium findings before milestone archive — {summary}. Not blocking.
+  ```
+- Proceed to Step 2
+
+**If PASS (no findings):**
+- Log to `.gsd-t/progress.md` Decision Log:
+  ```
+  - {date}: [goal-backward-pass] Goal-backward verification passed — {N} requirements checked, no placeholder patterns found
+  ```
+- Proceed to Step 2
+
+---
+
 ## Step 2: Gap Analysis Gate
 
 After verification passes, run a gap analysis against `docs/requirements.md` scoped to this milestone's deliverables:
@@ -85,7 +138,112 @@ Before archiving, extract learning from the event stream to improve future runs.
    - If approved: append the rule to CLAUDE.md under the relevant section
    - Write event: `node ~/.claude/scripts/gsd-t-event-writer.js --type distillation --command gsd-t-complete-milestone --reasoning "{rule}" --outcome success || true`
 
-5. If no patterns found (fewer than 3 occurrences): log "Distillation complete — no repeating patterns found", continue to Step 3
+5. If no patterns found (fewer than 3 occurrences): log "Distillation complete — no repeating patterns found"
+
+### Step 2.5b: Rule Engine Distillation
+
+After event-stream pattern detection, run rule-based distillation using the declarative rule engine and patch lifecycle:
+
+1. **Rule Evaluation**: Run via Bash:
+   `node -e "const re = require('./bin/rule-engine.js'); const domains = [/* list milestone domain names */]; domains.forEach(d => { const m = re.evaluateRules(d, { projectDir: '.', milestone: '{milestone-id}' }); m.forEach(x => { console.log('FIRED: ' + x.rule.id + ' — ' + x.rule.name + ' [' + x.severity + ']'); re.recordActivation(x.rule.id, '.'); }); });" 2>/dev/null || true`
+
+2. **Patch Candidate Generation**: For each fired rule with `action: 'patch'`, run via Bash:
+   `node -e "const re = require('./bin/rule-engine.js'); const pl = require('./bin/patch-lifecycle.js'); const fired = [/* rule IDs from step 1 */]; fired.forEach(ruleId => { const rule = re.getActiveRules('.').find(r => r.id === ruleId); if(rule && rule.action === 'patch' && rule.patch_template_id) { const p = pl.createCandidate(ruleId, rule.patch_template_id, 0, '.'); console.log('CANDIDATE: ' + p.id + ' from ' + ruleId); } });" 2>/dev/null || true`
+
+3. **Promotion Gate Check**: For all applied/measured patches, run via Bash:
+   `node -e "const pl = require('./bin/patch-lifecycle.js'); ['applied','measured'].forEach(s => { pl.getPatchesByStatus(s, '.').forEach(p => { const g = pl.checkPromotionGate(p.id, '.'); if(g.passes) { pl.promote(p.id, '.'); console.log('PROMOTED: ' + p.id); } else if(p.measured_milestones && p.measured_milestones.length >= 2) { pl.deprecate(p.id, g.reason, '.'); console.log('DEPRECATED: ' + p.id + ' — ' + g.reason); } }); });" 2>/dev/null || true`
+
+4. **Graduation**: For promoted patches sustained 3+ milestones, run via Bash:
+   `node -e "const pl = require('./bin/patch-lifecycle.js'); pl.getPatchesByStatus('promoted', '.').forEach(p => { const r = pl.graduate(p.id, '.'); if(r.target) console.log('GRADUATED: ' + p.id + ' → ' + r.target); });" 2>/dev/null || true`
+
+5. **Consolidation & Deprecation**: Run via Bash:
+   `node -e "const re = require('./bin/rule-engine.js'); const f = re.flagInactiveRules(5, '.'); if(f.length) f.forEach(r => console.log('INACTIVE: ' + r.id + ' — no activations in 5+ milestones'));" 2>/dev/null || true`
+
+6. **Quality Budget Governance**: Compute rework percentage from task-metrics. Run via Bash:
+   `node -e "const mc = require('./bin/metrics-collector.js'); const recs = mc.readTaskMetrics({ milestone: '{milestone-id}' }, '.'); if(recs.length) { const rework = recs.filter(r => r.fix_cycles > 0).length; const pct = (rework/recs.length*100).toFixed(1); console.log('Rework: ' + pct + '% (' + rework + '/' + recs.length + ')'); if(pct > 20) console.log('⚠️ REWORK CEILING EXCEEDED — triggering constraint tightening for next milestone'); }" 2>/dev/null || true`
+
+   When rework ceiling (20%) exceeded: log warning and note that next milestone should: force discuss phase, require contract review, split large tasks.
+
+### Step 2.5c: Global Rule Promotion
+
+After local rule promotion completes, propagate newly promoted rules to global metrics:
+
+1. **Check for promoted rules**: Run via Bash:
+   ```bash
+   node -e "const pl = require('./bin/patch-lifecycle.js'); const promoted = pl.getPatchesByStatus('promoted', '.'); console.log(JSON.stringify(promoted.map(p => ({ id: p.id, rule_id: p.rule_id, template_id: p.template_id }))));" 2>/dev/null || true
+   ```
+
+2. **Copy promoted rules to global**: For each promoted rule, run via Bash:
+   ```bash
+   node -e "
+     const gsm = require('./bin/global-sync-manager.js');
+     const re = require('./bin/rule-engine.js');
+     const pl = require('./bin/patch-lifecycle.js');
+     const promoted = pl.getPatchesByStatus('promoted', '.');
+     let count = 0;
+     for (const p of promoted) {
+       const rule = re.getActiveRules('.').find(r => r.id === p.rule_id);
+       if (!rule) continue;
+       const written = gsm.writeGlobalRule({
+         id: rule.id,
+         original_rule: rule,
+         source_project: (() => { try { return require('./package.json').name; } catch { return require('path').basename(process.cwd()); } })(),
+         source_project_dir: process.cwd(),
+       });
+       gsm.checkUniversalPromotion(written.global_id);
+       count++;
+     }
+     if (count > 0) console.log('Promoted ' + count + ' rules to global metrics');
+   " 2>/dev/null || true
+   ```
+
+3. **Write global rollup entry**: Run via Bash:
+   ```bash
+   node -e "
+     const gsm = require('./bin/global-sync-manager.js');
+     const mc = require('./bin/metrics-collector.js');
+     const mr = require('./bin/metrics-rollup.js');
+     const name = (() => { try { return require('./package.json').name; } catch { return require('path').basename(process.cwd()); } })();
+     const rollups = mr.readRollups({}, '.');
+     const latest = rollups.length > 0 ? rollups[rollups.length - 1] : null;
+     if (latest) {
+       gsm.writeGlobalRollup({
+         source_project: name, source_project_dir: process.cwd(),
+         milestone: latest.milestone, version: latest.version,
+         total_tasks: latest.total_tasks, first_pass_rate: latest.first_pass_rate,
+         avg_duration_s: latest.avg_duration_s, total_fix_cycles: latest.total_fix_cycles,
+         total_tokens: latest.total_tokens, elo_after: latest.elo_after,
+         signal_distribution: latest.signal_distribution,
+         domain_breakdown: latest.domain_breakdown,
+       });
+       console.log('Updated global rollup for ' + name);
+     }
+   " 2>/dev/null || true
+   ```
+
+4. **Write global signal distribution**: Run via Bash:
+   ```bash
+   node -e "
+     const gsm = require('./bin/global-sync-manager.js');
+     const mc = require('./bin/metrics-collector.js');
+     const name = (() => { try { return require('./package.json').name; } catch { return require('path').basename(process.cwd()); } })();
+     const allRecs = mc.readTaskMetrics({}, '.');
+     if (allRecs.length === 0) { process.exit(0); }
+     const counts = {};
+     allRecs.forEach(r => { counts[r.signal_type] = (counts[r.signal_type] || 0) + 1; });
+     const total = allRecs.length;
+     const rates = {};
+     for (const [k, v] of Object.entries(counts)) { rates[k] = Math.round(v / total * 1000) / 1000; }
+     gsm.writeGlobalSignalDistribution({
+       source_project: name, source_project_dir: process.cwd(),
+       total_tasks: total, signal_counts: counts, signal_rates: rates,
+       domain_type_signals: [],
+     });
+     console.log('Updated global signal distribution for ' + name);
+   " 2>/dev/null || true
+   ```
+
+5. If no rules were promoted this milestone: skip silently (steps 3-4 still run for rollup/signal tracking).
 
 ## Step 3: Gather Milestone Artifacts
 
@@ -233,6 +391,32 @@ If `.gsd-t/scan/` exists (a prior scan has been run):
 
 If `.gsd-t/scan/` doesn't exist → skip (no scan data to maintain).
 
+## Step 8.7: Generate Metrics Rollup
+
+Generate milestone-level metrics aggregation and ELO score:
+
+1. Run via Bash:
+   `node bin/metrics-rollup.js {milestone-id} {version} 2>/dev/null`
+2. If rollup succeeds, display:
+   ```
+   ## Process Metrics — {milestone}
+   - ELO: {elo_before} → {elo_after} ({elo_delta > 0 ? '+' : ''}{elo_delta})
+   - First-pass rate: {first_pass_rate * 100}%
+   - Tasks: {total_tasks} | Fix cycles: {total_fix_cycles}
+   - Avg duration: {avg_duration_s}s | Avg context: {avg_context_pct}%
+   ```
+3. If `trend_delta` is present (previous milestone exists), display:
+   ```
+   Trend vs previous: first-pass rate {delta > 0 ? '↑' : '↓'} {delta}%, duration {delta}s
+   ```
+4. If `heuristic_flags` has entries, display as warnings:
+   ```
+   ⚠️ Heuristic: {heuristic} ({severity}) — {description}
+   ```
+5. If rollup fails (no task-metrics data): log "No task-metrics found — rollup skipped" and continue.
+
+Include ELO score in the milestone summary (Step 5) and git tag message (Step 11).
+
 ## Step 9: Document Ripple
 
 Before creating the git tag, verify all documentation is up to date:
@@ -255,11 +439,15 @@ Before creating the git tag, verify all documentation is up to date:
 
 Verify the milestone is truly complete:
 
-1. **Run the full test suite**: Execute ALL tests — unit, integration, and E2E
-2. **Run Playwright E2E** (if configured): Detect `playwright.config.*` or Playwright in dependencies. If present, run the full Playwright suite. If specs are missing or stale, invoke `gsd-t-test-sync` first.
-3. **Verify all pass**: Every test must pass. If any fail, fix before tagging (up to 2 attempts)
+1. **Run ALL configured test suites** — detect and run every one:
+   a. Unit/integration tests (vitest/jest/mocha)
+   b. If `playwright.config.*` exists → run `npx playwright test` (full suite). Unit tests alone are NEVER sufficient when E2E exists.
+   c. If specs are missing or stale, invoke `gsd-t-test-sync` first.
+   d. Report: "Unit: X/Y pass | E2E: X/Y pass"
+2. **Verify all pass**: Every test must pass. If any fail, fix before tagging (up to 2 attempts)
+3. **Functional test quality gate**: Read every Playwright spec. Verify assertions check **functional behavior** (state changed after action, data loaded, content updated, widget responded to input) — NOT just element existence (`isVisible`, `toBeAttached`, `toBeEnabled`). Shallow tests that would pass on an empty HTML page with the right element IDs are a milestone completion FAIL. Flag and rewrite before proceeding.
 4. **Compare to baseline**: If a test baseline was recorded at milestone start, verify coverage has improved or at minimum not regressed
-5. **Log test results**: Include test pass/fail counts in the milestone summary (Step 4)
+5. **Log test results**: Include test pass/fail counts and shallow test audit results in the milestone summary (Step 4)
 
 ## Step 11: Create Git Tag
 

package/commands/gsd-t-debug.md

@@ -281,13 +281,48 @@ Skip scan docs not affected by this fix. Skip analytical sections — those requ
 Before committing, ensure the fix is solid:
 
 1. **Update tests**: If the bug reveals a missing test case, add one that would have caught it
-2. **Run affected tests**: Execute all tests related to the changed files and domain
+2. **Run ALL configured test suites** — this is NOT optional:
+   a. Detect all runners: check for vitest/jest config, playwright.config.*, cypress.config.*
+   b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
+   c. If `playwright.config.*` exists → run `npx playwright test` (full suite)
+   d. Report ALL results: "Unit: X/Y pass | E2E: X/Y pass"
 3. **Verify passing**: All tests must pass. If any fail, fix before proceeding (up to 2 attempts)
-4. **Run E2E tests**: If the fix changed UI, routes, or user flows and an E2E framework exists, run affected specs
-5. **Regression check**: Confirm the fix doesn't break any adjacent functionality
+4. **If the project has a UI but no E2E specs cover the fixed area**: WRITE THEM.
+5. **Functional test quality**: Every E2E assertion must verify an action produced the correct outcome (state changed, data loaded, content updated) — not just that elements exist. Tests that only check `isVisible`/`toBeEnabled` are shallow layout tests and don't catch real bugs. If a test would pass on an empty HTML page with the right IDs, rewrite it.
+6. **Regression check**: Confirm the fix doesn't break any adjacent functionality
 
 Commit: `[debug] Fix {description} — root cause: {explanation}`
 
+## Step 5.5: Emit Task Metrics
+
+After committing, emit a task-metrics record for this debug session — run via Bash:
+`node bin/metrics-collector.js --milestone {current-milestone-or-none} --domain {domain-or-debug} --task debug-{timestamp} --command debug --duration_s {elapsed} --tokens_used {estimated} --context_pct ${CTX_PCT:-0} --pass {true|false} --fix_cycles {attempts} --signal_type debug-invoked --notes "[debug] {description}" 2>/dev/null || true`
+
+Signal type is always `debug-invoked` for debug sessions.
+
+Emit task_complete event — run via Bash:
+`node ~/.claude/scripts/gsd-t-event-writer.js --type task_complete --command gsd-t-debug --reasoning "signal_type=debug-invoked, domain={domain}" --outcome {success|failure} || true`
+
+## Step 6: Doc-Ripple (Automated)
+
+After all work is committed but before reporting completion:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: debug
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 $ARGUMENTS
 
 ## Auto-Clear

package/commands/gsd-t-doc-ripple.md

@@ -0,0 +1,148 @@
+# GSD-T: Doc-Ripple — Automated Document Ripple Enforcement
+
+You are the doc-ripple agent. You identify and update all downstream documents after code changes. You are spawned by execute, integrate, quick, debug, and wave after primary work is committed.
+
+## Step 1: Load Context
+
+Read:
+1. `CLAUDE.md` — project conventions and Pre-Commit Gate (project-specific extensions)
+2. `.gsd-t/contracts/doc-ripple-contract.md` — trigger conditions, manifest format, update protocol
+3. `.gsd-t/contracts/pre-commit-gate.md` — the gate checklist you cross-reference
+
+Run via Bash:
+`git diff --name-only HEAD~1 2>/dev/null || git diff --cached --name-only`
+
+Store the changed file list for Steps 2–3.
+
+## Step 2: Threshold Check
+
+Evaluate the changed file list against trigger conditions from `doc-ripple-contract.md`.
+
+Output exactly:
+```
+DOC-RIPPLE THRESHOLD: {FIRE|SKIP}
+  Files changed: {N} across {N} directories
+  Cross-cutting signals: {list or "none"}
+  Reason: {brief explanation}
+```
+
+**If SKIP**: log the decision, output `Doc-ripple: SKIP — {reason}`, and stop. No manifest. No updates.
+
+**If FIRE**: proceed to Step 3.
+
+## Step 3: Blast Radius Analysis
+
+For each changed file, classify its type: source, test, contract, template, command, doc, config.
+
+Cross-reference `.gsd-t/contracts/pre-commit-gate.md` gate checklist:
+- API endpoint/shape changed → api-contract.md, Swagger spec, CLAUDE.md, README.md
+- Database schema changed → schema-contract.md, docs/schema.md
+- UI component interface changed → component-contract.md
+- New files or directories added → owning domain scope.md
+- Requirement implemented or changed → docs/requirements.md
+- Component or data flow changed → docs/architecture.md
+- Any file modified → .gsd-t/progress.md (Decision Log entry)
+- Architectural decision made → .gsd-t/progress.md (with rationale)
+- Tech debt discovered or fixed → .gsd-t/techdebt.md
+- New convention established → CLAUDE.md or domain constraints.md
+- Command file added/changed → GSD-T-README.md, README.md, templates/CLAUDE-global.md, commands/gsd-t-help.md
+- Command added/removed → all 4 above + package.json version + bin/gsd-t.js count
+- Wave flow changed → gsd-t-wave.md, GSD-T-README.md, README.md
+- Template changed → verify gsd-t-init output
+
+Build the final list: `{ document, status (UPDATED|SKIPPED), action, reason }`.
+
+## Step 4: Generate Manifest
+
+Write `.gsd-t/doc-ripple-manifest.md` (overwrite):
+
+```markdown
+# Doc-Ripple Manifest — {date}
+
+## Trigger
+- Command: {triggering command}
+- Files changed: {N}
+- Threshold: FIRE — {reason}
+
+## Blast Radius
+
+| Document | Status | Action | Reason |
+|----------|--------|--------|--------|
+| {path} | {UPDATED|SKIPPED} | {action} | {reason} |
+
+## Summary
+- Documents checked: {N}
+- Documents updated: {N}
+- Documents skipped (already current): {N}
+```
+
+## Step 5: Update Documents
+
+Count documents marked UPDATED.
+
+**Fewer than 3 updates — inline:**
+For each document: read current content → determine minimal edit → apply via Edit tool (not Write) → verify after edit.
+
+**3 or more updates — parallel subagents:**
+
+For each document or logical group:
+
+⚙ [haiku] gsd-t-doc-ripple → update {document}
+(Use sonnet for docs/architecture.md and docs/requirements.md — these need reasoning.)
+
+**OBSERVABILITY LOGGING (MANDATORY) — for each subagent spawn:**
+
+Before spawning — run via Bash:
+`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
+
+After subagent returns — run via Bash:
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && TOK_END=${CLAUDE_CONTEXT_TOKENS_USED:-0} && DURATION=$((T_END-T_START))`
+
+Compute tokens:
+- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
+- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
+
+Compute context utilization:
+`if [ "${CLAUDE_CONTEXT_TOKENS_MAX:-0}" -gt 0 ]; then CTX_PCT=$(echo "scale=1; ${CLAUDE_CONTEXT_TOKENS_USED:-0} * 100 / ${CLAUDE_CONTEXT_TOKENS_MAX}" | bc); else CTX_PCT="N/A"; fi`
+
+Alert thresholds:
+- CTX_PCT >= 85: `echo "🔴 CRITICAL: Context at ${CTX_PCT}% — compaction likely. Task MUST be split."`
+- CTX_PCT >= 70: `echo "⚠️ WARNING: Context at ${CTX_PCT}% — approaching compaction threshold. Consider splitting."`
+
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-doc-ripple | Step 5 | {model} | {DURATION}s | update:{document} | {TOKENS} | {COMPACTED} | doc-ripple | — | {CTX_PCT} |`
+
+**Each document-update subagent prompt:**
+```
+Task subagent (general-purpose, model: {haiku|sonnet}):
+"Update a single document as part of doc-ripple enforcement.
+
+Document to update: {path}
+Action: {action from manifest}
+Reason: {reason from manifest}
+Git diff context (changed files): {file list}
+
+Instructions:
+1. Read the current document
+2. Apply the minimal edit — add/update only the affected section
+3. Use the Edit tool (not Write) — preserve all existing content
+4. Re-read after edit to confirm correctness
+5. Report: 'Updated {document} — {one-line summary of change}'"
+```
+
+## Step 6: Report Summary
+
+Output:
+```
+Doc-ripple: {N} checked, {N} updated, {N} skipped
+```
+
+List each updated document with a one-line summary of what changed.
+
+If any update failed, list it under `Failures:` and flag for manual review.
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is written to project files. Execute `/clear` to free the context window for the next command.