@proflandrigan/shards 1.1.0

package/tools/gate-hook/sweep.js

@@ -0,0 +1,139 @@
+// Stale-gate sweep + operator force-close escape hatch.
+// Extracted from gate-hook.js for direct unit testing.
+'use strict';
+
+const state = require('./state.js');
+const { appendViolation, appendHistory } = require('./log.js');
+
+// Operator escape hatch — Bash invocations of `shards-gates force-close`
+// (the npm bin or a direct `node tools/shards-gates.js force-close`) are
+// allowed even while a gate is open, so a stuck-gate deadlock can be
+// unstuck from inside a Claude session. Chain/pipe/command-substitution
+// operators are rejected so the override can't piggyback another command.
+const FORCE_CLOSE_RE = /\bshards-gates(?:\.js)?\s+force-close\b/;
+const SHELL_CHAIN_RE = /[|;&`]|\$\(/;
+
+function isForceCloseBash(toolName, toolInput) {
+  if (toolName !== 'Bash') return false;
+  const cmd = (toolInput && toolInput.command) || '';
+  if (!FORCE_CLOSE_RE.test(cmd)) return false;
+  if (SHELL_CHAIN_RE.test(cmd)) return false;
+  return true;
+}
+
+// Stale-gate sweep — gates with missing/invalid opened_at OR older than 24h
+// are auto-closed. Symmetric with the session-index abandonment sweep at
+// src/ui/session-index.js (also 24h).
+const STALE_GATE_MS = 24 * 60 * 60 * 1000;
+
+// Staleness is a property of a SINGLE gate object (one session's slot), not
+// the global state. A non-open gate is never stale.
+function isStaleGate(gate, now = Date.now()) {
+  if (!gate || !gate.open) return false;
+  if (!gate.opened_at) return true;
+  const t = Date.parse(gate.opened_at);
+  if (Number.isNaN(t)) return true;
+  return (now - t) > STALE_GATE_MS;
+}
+
+function staleReason(gate) {
+  if (!gate.opened_at) return 'missing-opened-at';
+  if (Number.isNaN(Date.parse(gate.opened_at))) return 'invalid-opened-at';
+  return 'older-than-24h';
+}
+
+// Append a stale-sweep record to the shared history + audit logs for one gate.
+// Returns the history entry pushed (so callers can compose).
+function logStaleSweep(gate, sessionId) {
+  const closed_at = new Date().toISOString();
+  const reason = staleReason(gate);
+  const entry = {
+    id: gate.id || 'unknown',
+    phase: typeof gate.phase !== 'undefined' ? gate.phase : null,
+    kind: gate.kind || null,
+    opened_at: gate.opened_at || null,
+    closed_at,
+    confirmed_by: 'stale-sweep',
+    closed_reason: reason,
+  };
+  appendViolation({
+    type: 'stale-sweep',
+    gate_id: gate.id || 'unknown',
+    opened_at: gate.opened_at || null,
+    reason,
+    session_id: sessionId,
+  });
+  appendHistory({
+    event: 'closed',
+    gate_id: gate.id || 'unknown',
+    kind: gate.kind || 'phase',
+    confirmed_by: 'stale-sweep',
+  });
+  return entry;
+}
+
+// Sweep stale gates across the v2 state, persisting the result.
+//
+// Always sweeps THIS session's gate if it is stale. Additionally sweeps any
+// OTHER session's gate that is genuinely abandoned (older than 24h, or with a
+// missing/invalid opened_at) — those carry no risk of clobbering live work.
+// Other sessions' FRESH gates are left untouched.
+//
+// Each swept gate is appended to the shared `history` with
+// confirmed_by:'stale-sweep'. Returns the new state object (also written).
+function sweepStaleSessions(s, sessionId, now = Date.now()) {
+  const cur = normalizeForSweep(s);
+  const sessions = { ...cur.sessions };
+  const history = [...cur.history];
+  let changed = false;
+
+  for (const [sid, gate] of Object.entries(cur.sessions)) {
+    if (!gate || !gate.open) continue;
+    const stale = isStaleGate(gate, now);
+    // This session's gate sweeps whenever stale; other sessions only when
+    // genuinely abandoned (which is exactly what isStaleGate detects: missing/
+    // invalid opened_at or >24h). So the predicate is the same either way.
+    if (!stale) continue;
+    history.push(logStaleSweep(gate, sessionId));
+    delete sessions[sid];
+    changed = true;
+  }
+
+  const next = { version: 2, sessions, history };
+  if (changed) state.write(next);
+  return next;
+}
+
+// Local normalize so sweep doesn't depend on state.normalize being exported —
+// mirrors the v2 shape and tolerates legacy input (upgraded by state.read()
+// before it reaches here, but we stay defensive).
+function normalizeForSweep(s) {
+  if (s && (s.version === 2 || s.sessions)) {
+    return {
+      sessions: (s.sessions && typeof s.sessions === 'object') ? s.sessions : {},
+      history: Array.isArray(s.history) ? s.history : [],
+    };
+  }
+  // Legacy single slot.
+  const sessions = {};
+  if (s && s.open) {
+    sessions[s.agent || '__legacy__'] = {
+      open: true,
+      id: s.id,
+      phase: typeof s.phase !== 'undefined' ? s.phase : null,
+      kind: s.kind || null,
+      agent: s.agent || null,
+      opened_at: s.opened_at || null,
+    };
+  }
+  return { sessions, history: Array.isArray(s && s.history) ? s.history : [] };
+}
+
+module.exports = {
+  FORCE_CLOSE_RE,
+  SHELL_CHAIN_RE,
+  STALE_GATE_MS,
+  isForceCloseBash,
+  isStaleGate,
+  sweepStaleSessions,
+};

package/tools/gate-hook/transcript.js

@@ -0,0 +1,45 @@
+// Read last assistant message from a Claude Code transcript (JSONL)
+'use strict';
+
+const fs = require('fs');
+
+function readLastAssistantMessage(transcriptPath) {
+  if (!transcriptPath) return '';
+
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return '';
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  let lastAssistantText = '';
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      // Claude Code transcript shape: {type: "assistant", message: {role, content}}
+      // Test/legacy shape: {role: "assistant", content: [...]}
+      let content = null;
+      if (entry.type === 'assistant' && entry.message && Array.isArray(entry.message.content)) {
+        content = entry.message.content;
+      } else if (entry.role === 'assistant' && Array.isArray(entry.content)) {
+        content = entry.content;
+      }
+      if (!content) continue;
+
+      const text = content
+        .filter((c) => c && c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('');
+      if (text) lastAssistantText = text;
+    } catch {
+      // malformed line — skip
+    }
+  }
+
+  return lastAssistantText;
+}
+
+module.exports = { readLastAssistantMessage };

package/tools/gate-hook/validation.js

@@ -0,0 +1,321 @@
+// Validation section parser + checker for the gate hook.
+// Implements src/agents/specific_instructions/shared/validation_protocol.md
+// and tools/gate-hook/VALIDATION_SPEC.md.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_TRACKS = new Set(['quick', 'deep', 'fixer']);
+const VALID_PASS_FAIL = new Set(['✓', '✗', 'n/a']);
+
+// ─── Specs file resolution ───────────────────────────────────────────────────
+
+// Shards projects live under convention directories — see CLAUDE.md output
+// directory map. We search these for the most recently modified project-specs.md.
+const PROJECT_DIRS = [
+  'analysis', 'studies', 'models', 'data_models', 'services',
+  'research', 'dashboards', 'brainstorm', 'fixes',
+];
+
+// Find the most recently modified project-specs.md in any immediate subdirectory
+// of the conventional project dirs (e.g. analysis/*/project-specs.md).
+function findLatestSpecs(root) {
+  let best = null;
+  let bestMtime = 0;
+  for (const d of PROJECT_DIRS) {
+    const base = path.join(root, d);
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const candidate = path.join(base, e.name, 'project-specs.md');
+      try {
+        const st = fs.statSync(candidate);
+        if (st.mtimeMs > bestMtime) {
+          bestMtime = st.mtimeMs;
+          best = candidate;
+        }
+      } catch {
+        // no specs file here — skip
+      }
+    }
+  }
+  return best;
+}
+
+function specsPath() {
+  if (process.env.SHARDS_PROJECT_SPECS_PATH) {
+    return process.env.SHARDS_PROJECT_SPECS_PATH;
+  }
+  // Backward-compatible: prefer a specs file at CWD if one exists.
+  const cwdPath = path.join(process.cwd(), 'project-specs.md');
+  try {
+    fs.accessSync(cwdPath, fs.constants.R_OK);
+    return cwdPath;
+  } catch {
+    // Not at CWD — search conventional project subdirectories.
+  }
+  return findLatestSpecs(process.cwd()) || cwdPath;
+}
+
+function readSpecs() {
+  try {
+    return fs.readFileSync(specsPath(), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// ─── Section extraction ──────────────────────────────────────────────────────
+
+// Return the body of the LAST `## Validation` section in the file.
+// A section body runs from the heading line to the next `## ` heading or EOF.
+function extractValidationBody(content) {
+  if (!content) return null;
+  const lines = content.split('\n');
+  let lastStart = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Validation\s*$/.test(lines[i])) lastStart = i;
+  }
+  if (lastStart === -1) return null;
+
+  let end = lines.length;
+  for (let i = lastStart + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(lastStart + 1, end).join('\n');
+}
+
+// Extract the body of a `### <heading>` subsection within the validation body.
+function extractSubsection(body, heading) {
+  if (!body) return null;
+  const lines = body.split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (new RegExp('^###\\s+' + heading.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&') + '\\s*$').test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^###\s+/.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+function hasSubsectionHeading(body, heading) {
+  if (!body) return false;
+  return new RegExp('^###\\s+' + heading.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&') + '\\s*$', 'm').test(body);
+}
+
+// ─── Field parsers ───────────────────────────────────────────────────────────
+
+function matchOne(body, re) {
+  if (!body) return null;
+  const m = body.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function modePresent(body) {
+  if (!body) return false;
+  return /^\*\*Mode:\*\*/m.test(body);
+}
+
+// Parse a markdown pipe table. Returns array of row objects keyed by header name (lowercased, trimmed).
+// Skips separator row (|---|---|).
+function parsePipeTable(section) {
+  if (!section) return [];
+  const lines = section.split('\n').map(l => l.trim()).filter(Boolean);
+  if (lines.length < 2) return [];
+
+  const tableLines = lines.filter(l => l.startsWith('|'));
+  if (tableLines.length < 2) return [];
+
+  const header = tableLines[0]
+    .replace(/^\||\|$/g, '')
+    .split('|')
+    .map(c => c.trim().toLowerCase());
+
+  // The next line should be the separator row — skip it if it's all dashes.
+  const dataStart = /^\|[-\s|:]+\|?$/.test(tableLines[1]) ? 2 : 1;
+
+  const rows = [];
+  for (let i = dataStart; i < tableLines.length; i++) {
+    const cells = tableLines[i]
+      .replace(/^\||\|$/g, '')
+      .split('|')
+      .map(c => c.trim());
+    if (cells.length !== header.length) continue;
+    const row = {};
+    header.forEach((h, idx) => { row[h] = cells[idx]; });
+    rows.push(row);
+  }
+  return rows;
+}
+
+// Parse a bulleted list, return array of bullet texts (trimmed).
+// Accepts `- ` or `* ` prefix.
+function parseBullets(section) {
+  if (!section) return [];
+  return section
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => /^[-*]\s+/.test(l))
+    .map(l => l.replace(/^[-*]\s+/, '').trim());
+}
+
+function nonWhitespaceLength(s) {
+  if (!s) return 0;
+  return s.replace(/\s+/g, '').length;
+}
+
+// ─── Top-level parse + check ─────────────────────────────────────────────────
+
+function parseValidationSection(content) {
+  const body = extractValidationBody(content);
+  if (body === null) return { present: false };
+
+  const evidence = extractSubsection(body, 'Evidence');
+  const artifacts = extractSubsection(body, 'Artifacts');
+  const downstream = extractSubsection(body, 'Downstream Impact');
+  const openIssues = hasSubsectionHeading(body, 'Open Issues');
+  const summary = extractSubsection(body, 'Summary');
+
+  return {
+    present: true,
+    // Anchor each field match to the same line as the label — otherwise
+    // \s* would greedily consume newlines and swallow subsequent lines
+    // when the label's value is empty.
+    track: matchOne(body, /\*\*Track:\*\*[^\S\n]*(quick|deep|fixer)\b/i),
+    modeLinePresent: modePresent(body),
+    mode: matchOne(body, /\*\*Mode:\*\*[^\S\n]*([^\n]+)/),
+    checklist: matchOne(body, /\*\*Checklist:\*\*[^\S\n]*([^\n]+validation_checklist\.md)/),
+    appliedAt: matchOne(body, /\*\*Applied at:\*\*[^\S\n]*([^\n]+)/),
+    evidenceRows: parsePipeTable(evidence),
+    artifactBullets: parseBullets(artifacts),
+    downstreamBullets: parseBullets(downstream),
+    openIssuesHeadingPresent: openIssues,
+    summaryLength: nonWhitespaceLength(summary),
+  };
+}
+
+function checkValidation(parsed) {
+  const errors = [];
+  if (!parsed.present) return [{ code: 'MISSING_SECTION' }];
+
+  if (!parsed.track || !VALID_TRACKS.has(parsed.track.toLowerCase())) {
+    errors.push({ code: 'MISSING_TRACK' });
+  }
+
+  // Mode: optional. If the line is present, value must be non-empty.
+  if (parsed.modeLinePresent && (!parsed.mode || !parsed.mode.trim())) {
+    errors.push({ code: 'EMPTY_MODE' });
+  }
+
+  if (!parsed.checklist) errors.push({ code: 'MISSING_CHECKLIST' });
+
+  if (parsed.evidenceRows.length === 0) {
+    errors.push({ code: 'NO_EVIDENCE_ROWS' });
+  } else {
+    for (let i = 0; i < parsed.evidenceRows.length; i++) {
+      const row = parsed.evidenceRows[i];
+      const check = (row.check || '').trim();
+      const expected = (row.expected || '').trim();
+      const observed = (row.observed || '').trim();
+      const passFail = (row['pass/fail'] || row.passfail || '').trim();
+      const notes = (row.notes || '').trim();
+
+      if (!check || !expected || !observed) {
+        errors.push({ code: 'INCOMPLETE_EVIDENCE_ROW', row: i + 1 });
+        continue;
+      }
+      if (!VALID_PASS_FAIL.has(passFail)) {
+        errors.push({ code: 'INVALID_PASS_FAIL', row: i + 1, got: passFail });
+        continue;
+      }
+      if (passFail === 'n/a' && !notes) {
+        errors.push({ code: 'NA_WITHOUT_JUSTIFICATION', row: i + 1 });
+      }
+    }
+  }
+
+  if (parsed.artifactBullets.length === 0) errors.push({ code: 'NO_ARTIFACTS' });
+  if (parsed.downstreamBullets.length === 0) errors.push({ code: 'NO_DOWNSTREAM' });
+  if (parsed.summaryLength < 20) {
+    errors.push({ code: 'SUMMARY_TOO_SHORT', length: parsed.summaryLength });
+  }
+
+  return errors;
+}
+
+// ─── Error formatting ────────────────────────────────────────────────────────
+
+const ERROR_DESCRIPTIONS = {
+  MISSING_SECTION: 'No `## Validation` heading found in project-specs.md',
+  MISSING_TRACK: '`**Track:**` line missing or value is not quick/deep/fixer',
+  EMPTY_MODE: '`**Mode:**` line present but value is blank (omit the line entirely if Mode is not meaningful)',
+  MISSING_CHECKLIST: '`**Checklist:**` line missing or doesn\'t reference a `validation_checklist.md`',
+  NO_EVIDENCE_ROWS: 'Evidence table has zero data rows',
+  INCOMPLETE_EVIDENCE_ROW: 'A row has an empty Check, Expected, or Observed cell',
+  INVALID_PASS_FAIL: 'A row\'s Pass/Fail value is not one of ✓, ✗, or n/a',
+  NA_WITHOUT_JUSTIFICATION: 'A row has `Pass/Fail: n/a` but the Notes cell is empty',
+  NO_ARTIFACTS: 'Artifacts section has no bullets (use `- none (see Summary)` to override intentionally)',
+  NO_DOWNSTREAM: 'Downstream Impact section has no bullets',
+  SUMMARY_TOO_SHORT: 'Summary has fewer than 20 non-whitespace characters',
+};
+
+function describe(err) {
+  const base = ERROR_DESCRIPTIONS[err.code] || err.code;
+  if (err.row) return `row ${err.row}: ${base}${err.got ? ` (got: "${err.got}")` : ''}`;
+  return base;
+}
+
+function formatValidationError(checklist, gate, errors) {
+  const lines = [
+    '::GATE-BLOCK:: Validation evidence is missing or incomplete.',
+    '',
+    `Required checklist: ${checklist}/validation_checklist.md`,
+    `Gate: ${gate.id} (phase ${gate.phase || '?'}, kind ${gate.kind || '?'})`,
+    '',
+    'Problems:',
+    ...errors.map(e => `  - ${e.code}: ${describe(e)}`),
+    '',
+    'What to do:',
+    '  1. Re-read .claude/agents/specific_instructions/shared/validation_protocol.md',
+    '     for the required `## Validation` section schema.',
+    `  2. Re-read .claude/agents/specific_instructions/${checklist}/validation_checklist.md`,
+    '     for the domain-specific checks.',
+    '  3. Run the checks, record observed values in the Evidence table, and',
+    '     re-emit the gate fence.',
+    '',
+    'If this phase should not require validation, remove the `validates=...`',
+    'attribute from the gate fence.',
+  ];
+  return lines.join('\n');
+}
+
+module.exports = {
+  parseValidationSection,
+  checkValidation,
+  formatValidationError,
+  readSpecs,
+  // Exported for tests
+  _internals: {
+    extractValidationBody,
+    extractSubsection,
+    parsePipeTable,
+    parseBullets,
+    nonWhitespaceLength,
+    VALID_TRACKS,
+    VALID_PASS_FAIL,
+    ERROR_DESCRIPTIONS,
+  },
+};