@tekyzinc/gsd-t 4.19.14 → 4.20.11

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.20.11] - 2026-07-12
+
+### Added — M101: Architect's Oversight Doctrine
+
+Fills GSD-T's empty architect seat. Every existing quality gate (Red Team, QA, code-review, pre-mortem) asks "is this correct?" — none asked "is this the smartest, simplest design given what already exists?" The result was the wrong thing built correctly, tested thoroughly, and shipped (origin: a real waste where a whole-page scan re-derived a value already stored locally, invisible under jargon). Now every build runs a Six-Stage Pass before code: Objective → Conflict → Reuse (process AND output, queried against the code graph) → Simplicity → Reuse-forecast → Risk, each answered with evidence not conviction. Three-layer enforcement, sibling of the M90 Unproven-Assumption Doctrine.
+
+- `templates/CLAUDE-global.md` + `~/.claude/CLAUDE.md`: the doctrine (definition layer) — Six-Stage Pass, reuse logic (HIGH/LOW forecast, extract-don't-mutate, graph-registered reuse-candidate links to prevent silent duplicate sprawl), plain-English proof, jargonless output co-equal with brevity (absorbs backlog #47).
+- `~/.claude/scripts/gsd-t-architect-oversight-guard.js`: PreToolUse Write|Edit reminder hook (trigger layer) — one line at the build moment, fail-open, code-only (silent on prose/pseudocode/docs/non-project). Wired into settings.json.
+- `templates/workflows/gsd-t-phase.workflow.js`: injects the Six-Stage directive into plan/milestone phases (execution layer; `[RULE] phase-workflow-injects-architect-pass`, enforced by the existing guard-map gate).
+- `.gsd-t/contracts/architects-oversight-contract.md` v1.0.0 STABLE; `.gsd-t/pseudocode/PseudoCode-ArchitectsOversight.md` (self-obedience, plain-English house style).
+- `scripts/gsd-t-auto-route.js`: sharpened READER_CONTRACT jargon rule + 2 worked examples (backlog #47).
+- `test/m101-architect-oversight-hook.test.js`: 9 tests (fires on code, silent on prose, fails open on garbage).
+
+Follow-on (recorded, not built): a dedicated verify agent for pseudocode-completeness / reuse-evidence / no-silent-twin checks. The existing guard-map gate already enforces the `[RULE]` marker.
+
+## [4.20.10] - 2026-07-08
+
+### Added — M100: Universal Trace + Audit Logging (framework defaults)
+
+Trace + audit logging are now GSD-T framework defaults — every new project is born with a toggleable capture-everything trace stream (PII-barred; opt-out-able for stateless CLIs/libraries) and an immutable, admin-queryable audit stream (opt-out-able), enforced by a structural verify gate. Trace and audit are two DISTINCT streams that never collapse (the two machinery domains share no file, mechanizing the invariant by construction). Piloted end-to-end into greenfield UMI-Automation.
+
+- 2 primary contracts + 3 support contracts + 2 PseudoCode behavior maps.
+- `bin/gsd-t-logging-scaffolder.cjs` — storage scaffolder with a human-approval PAUSE (never silently picks a backend).
+- `bin/gsd-t-logging-envelope-check.cjs` — structural verify gate (per-record + per-project discovery incl. SQLite, PII bar, no-collapse, presence-vs-null, trace+audit opt-out).
+- `templates/logging/{trace,audit}-module.template.ts` + `bin/gsd-t-{trace,audit}-distill.cjs`; audit = real SQLite, append-only triggers + sentinel + self-heal, GSD-T-independent admin query.
+- `bin/gsd-t-migrate-logging.cjs` + `commands/gsd-t-migrate-logging.md` + 2 CLAUDE.md hard rules + a symmetric trace opt-out (`.gsd-t/trace-optout.json`); GSD-T self-opts-out of both.
+
+### Fixed — update banner corrupted machine JSON stdout
+
+The "Update available" banner wrote to stdout after a command's JSON envelope — breaking JSON.parse consumers of `graph body` / `graph --output json`. Moved to stderr.
+
+**Known limitation (documented):** audit immutability is trigger-based defense-in-depth, NOT cryptographic tamper-proofing against a hostile process with direct .db-file write access (a fundamental SQLite limit). Tamper-evidence (hash-chain) is backlog #48.
+
 ## [4.19.14] - 2026-07-07
 
 ### Changed — `/gsd-t-stories`: pagination, test-case coloring, in-image diagram titles

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.19.14** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.20.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.
@@ -24,6 +24,7 @@
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
 **Design Verification Agent** — after QA passes on design-to-code projects, a dedicated verification agent opens a browser with both the built frontend AND the original design (Figma page, design image, or MCP screenshot) side-by-side for direct visual comparison. Produces a structured element-by-element comparison table (30+ rows) with specific design values vs. implementation values and MATCH/DEVIATION verdicts. An artifact gate enforces that the comparison table exists — missing it blocks completion. Separation of concerns: coding agents code, verification agents verify. Wired into execute (Step 5.25) and quick (Step 5.25). Only fires when `.gsd-t/contracts/design-contract.md` exists — non-design projects are unaffected.
 **Exploratory Testing** — after scripted tests pass, if Playwright MCP is registered in Claude Code settings, QA agents get 3 minutes and Red Team gets 5 minutes of interactive browser exploration. All findings tagged `[EXPLORATORY]` and tracked separately in QA calibration. Silent skip when Playwright MCP absent. Wired into execute, quick, integrate, and debug.
+**Universal Trace + Audit Logging (M100)** — every project gets two logging streams by default, each a default for EVERY project EXCEPT explicit opt-out: **trace** (transient, PII-barred debug signal — a stateless CLI/library with no runtime data-flow may opt out via `.gsd-t/trace-optout.json`) and **audit** (durable, append-only, admin-queryable accountability record — opt out via `.gsd-t/audit-optout.json`), mirroring each other's opt-out convention. Storage is stack-adaptive and human-approval-gated (`bin/gsd-t-logging-scaffolder.cjs` — never silently picks a backend); `gsd-t-verify` enforces both envelopes structurally and blocks any collapse of the two streams into one. Brownfield projects get `gsd-t migrate-logging` (additive/non-destructive scaffold-in). Contracts: `.gsd-t/contracts/trace-logging-contract.md`, `audit-logging-contract.md`, `logging-schema-distillation-contract.md`, `logging-scaffold-seam-contract.md`.
 
 ---
 
@@ -228,6 +229,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report | Manual |
 | `/gsd-t-design-build` | Build from design contracts with two-terminal review (Term 1 builder) | Manual |
 | `/gsd-t-design-review` | Independent review agent for design build (Term 2 reviewer) | Auto |
+| `gsd-t migrate-logging <projectDir>` | Brownfield: scaffold trace + audit logging into an existing project, additively (M100) | Manual |
 
 ### Backlog Management
 

package/bin/gsd-t-audit-distill.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T Audit-Half Action Distiller (M100-D4-T2)
+ *
+ * Distills the concrete per-project audit ACTION set from the project's own
+ * plan/integration points — NEVER confabulates an example
+ * (`feedback_no_confabulated_examples`). An unstated action is a QUESTION,
+ * not an invented value. Ships the opt-out record writer for the audit
+ * default-except-opt-out convention.
+ *
+ * Contract: .gsd-t/contracts/logging-schema-distillation-contract.md
+ * Consumed contract: .gsd-t/contracts/audit-logging-contract.md §opt-out-record.
+ *
+ * NEVER shares a file with the trace distiller (bin/gsd-t-trace-distill.cjs,
+ * owned by d2) — mechanizes no-collapse by construction (this file's own
+ * path is distinct from that path).
+ *
+ * Exports:
+ *   distillAuditActions(planPath) -> { actions: Array<{ action, target, source }> }
+ *   writeOptOut(projectDir, reason) -> the written opt-out record
+ *   readOptOut(projectDir) -> the opt-out record, or null if absent/invalid
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── §opt-out-record — pinned shape (audit-logging-contract.md §opt-out-record) ──
+
+const OPTOUT_REL_PATH = path.join('.gsd-t', 'audit-optout.json');
+
+/**
+ * Writes the canonical opt-out record to `<projectDir>/.gsd-t/audit-optout.json`.
+ * Shape is FIXED by the contract — do not invent alternate keys/paths.
+ */
+function writeOptOut(projectDir, reason) {
+  if (typeof reason !== 'string' || reason.trim().length === 0) {
+    throw new Error('writeOptOut: reason must be a non-empty string');
+  }
+  const record = { auditOptOut: true, reason };
+  const dir = path.join(projectDir, '.gsd-t');
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(projectDir, OPTOUT_REL_PATH);
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  return record;
+}
+
+/**
+ * Reads + validates the opt-out record. Returns null if the file is absent,
+ * unparseable, or fails either field rule (fail-closed — an unrecognized
+ * record is treated as absent, never as an implicit pass).
+ */
+function readOptOut(projectDir) {
+  const filePath = path.join(projectDir, OPTOUT_REL_PATH);
+  let parsed;
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_err) {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  if (parsed.auditOptOut !== true) return null;
+  if (typeof parsed.reason !== 'string' || parsed.reason.trim().length === 0) return null;
+  return parsed;
+}
+
+// ── Distillation — grounded extraction, never confabulated ─────────────────
+
+// Structural cues that mark a plan line as an accountability-worthy human
+// decision point (approve/reject/edit a record with a before/after state).
+// This is a STRUCTURAL grep over the plan's own text — it extracts what the
+// plan says, it does not invent a domain-specific action.
+// Note: bare noun 'approval' is intentionally excluded — the approve[sd]?
+// branch already covers the decision verb, and keeping the action set
+// verb-consistent avoids emitting action:'approval' alongside 'approve'/
+// 'approved' for the same decision (code-review nit).
+const DECISION_VERB_RE = /\b(approve[sd]?|reject[sd]?|edit(?:ed|s)?|revis(?:e|ed|es)|review(?:ed|s)?|impersonat(?:e|ed|es|ion)|refund(?:ed|s)?|delet(?:e|ed|es)|role[- ]?chang(?:e|ed|es)|export(?:ed|s)?)\b/i;
+
+// Lines that look like a markdown heading or list item naming a step.
+const PLAN_LINE_RE = /^\s*(?:[-*+]\s+|#{1,6}\s+|\d+[.)]\s+)(.*\S)\s*$/;
+
+/**
+ * Extracts a target noun phrase near the matched verb — best-effort, purely
+ * structural (adjacent capitalized/quoted token), never a fabricated value.
+ * Falls back to the generic 'record' target only when no more specific noun
+ * is structurally recoverable from the line itself.
+ */
+function _extractTarget(line) {
+  const quoted = line.match(/"([^"]+)"|'([^']+)'|`([^`]+)`/);
+  if (quoted) return quoted[1] || quoted[2] || quoted[3];
+  const capitalized = line.match(/\b([A-Z][a-zA-Z]*(?:\s[A-Z][a-zA-Z]*)*)\b/);
+  if (capitalized) return capitalized[1];
+  return 'record';
+}
+
+/**
+ * distillAuditActions(planPath) -> { actions: Array<{ action, target, source }> }
+ *
+ * Reads the project's own plan file and extracts accountability-worthy
+ * actions GROUNDED in the plan's actual text (source = the exact matched
+ * line, for grep-traceability back to the plan). Returns an EMPTY array
+ * (never an error, never a confabulated placeholder) when the plan contains
+ * no accountability-worthy actions — the empty-input pole is a legitimate,
+ * non-error outcome.
+ */
+function distillAuditActions(planPath) {
+  if (!fs.existsSync(planPath)) {
+    throw new Error('distillAuditActions: plan file not found: ' + planPath);
+  }
+  const text = fs.readFileSync(planPath, 'utf8');
+  const lines = text.split(/\r?\n/);
+
+  const actions = [];
+  for (const rawLine of lines) {
+    const lineMatch = rawLine.match(PLAN_LINE_RE);
+    const candidate = lineMatch ? lineMatch[1] : rawLine;
+    if (!candidate || !DECISION_VERB_RE.test(candidate)) continue;
+
+    const verbMatch = candidate.match(DECISION_VERB_RE);
+    const action = verbMatch[1].toLowerCase();
+    const target = _extractTarget(candidate);
+
+    actions.push({
+      action,
+      target,
+      source: candidate.trim(),
+    });
+  }
+
+  return { actions };
+}
+
+module.exports = {
+  distillAuditActions,
+  writeOptOut,
+  readOptOut,
+  OPTOUT_REL_PATH,
+  // Test surface:
+  _extractTarget,
+  DECISION_VERB_RE,
+};
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+
+function _parseArgv(argv) {
+  const out = { cmd: null, planPath: null, projectDir: '.', reason: null };
+  out.cmd = argv[0] || null;
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--plan') out.planPath = argv[++i];
+    else if (a === '--project') out.projectDir = argv[++i];
+    else if (a === '--reason') out.reason = argv[++i];
+  }
+  return out;
+}
+
+if (require.main === module) {
+  const args = _parseArgv(process.argv.slice(2));
+  if (args.cmd === 'distill') {
+    const result = distillAuditActions(args.planPath);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (args.cmd === 'opt-out') {
+    const record = writeOptOut(args.projectDir, args.reason);
+    process.stdout.write(JSON.stringify(record, null, 2) + '\n');
+  } else {
+    process.stderr.write('Usage: gsd-t-audit-distill.cjs distill --plan <path> | opt-out --project <dir> --reason <text>\n');
+    process.exit(1);
+  }
+}