@tekyzinc/gsd-t 2.39.12 → 2.45.11

package/README.md

@@ -2,13 +2,15 @@
 
 A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
-**Solves context rot** — the quality degradation that happens as Claude fills its context window.
-**Enables parallel execution** — contract-driven domains can be worked on simultaneously.
+**Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
+**Safe parallel execution** — worktree isolation gives each domain agent its own filesystem; sequential atomic merges prevent conflicts.
 **Maintains test coverage** — automatically keeps tests aligned with code changes.
 **Catches downstream effects** — analyzes impact before changes break things.
 **Protects existing work** — destructive action guard prevents schema drops, architecture replacements, and data loss without explicit approval.
 **Visualizes execution in real time** — live browser dashboard renders agent hierarchy, tool activity, and phase progression from the event stream.
 **Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
+**Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
+**Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 
 ---
 
@@ -20,7 +22,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 45 GSD-T commands + 4 utility commands (49 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 45 GSD-T commands + 5 utility commands (50 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -76,6 +78,11 @@ npx @tekyzinc/gsd-t status         # Check installation + version
 npx @tekyzinc/gsd-t doctor         # Diagnose common issues
 npx @tekyzinc/gsd-t changelog      # Open changelog in the browser
 npx @tekyzinc/gsd-t uninstall      # Remove commands (keeps project files)
+
+# Headless mode (CI/CD)
+gsd-t headless verify --json --timeout=1200  # Run verify non-interactively
+gsd-t headless query status                  # Get project state (no LLM, <100ms)
+gsd-t headless query domains                 # List domains (no LLM)
 ```
 
 ### Updating
@@ -129,26 +136,27 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-milestone` | Define new milestone | Manual |
 | `/user:gsd-t-partition` | Decompose into domains + contracts | In wave |
 | `/user:gsd-t-discuss` | Multi-perspective design exploration | In wave |
-| `/user:gsd-t-plan` | Create atomic task lists per domain | In wave |
+| `/user:gsd-t-plan` | Create atomic task lists per domain (tasks auto-split to fit one context window) | In wave |
 | `/user:gsd-t-impact` | Analyze downstream effects | In wave |
-| `/user:gsd-t-execute` | Run tasks (solo or team) | In wave |
+| `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/user:gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |
 | `/user:gsd-t-integrate` | Wire domains together | In wave |
-| `/user:gsd-t-verify` | Run quality gates | In wave |
-| `/user:gsd-t-complete-milestone` | Archive + git tag | In wave |
+| `/user:gsd-t-verify` | Run quality gates + goal-backward behavior verification | In wave |
+| `/user:gsd-t-complete-milestone` | Archive + git tag (goal-backward gate required) | In wave |
 
 ### Automation & Utilities
 
 | Command | Purpose | Auto |
 |---------|---------|------|
 | `/user:gsd-t-wave` | Full cycle, auto-advances all phases | Manual |
-| `/user:gsd-t-status` | Cross-domain progress view | Manual |
+| `/user:gsd-t-status` | Cross-domain progress view with token breakdown by domain/task/phase | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
 | `/user:gsd-t-reflect` | Generate retrospective from event stream, propose memory updates | Manual |
 | `/user:gsd-t-visualize` | Launch browser dashboard — SSE server + React Flow agent visualization | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
+| `/user:gsd-t-metrics` | View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (`--cross-project`) | Manual |
 | `/user:gsd-t-health` | Validate .gsd-t/ structure, optionally repair | Manual |
 | `/user:gsd-t-pause` | Save exact position for reliable resume | Manual |
 | `/user:gsd-t-log` | Sync progress Decision Log with recent git activity | Manual |
@@ -306,7 +314,7 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 49 slash commands
+├── commands/                          # 50 slash commands
 │   ├── gsd-t-*.md                     # 44 GSD-T workflow commands
 │   ├── gsd.md                         # GSD-T smart router
 │   ├── branch.md                      # Git branch helper

package/bin/desktop.ini

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

package/bin/global-sync-manager.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Global Sync Manager — Cross-project metrics and rule propagation
+ *
+ * Reads local project metrics and writes global aggregated files to
+ * ~/.claude/metrics/. Provides APIs for global rollup aggregation,
+ * global rule storage, signal distribution comparison, and universal
+ * rule promotion logic.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const GLOBAL_METRICS_DIR = path.join(os.homedir(), ".claude", "metrics");
+const GLOBAL_RULES_FILE = path.join(GLOBAL_METRICS_DIR, "global-rules.jsonl");
+const GLOBAL_ROLLUP_FILE = path.join(GLOBAL_METRICS_DIR, "global-rollup.jsonl");
+const GLOBAL_SIGNAL_FILE = path.join(GLOBAL_METRICS_DIR, "global-signal-distributions.jsonl");
+
+const ELO_START = 1000;
+const ELO_K = 32;
+
+const UNIVERSAL_THRESHOLD = 3;
+const NPM_CANDIDATE_THRESHOLD = 5;
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Task 1: Core JSONL read/write + global rule management
+  readGlobalRules, writeGlobalRule,
+  readGlobalRollups, writeGlobalRollup,
+  readGlobalSignalDistributions, writeGlobalSignalDistribution,
+  // Task 2: Signal distribution comparison
+  compareSignalDistributions, getDomainTypeComparison,
+  // Task 3: Universal rule promotion + global ELO
+  checkUniversalPromotion, getGlobalELO, getProjectRankings,
+  // Internal (exposed for testing)
+  _setGlobalDir,
+};
+
+// ── Overridable paths (for test isolation) ──────────────────────────────────
+
+let _globalDir = GLOBAL_METRICS_DIR;
+let _rulesFile = GLOBAL_RULES_FILE;
+let _rollupFile = GLOBAL_ROLLUP_FILE;
+let _signalFile = GLOBAL_SIGNAL_FILE;
+
+/** @param {string} dir Override global metrics directory (for testing) */
+function _setGlobalDir(dir) {
+  _globalDir = dir;
+  _rulesFile = path.join(dir, "global-rules.jsonl");
+  _rollupFile = path.join(dir, "global-rollup.jsonl");
+  _signalFile = path.join(dir, "global-signal-distributions.jsonl");
+}
+
+// ── Task 1: Core JSONL read/write ───────────────────────────────────────────
+
+/** @returns {object[]} All global rules */
+function readGlobalRules() {
+  return loadJsonl(_rulesFile);
+}
+
+/**
+ * Write or update a global rule. Dedup via trigger fingerprint.
+ * If rule already exists (same trigger), increments promotion_count and
+ * updates propagated_to. Otherwise appends new rule.
+ * @param {object} rule
+ * @returns {object} The written/updated rule
+ */
+function writeGlobalRule(rule) {
+  ensureDir(_globalDir);
+  const rules = loadJsonl(_rulesFile);
+  const fingerprint = JSON.stringify(rule.original_rule && rule.original_rule.trigger
+    ? rule.original_rule.trigger : (rule.trigger || {}));
+  const existing = rules.find((r) => {
+    const fp = JSON.stringify(r.original_rule && r.original_rule.trigger
+      ? r.original_rule.trigger : (r.trigger || {}));
+    return fp === fingerprint;
+  });
+
+  if (existing) {
+    existing.promotion_count = (existing.promotion_count || 1) + 1;
+    const srcDir = rule.source_project_dir || rule.source_project || "";
+    if (srcDir && !existing.propagated_to.includes(srcDir)) {
+      existing.propagated_to.push(srcDir);
+    }
+    // Auto-check universal/npm thresholds
+    if (existing.promotion_count >= UNIVERSAL_THRESHOLD) existing.is_universal = true;
+    if (existing.promotion_count >= NPM_CANDIDATE_THRESHOLD) existing.is_npm_candidate = true;
+    atomicWriteJsonl(_rulesFile, rules);
+    return existing;
+  }
+
+  // New rule — assign global_id
+  const nextId = rules.length > 0
+    ? Math.max(...rules.map((r) => parseInt((r.global_id || "grule-0").replace("grule-", ""), 10))) + 1
+    : 1;
+  const newRule = {
+    id: rule.id || null,
+    global_id: `grule-${String(nextId).padStart(3, "0")}`,
+    source_project: rule.source_project || getProjectName(),
+    source_project_dir: rule.source_project_dir || process.cwd(),
+    original_rule: rule.original_rule || null,
+    promoted_at: rule.promoted_at || new Date().toISOString(),
+    propagated_to: rule.propagated_to || [],
+    promotion_count: rule.promotion_count || 1,
+    is_universal: (rule.promotion_count || 1) >= UNIVERSAL_THRESHOLD,
+    is_npm_candidate: (rule.promotion_count || 1) >= NPM_CANDIDATE_THRESHOLD,
+    shipped_in_version: rule.shipped_in_version || null,
+  };
+  rules.push(newRule);
+  atomicWriteJsonl(_rulesFile, rules);
+  return newRule;
+}
+
+/** @returns {object[]} All global rollup entries */
+function readGlobalRollups() {
+  return loadJsonl(_rollupFile);
+}
+
+/**
+ * Append a global rollup entry. Dedup by source_project + milestone pair.
+ * @param {object} entry
+ * @returns {object} The written entry
+ */
+function writeGlobalRollup(entry) {
+  ensureDir(_globalDir);
+  const rollups = loadJsonl(_rollupFile);
+  const existing = rollups.find((r) =>
+    r.source_project === entry.source_project && r.milestone === entry.milestone);
+
+  if (existing) {
+    // Update in place
+    Object.assign(existing, entry, { ts: new Date().toISOString() });
+    atomicWriteJsonl(_rollupFile, rollups);
+    return existing;
+  }
+
+  const newEntry = { ts: new Date().toISOString(), ...entry };
+  rollups.push(newEntry);
+  atomicWriteJsonl(_rollupFile, rollups);
+  return newEntry;
+}
+
+/** @returns {object[]} All global signal distribution entries */
+function readGlobalSignalDistributions() {
+  return loadJsonl(_signalFile);
+}
+
+/**
+ * Write or update a global signal distribution entry.
+ * One entry per project (overwrites previous).
+ * @param {object} entry
+ * @returns {object} The written entry
+ */
+function writeGlobalSignalDistribution(entry) {
+  ensureDir(_globalDir);
+  const entries = loadJsonl(_signalFile);
+  const idx = entries.findIndex((e) => e.source_project === entry.source_project);
+  const newEntry = { ts: new Date().toISOString(), ...entry };
+
+  if (idx >= 0) {
+    entries[idx] = newEntry;
+  } else {
+    entries.push(newEntry);
+  }
+  atomicWriteJsonl(_signalFile, entries);
+  return newEntry;
+}
+
+// ── Task 2: Signal distribution comparison ──────────────────────────────────
+
+/**
+ * Compare signal distributions across all projects.
+ * Returns all projects' signal rates sorted by pass-through rate descending,
+ * with the queried project highlighted.
+ * @param {string} projectName
+ * @returns {object}
+ */
+function compareSignalDistributions(projectName) {
+  const entries = readGlobalSignalDistributions();
+  if (entries.length < 2) {
+    return {
+      insufficient_data: true,
+      projects: entries.map(formatProjectSignals),
+      queried_project: projectName,
+    };
+  }
+
+  const sorted = entries
+    .map(formatProjectSignals)
+    .sort((a, b) => (b.signal_rates["pass-through"] || 0) - (a.signal_rates["pass-through"] || 0));
+
+  return {
+    insufficient_data: false,
+    projects: sorted.map((p) => ({
+      ...p,
+      is_queried: p.source_project === projectName,
+    })),
+    queried_project: projectName,
+  };
+}
+
+/**
+ * Compare signal distributions for a specific domain type across all projects.
+ * @param {string} domainType
+ * @returns {object}
+ */
+function getDomainTypeComparison(domainType) {
+  const entries = readGlobalSignalDistributions();
+  const matches = [];
+
+  for (const entry of entries) {
+    const domSignals = (entry.domain_type_signals || [])
+      .find((d) => d.domain_type === domainType);
+    if (domSignals) {
+      matches.push({
+        source_project: entry.source_project,
+        domain_type: domainType,
+        signal_counts: domSignals.signal_counts || {},
+        total_tasks: domSignals.total_tasks || 0,
+      });
+    }
+  }
+
+  if (matches.length < 2) {
+    return { insufficient_data: true, domain_type: domainType, projects: matches };
+  }
+
+  return { insufficient_data: false, domain_type: domainType, projects: matches };
+}
+
+// ── Task 3: Universal rule promotion + global ELO ───────────────────────────
+
+/**
+ * Check if a global rule qualifies for universal or npm-candidate status.
+ * Updates the rule on disk if thresholds are met.
+ * @param {string} globalRuleId
+ * @returns {object|null} Updated rule or null if not found
+ */
+function checkUniversalPromotion(globalRuleId) {
+  const rules = loadJsonl(_rulesFile);
+  const rule = rules.find((r) => r.global_id === globalRuleId);
+  if (!rule) return null;
+
+  let changed = false;
+  if (rule.promotion_count >= UNIVERSAL_THRESHOLD && !rule.is_universal) {
+    rule.is_universal = true;
+    changed = true;
+  }
+  if (rule.promotion_count >= NPM_CANDIDATE_THRESHOLD && !rule.is_npm_candidate) {
+    rule.is_npm_candidate = true;
+    changed = true;
+  }
+
+  if (changed) {
+    atomicWriteJsonl(_rulesFile, rules);
+  }
+  return rule;
+}
+
+/**
+ * Get the latest global ELO for a project.
+ * @param {string} projectName
+ * @returns {number|null}
+ */
+function getGlobalELO(projectName) {
+  const rollups = readGlobalRollups();
+  const projectRollups = rollups.filter((r) => r.source_project === projectName);
+  if (projectRollups.length === 0) return null;
+  // Return latest elo_after
+  const latest = projectRollups[projectRollups.length - 1];
+  return latest.elo_after != null ? latest.elo_after : null;
+}
+
+/**
+ * Get all projects ranked by latest elo_after, descending.
+ * @returns {object[]} Array of { source_project, elo_after, milestone }
+ */
+function getProjectRankings() {
+  const rollups = readGlobalRollups();
+  if (rollups.length === 0) return [];
+
+  // Get latest rollup per project
+  const latest = {};
+  for (const r of rollups) {
+    latest[r.source_project] = r;
+  }
+
+  return Object.values(latest)
+    .map((r) => ({
+      source_project: r.source_project,
+      elo_after: r.elo_after != null ? r.elo_after : ELO_START,
+      milestone: r.milestone,
+    }))
+    .sort((a, b) => b.elo_after - a.elo_after);
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+function formatProjectSignals(entry) {
+  const rates = entry.signal_rates || {};
+  // Ensure normalization
+  const sum = Object.values(rates).reduce((s, v) => s + v, 0);
+  const normalized = {};
+  if (sum > 0) {
+    for (const [k, v] of Object.entries(rates)) {
+      normalized[k] = Math.round((v / sum) * 1000) / 1000;
+    }
+  }
+  return {
+    source_project: entry.source_project,
+    total_tasks: entry.total_tasks || 0,
+    signal_rates: sum > 0 ? normalized : rates,
+  };
+}
+
+function getProjectName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
+    return pkg.name || path.basename(process.cwd());
+  } catch {
+    return path.basename(process.cwd());
+  }
+}
+
+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 ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}