@tekyzinc/gsd-t 3.22.11 → 3.23.11

package/scripts/hooks/gsd-t-conversation-capture.js

@@ -16,16 +16,20 @@
  * - Never throws to the caller — catches all errors, logs to stderr, exits 0.
  * - `content` is capped at 16 KB per frame; over-cap writes `truncated: true`.
  * - Append-only; never overwrites an existing in-session NDJSON file.
- * - Project-dir discovery: prefers `GSD_T_PROJECT_DIR`, then `payload.cwd`,
+ * - Project-dir discovery: prefers `GSD_T_PROJECT_DIR`, then decodes
+ *   `payload.transcript_path`'s `~/.claude/projects/{slug}` to a real project
+ *   root (session-specific signal — required when multiple parallel Claude
+ *   Code sessions share one node-runtime hook process), then `payload.cwd`,
  *   then walks up from `process.cwd()` looking for `.gsd-t/progress.md`.
  *   Silent no-op if no project dir found.
  *
- * Contract: .gsd-t/contracts/conversation-capture-contract.md v1.0.0
+ * Contract: .gsd-t/contracts/conversation-capture-contract.md v1.2.0
  */
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const os = require('os');
 
 const DEFAULT_SCRIPT_GUARD_MS = 5000;
 const CONTENT_CAP_BYTES = 16 * 1024; // 16 KB
@@ -69,15 +73,102 @@ function _walkUpForProject(startDir) {
   return null;
 }
 
+// Decode a Claude Code project slug (the directory name under
+// `~/.claude/projects/`) back to an absolute project root that contains a
+// `.gsd-t/` directory. The slug encoding is lossy — `/` and literal `-` both
+// map to `-` — so we DFS-walk the filesystem, greedily consuming token runs as
+// directory names. First match whose `.gsd-t/` exists wins. Returns null if
+// nothing matches or the slug is malformed.
+//
+// Why this exists: Claude Code Stop hook payloads carry `transcript_path` =
+// `~/.claude/projects/{slug}/{sessionId}.jsonl`. The hook runs as one shared
+// node-runtime process across parallel Claude Code sessions, so `process.cwd()`
+// can resolve to the wrong project. The slug is the only *session-specific*
+// signal we have for project routing.
+function _slugToProjectDir(slug) {
+  if (typeof slug !== 'string' || slug.length === 0) return null;
+  if (slug[0] !== '-') return null; // must encode leading '/'
+  // Reject anything that could traversal-escape after decode.
+  if (slug.includes('/') || slug.includes('\\') || slug.includes('\0')) return null;
+  if (slug.includes('..')) return null;
+  const tokens = slug.slice(1).split('-'); // strip leading '-' (the leading '/')
+  if (tokens.length === 0 || tokens.some((t) => t.length === 0)) return null;
+  // DFS over how many '-'-separated tokens form each directory segment.
+  // Greedy preference: try fewest tokens first (most '/' separators) so deeper
+  // paths win when both interpretations exist.
+  function walk(prefix, idx) {
+    if (idx >= tokens.length) {
+      try {
+        if (fs.existsSync(path.join(prefix, '.gsd-t'))) return prefix;
+      } catch (_) { /* swallow */ }
+      return null;
+    }
+    for (let k = 1; k <= tokens.length - idx; k++) {
+      const seg = tokens.slice(idx, idx + k).join('-');
+      const next = path.join(prefix, seg);
+      // Re-validate after path.join — defense against weird inputs.
+      if (next.includes('..')) continue;
+      let exists = false;
+      try { exists = fs.existsSync(next); } catch (_) { exists = false; }
+      if (!exists) continue;
+      const found = walk(next, idx + k);
+      if (found) return found;
+    }
+    return null;
+  }
+  return walk('/', 0);
+}
+
+// Extract the slug ({dir-name} under `~/.claude/projects/`) from a
+// transcript_path. Returns null on malformed input.
+function _slugFromTranscriptPath(p) {
+  if (typeof p !== 'string' || !path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const root = path.resolve(home, '.claude', 'projects') + path.sep;
+  const resolved = path.resolve(p);
+  if (!resolved.startsWith(root)) return null;
+  const rest = resolved.slice(root.length);
+  // First path segment after the projects/ root is the slug.
+  const sep = rest.indexOf(path.sep);
+  const slug = sep === -1 ? rest : rest.slice(0, sep);
+  if (!slug) return null;
+  return slug;
+}
+
 function _resolveProjectDir(payload) {
+  // 1. Explicit env override (preserved for tests + operator overrides).
   const env = process.env.GSD_T_PROJECT_DIR;
   if (env && fs.existsSync(path.join(env, '.gsd-t'))) return env;
+  // 2. Session-specific signal: decode the transcript_path slug. This is the
+  //    ONLY source that's per-session under parallel Claude Code instances —
+  //    cwd / walk-up resolve to whichever project the hook process happens to
+  //    inherit, which misroutes frames across projects.
+  if (payload && typeof payload.transcript_path === 'string') {
+    const slug = _slugFromTranscriptPath(payload.transcript_path);
+    if (slug) {
+      const fromSlug = _slugToProjectDir(slug);
+      if (fromSlug) return fromSlug;
+    }
+  }
+  // 3. payload.cwd (Claude Code may carry it on some events).
   if (payload && typeof payload.cwd === 'string' && path.isAbsolute(payload.cwd)
       && fs.existsSync(path.join(payload.cwd, '.gsd-t'))) {
     return payload.cwd;
   }
+  // 4. Last resort: walk up from process.cwd(). Known-unreliable for parallel
+  //    sessions sharing a node-runtime hook process — emit a one-line warning
+  //    so misroutes are diagnosable from stderr.
   const walked = _walkUpForProject(process.cwd());
-  if (walked) return walked;
+  if (walked) {
+    try {
+      process.stderr.write(
+        'gsd-t-conversation-capture: project-dir resolved via cwd walk-up (' +
+        walked + ') — unreliable for parallel sessions\n'
+      );
+    } catch (_) { /* noop */ }
+    return walked;
+  }
   return null;
 }
 
@@ -134,9 +225,93 @@ function _extractUserContent(payload) {
   return null;
 }
 
+// Tail-read the last `bytes` of a file as UTF-8. Returns '' on any error.
+// Used so multi-MB transcripts don't get fully loaded into RAM.
+function _readFileTail(filePath, bytes) {
+  let fd = -1;
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) return '';
+    const size = st.size;
+    if (size === 0) return '';
+    const want = Math.min(bytes, size);
+    const start = size - want;
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(want);
+    fs.readSync(fd, buf, 0, want, start);
+    let str = buf.toString('utf8');
+    // If we sliced mid-line, drop the (possibly malformed) leading partial.
+    if (start > 0) {
+      const nl = str.indexOf('\n');
+      if (nl >= 0) str = str.slice(nl + 1);
+    }
+    return str;
+  } catch (_) {
+    return '';
+  } finally {
+    if (fd >= 0) { try { fs.closeSync(fd); } catch (_) { /* noop */ } }
+  }
+}
+
+// Validate `transcript_path` from a hook payload before reading. Stop hooks
+// from Claude Code put the file under `~/.claude/projects/`; we lock to that
+// to defeat path-traversal attempts (BUG-1 sanitizer pattern). Fail open
+// (return null) on anything suspicious.
+function _safeTranscriptPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return null;
+  if (!path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const allowedRoot = path.resolve(home, '.claude', 'projects') + path.sep;
+  const resolved = path.resolve(p);
+  if (!resolved.startsWith(allowedRoot)) return null;
+  return resolved;
+}
+
+// Pull the assistant body out of a Claude Code transcript JSONL by scanning
+// from the tail. Each line is one event; the latest `type === 'assistant'`
+// row carries the message. Concatenate all `text`-type content blocks; ignore
+// tool_use / tool_result / thinking blocks. Returns null if no assistant row
+// is found or every candidate is body-less (tool_use only).
+function _readAssistantFromTranscript(transcriptPath) {
+  const safe = _safeTranscriptPath(transcriptPath);
+  if (!safe) return null;
+  const tail = _readFileTail(safe, 64 * 1024);
+  if (!tail) return null;
+  const lines = tail.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line) continue;
+    let row;
+    try { row = JSON.parse(line); } catch (_) { continue; }
+    if (!row || row.type !== 'assistant') continue;
+    // Skip subagent turns — orchestrator transcripts record both, but only
+    // the orchestrator's own assistant turn belongs in this in-session file.
+    if (row.isSidechain === true) continue;
+    const msg = row.message;
+    if (!msg) continue;
+    const blocks = msg.content;
+    if (typeof blocks === 'string') return blocks;
+    if (!Array.isArray(blocks)) continue;
+    const texts = [];
+    for (const b of blocks) {
+      if (b && b.type === 'text' && typeof b.text === 'string') texts.push(b.text);
+    }
+    if (texts.length === 0) continue; // tool_use-only turn — keep scanning
+    return texts.join('');
+  }
+  return null;
+}
+
 function _extractAssistantContent(payload) {
-  // Stop hook payloads vary. Try the common shapes; fall back to null so we
-  // still emit a stub frame (ts + session_id only).
+  // PRIMARY: Claude Code Stop hook payload carries `transcript_path` to the
+  // orchestrator's JSONL. Read the most recent assistant row from the tail.
+  if (payload && typeof payload.transcript_path === 'string') {
+    const fromTranscript = _readAssistantFromTranscript(payload.transcript_path);
+    if (fromTranscript != null) return fromTranscript;
+  }
+  // Fallback shapes — kept so older / non-Claude-Code payload shapes still
+  // work (and so unit tests can exercise the hook without a real transcript).
   if (payload && typeof payload.assistant_message === 'string') return payload.assistant_message;
   if (payload && payload.message && typeof payload.message.content === 'string') {
     return payload.message.content;
@@ -253,6 +428,12 @@ module.exports = {
     _buildToolUseFrame,
     _appendFrame,
     _handle,
+    _extractAssistantContent,
+    _readAssistantFromTranscript,
+    _safeTranscriptPath,
+    _readFileTail,
+    _slugFromTranscriptPath,
+    _slugToProjectDir,
     CONTENT_CAP_BYTES,
   },
 };

package/scripts/hooks/pre-commit-journey-coverage

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# GSD-T journey-coverage gate (M52 D1)
+# Blocks commits that touch viewer-source files when uncovered listeners are
+# detected by `bin/journey-coverage-cli.cjs --staged-only`.
+#
+# Install (opt-in):  gsd-t doctor --install-journey-hook
+# Remove:            rm .git/hooks/pre-commit  (or remove the marker block if
+#                    merged into an existing hook)
+#
+# Exit codes:
+#   0 — clean (no viewer-source files staged, OR coverage clean, OR fail-open)
+#   1 — blocked (uncovered listener in staged viewer-source files)
+#
+# Fail-open philosophy: a broken hook is worse than a permissive one. Detector
+# internal exception → exit 0 with a stderr warning, never block.
+
+set -e
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+VIEWER_SOURCE_PATTERNS=(
+  "scripts/gsd-t-transcript.html"
+  "scripts/gsd-t-dashboard-server.js"
+  "bin/gsd-t-dashboard"
+  "e2e/journeys/"
+  "e2e/viewer/"
+)
+
+STAGED="$(git diff --cached --name-only --diff-filter=AM 2>/dev/null || true)"
+[ -z "$STAGED" ] && exit 0
+
+matches=""
+while IFS= read -r f; do
+  for p in "${VIEWER_SOURCE_PATTERNS[@]}"; do
+    case "$f" in
+      "$p"|"$p"*) matches="$matches $f"; break ;;
+    esac
+  done
+done <<EOF
+$STAGED
+EOF
+
+if [ -z "$matches" ]; then
+  exit 0
+fi
+
+CLI="$ROOT/bin/journey-coverage-cli.cjs"
+if [ ! -f "$CLI" ]; then
+  echo "[journey-coverage] WARNING: $CLI not found — fail-open." >&2
+  exit 0
+fi
+
+# Run the CLI in --staged-only mode. Capture stdout+stderr; rely on exit code.
+set +e
+OUT="$(node "$CLI" --staged-only --project-dir "$ROOT" 2>&1)"
+RC=$?
+set -e
+
+case "$RC" in
+  0)
+    exit 0
+    ;;
+  4)
+    echo "[journey-coverage] BLOCKED: uncovered viewer listener in staged files." >&2
+    echo "$OUT" >&2
+    echo "" >&2
+    echo "  Add a journey spec under e2e/journeys/ and update .gsd-t/journey-manifest.json." >&2
+    exit 1
+    ;;
+  2)
+    echo "[journey-coverage] BLOCKED: manifest missing/unreadable." >&2
+    echo "$OUT" >&2
+    exit 1
+    ;;
+  *)
+    # Unknown exit — fail-open so a detector bug doesn't break workflow.
+    echo "[journey-coverage] WARNING: detector exited $RC (fail-open):" >&2
+    echo "$OUT" >&2
+    exit 0
+    ;;
+esac

package/templates/prompts/red-team-subagent.md

@@ -42,3 +42,56 @@ Summary:
 - VERDICT: `FAIL` ({N} bugs found) | `GRUDGING PASS` (exhaustive search, nothing found)
 
 Write findings to `.gsd-t/red-team-report.md`. If bugs found, also append to `.gsd-t/qa-issues.md`.
+
+## Test Pass-Through — Journey Edition (M52)
+
+**Activates when**: `.gsd-t/journey-manifest.json` exists AND `e2e/journeys/` is non-empty (M52 D2 has landed).
+
+**Goal**: Prove the journey specs catch real regressions in the journeys they
+claim to cover. A journey spec that only checks "the button exists and is
+clickable" passes through any breakage to the user — that is what this
+category attacks.
+
+**Protocol**:
+
+1. For each spec in `.gsd-t/journey-manifest.json`, identify the listener(s) it covers.
+2. Write a deliberately-broken patch to `scripts/gsd-t-transcript.html` that
+   targets that listener — examples:
+   - Remove the listener entirely (`addEventListener` line stripped).
+   - Comment out the side-effect inside the handler (e.g. `_ssSet` call).
+   - Swap a sessionStorage key name (e.g. splitterPct key → `'XXX'`).
+   - Stub the handler to early-return (`if (true) return;` at top).
+   - Reverse a state mutation (`next ? 'true' : 'false'` → `next ? 'false' : 'true'`).
+3. Run the journey spec against the broken viewer.
+4. **PASS**: spec FAILS (red) → revert patch → spec PASSES (green). Record `caught`.
+5. **FAIL**: spec PASSES with broken viewer → SHALLOW SPEC, must be tightened.
+   Record `pass-through` and rewrite the assertion to verify state change /
+   data flow / content load.
+6. Write at least 5 broken patches across different specs. Each pass-through
+   is a verdict-level FAIL until rewritten.
+
+**Hook end-to-end exercise** (also part of this category):
+- Stage a viewer-source diff that adds a NEW listener with no manifest entry.
+- Confirm `pre-commit-journey-coverage` blocks the commit (exit 1).
+- Update `.gsd-t/journey-manifest.json` with a covering entry.
+- Confirm the hook now allows the commit (exit 0).
+- Both transitions logged in `.gsd-t/red-team-report.md` § "M52 JOURNEY-EDITION RED TEAM".
+
+**Findings format** in `.gsd-t/red-team-report.md` (append-only section):
+```
+## M52 JOURNEY-EDITION RED TEAM — {date}
+
+### Patch {N}: {short-name}
+- **Spec**: {spec-name}
+- **Broken-line(s)**: file:line — {one-line description of patch}
+- **Expected**: spec FAILS, caught the regression
+- **Actual**: {fail|pass-through}
+- **Verdict**: caught | PASS-THROUGH (must rewrite spec)
+
+### Hook end-to-end
+- Block exercise: {git diff details, exit code, stderr summary}
+- Unblock exercise: {manifest update, exit code, stderr summary}
+
+### VERDICT
+{GRUDGING PASS — N patches written, all caught | FAIL — {M} pass-through(s)}
+```