session-orchestrator 3.16.0

package/scripts/lib/frontend-detect/rules.mjs

@@ -0,0 +1,295 @@
+/**
+ * scripts/lib/frontend-detect/rules.mjs
+ *
+ * Deterministic frontend-slop rule registry (regex tier — no LLM, no API key,
+ * no browser). Each rule is a pure function over file text that returns zero or
+ * more matches with the offending line + snippet.
+ *
+ * Design provenance: the rule *catalogue* (which AI-generated design tells to
+ * detect) is inspired by pbakaus/impeccable (Apache-2.0) and our own
+ * `.claude/rules/frontend.md`. The detection *code* here is a clean-room
+ * regex-tier reimplementation — we deliberately skip impeccable's heavier
+ * static-HTML CSS-cascade + Puppeteer tiers (cost ≫ value for a pre-commit /
+ * discovery probe; see the analysis in the linked backlog issue).
+ *
+ * The load-bearing idea we adopt: every prose design rule should have a
+ * MECHANICAL counterpart. `ruleRef` ties each detector rule back to the prose
+ * guidance it enforces — the "Disziplin statt Mechanik" pattern applied to a
+ * domain (frontend quality) we previously enforced with prose alone.
+ *
+ * Rule contract:
+ *   {
+ *     id: string,                 // stable kebab-case id
+ *     ruleRef: string,            // prose-guidance anchor it enforces
+ *     severity: 'high'|'medium'|'low',
+ *     category: 'ai-slop'|'quality',
+ *     title: string,
+ *     recommendation: string,
+ *     fpRisk: 'low'|'medium'|'high',   // false-positive risk (honesty signal)
+ *     scan(content: string): Array<{ line: number, snippet: string, value?: string }>
+ *   }
+ *
+ * A "match" is reported with a 1-based line number and a trimmed snippet of the
+ * offending source line.
+ */
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a 0-based string index to a 1-based line number.
+ * @param {string} content
+ * @param {number} index
+ * @returns {number}
+ */
+function lineOf(content, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Return the trimmed full source line containing `index`, capped to 160 chars.
+ * @param {string} content
+ * @param {number} index
+ * @returns {string}
+ */
+function snippetAt(content, index) {
+  const start = content.lastIndexOf('\n', index - 1) + 1;
+  let end = content.indexOf('\n', index);
+  if (end === -1) end = content.length;
+  const raw = content.slice(start, end).trim();
+  return raw.length > 160 ? `${raw.slice(0, 157)}…` : raw;
+}
+
+/**
+ * Run a global regex over content and emit one match per hit.
+ * Deduplicates by line so a single offending line reports once.
+ * @param {string} content
+ * @param {RegExp} re — MUST have the global flag
+ * @returns {Array<{ line: number, snippet: string, value: string }>}
+ */
+function scanRegex(content, re) {
+  const out = [];
+  const seenLines = new Set();
+  let m;
+  // Defensive: reset lastIndex in case a non-fresh regex is passed.
+  re.lastIndex = 0;
+  while ((m = re.exec(content)) !== null) {
+    const line = lineOf(content, m.index);
+    if (seenLines.has(line)) continue;
+    seenLines.add(line);
+    out.push({ line, snippet: snippetAt(content, m.index), value: m[0].trim() });
+    // Guard against zero-width matches looping forever.
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+// Purple / indigo / violet color tokens — the canonical AI-gradient palette.
+const PURPLE_TOKENS = [
+  'purple',
+  'violet',
+  'indigo',
+  'fuchsia',
+  'rebeccapurple',
+  '#7c3aed',
+  '#8b5cf6',
+  '#a855f7',
+  '#6366f1',
+  '#818cf8',
+  '#d946ef',
+  '#c084fc',
+  '#9333ea',
+];
+const BLUE_TOKENS = ['blue', '#3b82f6', '#2563eb', '#60a5fa', '#0ea5e9', '#06b6d4', 'cyan'];
+
+// ---------------------------------------------------------------------------
+// Rules
+// ---------------------------------------------------------------------------
+
+/** @type {Array<import('./detect.mjs').Rule>} */
+export const RULES = [
+  {
+    id: 'gradient-text',
+    ruleRef: 'frontend.md#absolute-bans (gradient text)',
+    severity: 'high',
+    category: 'ai-slop',
+    title: 'Gradient text (background-clip:text + gradient)',
+    recommendation:
+      'Decorative, never meaningful. Use a single solid color; carry emphasis with weight or size.',
+    fpRisk: 'low',
+    scan(content) {
+      const matches = [];
+      // CSS form: background-clip:text (or -webkit-) anywhere AND a gradient() anywhere.
+      const hasClipText = /(?:-webkit-)?background-clip\s*:\s*text\b/i.test(content);
+      const hasGradient = /\b(?:linear|radial|conic)-gradient\s*\(/i.test(content);
+      if (hasClipText && hasGradient) {
+        matches.push(...scanRegex(content, /(?:-webkit-)?background-clip\s*:\s*text\b/gi));
+      }
+      // Tailwind form: the `bg-clip-text` utility is the unambiguous tell.
+      matches.push(...scanRegex(content, /\bbg-clip-text\b/g));
+      return dedupeByLine(matches);
+    },
+  },
+
+  {
+    id: 'side-stripe-border',
+    ruleRef: 'frontend.md#absolute-bans (side-stripe borders)',
+    severity: 'high',
+    category: 'ai-slop',
+    title: 'Side-stripe accent border (border-left/right ≥ 2px)',
+    recommendation:
+      'Never intentional as a colored accent. Use full borders, a background tint, a leading icon/number, or nothing.',
+    fpRisk: 'low',
+    scan(content) {
+      const matches = [];
+      // CSS: border-left: 4px solid <color>  (width >= 2, not transparent/none)
+      const css = /border-(?:left|right)\s*:\s*(\d+)px\s+(?:solid|dashed|dotted|double)\b(?![^;]*\b(?:transparent|none)\b)/gi;
+      let m;
+      css.lastIndex = 0;
+      while ((m = css.exec(content)) !== null) {
+        if (Number(m[1]) >= 2) {
+          matches.push({ line: lineOf(content, m.index), snippet: snippetAt(content, m.index), value: m[0].trim() });
+        }
+      }
+      // Tailwind: border-l-2 / border-l-4 / border-l-8 / border-r-4 ...
+      matches.push(...scanRegex(content, /\bborder-(?:l|r)-(?:2|4|8)\b/g));
+      return dedupeByLine(matches);
+    },
+  },
+
+  {
+    id: 'overused-font',
+    ruleRef: 'frontend.md / development.md (avoid overused fonts)',
+    severity: 'medium',
+    category: 'ai-slop',
+    title: 'Overused primary font (Inter / Roboto / Arial / Helvetica)',
+    recommendation:
+      'Every model reaches for these. Pick a font with a point of view; keep these only as fallbacks deeper in the stack.',
+    fpRisk: 'medium',
+    scan(content) {
+      // First family in a font-family stack is one of the overused four.
+      return scanRegex(content, /font-family\s*:\s*["']?(?:Inter|Roboto|Arial|Helvetica)\b/gi);
+    },
+  },
+
+  {
+    id: 'bounce-easing',
+    ruleRef: 'frontend.md#motion (no bounce/elastic easing)',
+    severity: 'medium',
+    category: 'ai-slop',
+    title: 'Bounce / elastic / overshoot easing',
+    recommendation: 'Feels dated. Ease out with exponential curves (ease-out-quart / quint / expo). No overshoot.',
+    fpRisk: 'low',
+    scan(content) {
+      const matches = [];
+      // Keyword easings.
+      matches.push(...scanRegex(content, /\b(?:bounce|elastic|wobble|spring)\b/gi));
+      // cubic-bezier with a y-control point > 1 or < 0 (overshoot).
+      const cb = /cubic-bezier\(\s*([\d.]+)\s*,\s*(-?[\d.]+)\s*,\s*([\d.]+)\s*,\s*(-?[\d.]+)\s*\)/gi;
+      let m;
+      cb.lastIndex = 0;
+      while ((m = cb.exec(content)) !== null) {
+        const y1 = Number(m[2]);
+        const y2 = Number(m[4]);
+        if (y1 > 1 || y2 > 1 || y1 < 0 || y2 < 0) {
+          matches.push({ line: lineOf(content, m.index), snippet: snippetAt(content, m.index), value: m[0].trim() });
+        }
+      }
+      return dedupeByLine(matches);
+    },
+  },
+
+  {
+    id: 'ai-purple-gradient',
+    ruleRef: 'frontend.md / PRODUCT anti-references (purple-to-blue gradients)',
+    severity: 'medium',
+    category: 'ai-slop',
+    title: 'Purple / indigo AI gradient',
+    recommendation:
+      'The single most recognizable AI tell. If purple is genuinely the brand, keep it flat; otherwise pick a committed strategy.',
+    fpRisk: 'high',
+    scan(content) {
+      const matches = [];
+      const grad = /\b(?:linear|radial|conic)-gradient\s*\(([^)]*)\)/gi;
+      let m;
+      grad.lastIndex = 0;
+      while ((m = grad.exec(content)) !== null) {
+        const args = m[1].toLowerCase();
+        const purpleHits = PURPLE_TOKENS.filter((t) => args.includes(t)).length;
+        const blueHits = BLUE_TOKENS.filter((t) => args.includes(t)).length;
+        // Tell = two purples, OR a purple→blue ramp.
+        if (purpleHits >= 2 || (purpleHits >= 1 && blueHits >= 1)) {
+          matches.push({ line: lineOf(content, m.index), snippet: snippetAt(content, m.index), value: m[0].trim().slice(0, 80) });
+        }
+      }
+      return dedupeByLine(matches);
+    },
+  },
+
+  {
+    id: 'pure-black-ink',
+    ruleRef: 'frontend.md (never pure black/gray — always tint)',
+    severity: 'low',
+    category: 'quality',
+    title: 'Pure black text color (#000 / black / rgb(0,0,0))',
+    recommendation: 'Pure black reads harsh on screen. Tint toward the brand hue (e.g. very dark, slightly hued ink).',
+    fpRisk: 'medium',
+    scan(content) {
+      return scanRegex(
+        content,
+        /color\s*:\s*(?:#000(?:000)?\b|black\b|rgb\(\s*0\s*,\s*0\s*,\s*0\s*\))/gi,
+      );
+    },
+  },
+
+  {
+    id: 'arbitrary-z-index',
+    ruleRef: 'frontend.md#layout (semantic z-index scale, never 999/9999)',
+    severity: 'low',
+    category: 'quality',
+    title: 'Arbitrary z-index (999 / 9999 …)',
+    recommendation: 'Build a semantic z-index scale (dropdown → sticky → modal → toast → tooltip). Never magic numbers.',
+    fpRisk: 'low',
+    scan(content) {
+      return scanRegex(content, /z-index\s*:\s*(?:9{3,})\b/gi);
+    },
+  },
+
+  {
+    id: 'layout-property-transition',
+    ruleRef: 'frontend.md#motion (don\'t animate layout properties)',
+    severity: 'low',
+    category: 'quality',
+    title: 'Animating layout properties (width/height/margin/…)',
+    recommendation:
+      'Animating layout props thrashes the main thread. Animate transform/opacity; reserve layout animation for genuine need.',
+    fpRisk: 'medium',
+    scan(content) {
+      // `transition:` shorthand whose property list includes a layout prop.
+      return scanRegex(
+        content,
+        /transition\s*:\s*[^;{}]*\b(?:width|height|top|left|right|bottom|margin|padding)\b/gi,
+      );
+    },
+  },
+];
+
+/**
+ * Collapse multiple matches on the same line into one (stable order).
+ * @param {Array<{line:number, snippet:string, value?:string}>} matches
+ */
+function dedupeByLine(matches) {
+  const byLine = new Map();
+  for (const mt of matches) {
+    if (!byLine.has(mt.line)) byLine.set(mt.line, mt);
+  }
+  return [...byLine.values()].sort((a, b) => a.line - b.line);
+}
+
+/** Stable list of rule ids (for config validation + tests). */
+export const RULE_IDS = RULES.map((r) => r.id);

package/scripts/lib/frontmatter-guard.mjs

@@ -0,0 +1,241 @@
+/**
+ * Frontmatter-Guard library (issue #328).
+ *
+ * Reads the canonical vault-frontmatter Zod schema source and exposes helpers
+ * for generating a contextual schema snippet that can be injected into agent
+ * prompts before vault-write tasks.
+ *
+ * Pure ESM, no top-level side effects. All I/O is wrapped in functions.
+ * Uses `node:fs` and `node:crypto` only — no external dependencies.
+ */
+
+import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Absolute path to the canonical vault-frontmatter schema source. */
+const SCHEMA_SOURCE_PATH = join(
+  homedir(),
+  'Projects/projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts',
+);
+
+/**
+ * In-memory mtime cache so repeated calls within a single process invocation
+ * skip the FS read when the file has not changed. Re-reads on mtime change.
+ *
+ * @type {{ mtime: number | null; result: ReturnType<typeof _parseSchema> | null }}
+ */
+const _cache = { mtime: null, result: null };
+
+/**
+ * Parse the type-enum values out of a Zod `z.enum([...])` call in source text.
+ *
+ * @param {string} text
+ * @param {string} exportName - e.g. 'vaultNoteTypeSchema'
+ * @returns {string[]}
+ */
+function _extractEnum(text, exportName) {
+  // Match: export const <name> = z.enum([ ...values... ]);
+  const re = new RegExp(
+    `export\\s+const\\s+${exportName}\\s*=\\s*z\\.enum\\(\\s*\\[([^\\]]+)\\]`,
+    's',
+  );
+  const match = text.match(re);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
+
+/**
+ * Internal parser — extracts structured info from the TS source.
+ *
+ * @param {string} text
+ * @returns {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string, schemaText: string }}
+ */
+function _parseSchema(text) {
+  const typeEnum = _extractEnum(text, 'vaultNoteTypeSchema');
+  const statusEnum = _extractEnum(text, 'vaultNoteStatusSchema');
+
+  // Required fields are id, type, created, updated — stable; extracted
+  // from the schema object declaration (non-optional fields).
+  const requiredFields = ['id', 'type', 'created', 'updated'];
+
+  // Regex values — parse from source or use hard-coded fallback that matches
+  // the known schema. Prefer source-parse for drift-safety.
+  const slugMatch = text.match(/const slugRegex\s*=\s*([^;]+);/);
+  const tagMatch = text.match(/const tagPathRegex\s*=\s*([^;]+);/);
+
+  // Convert JS regex literal /pattern/ to pattern string
+  const toPattern = (raw) => {
+    if (!raw) return null;
+    const m = raw.trim().match(/^\/(.+)\/[gimsuy]*$/);
+    return m ? m[1] : null;
+  };
+
+  const idRegex =
+    toPattern(slugMatch?.[1]) ?? '^[a-z0-9]+(?:-[a-z0-9]+)*$';
+  const tagsRegex =
+    toPattern(tagMatch?.[1]) ??
+    '^[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*$';
+
+  return { typeEnum, statusEnum, requiredFields, idRegex, tagsRegex, schemaText: text };
+}
+
+/**
+ * Read and parse the canonical vault-frontmatter schema source.
+ *
+ * Caches the result in-memory; re-reads only when the file mtime changes.
+ * Returns `null` (no throw) if the file is missing or unreadable.
+ *
+ * @returns {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string, schemaText: string } | null}
+ */
+export function readVaultSchema() {
+  let mtime;
+  try {
+    mtime = statSync(SCHEMA_SOURCE_PATH).mtimeMs;
+  } catch {
+    // File missing or inaccessible
+    return null;
+  }
+
+  if (_cache.mtime === mtime && _cache.result !== null) {
+    return _cache.result;
+  }
+
+  let text;
+  try {
+    text = readFileSync(SCHEMA_SOURCE_PATH, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const result = _parseSchema(text);
+  _cache.mtime = mtime;
+  _cache.result = result;
+  return result;
+}
+
+/**
+ * Compute an 8-character SHA-256 hex prefix of the given schema source text.
+ * Stable across calls for the same input — useful as a cache-busting token.
+ *
+ * @param {string} schemaText
+ * @returns {string}
+ */
+export function computeSchemaHash(schemaText) {
+  return digestSha256Short(schemaText);
+}
+
+/**
+ * Generate a deterministic Markdown snippet documenting the vault frontmatter
+ * schema, suitable for injection into agent prompts before vault-write tasks.
+ *
+ * @param {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string }} schema
+ * @returns {string}
+ */
+export function generateFrontmatterSnippet(schema) {
+  const { typeEnum, statusEnum, requiredFields, idRegex, tagsRegex: _tagsRegex } = schema;
+
+  const typeList = typeEnum.map((v) => `\`${v}\``).join(' | ');
+  const statusList = statusEnum.map((v) => `\`${v}\``).join(' | ');
+  const requiredList = requiredFields.map((f) => `\`${f}\``).join(', ');
+
+  return `## Vault Frontmatter Schema (REQUIRED for files under ~/Projects/vault/)
+
+**Required fields (every note):** ${requiredList}
+
+### Enums
+- **\`type\`:** ${typeList}
+- **\`status\`** (optional): ${statusList}
+
+### Field formats
+- \`id\`: kebab-case, 2-128 chars, regex \`${idRegex}\`
+- \`tags\`: array of kebab-case strings, \`/\` separator allowed (e.g., \`learning/cli-design\`)
+- \`created\` / \`updated\` / \`expires\`: ISO 8601 (\`YYYY-MM-DD\` or \`YYYY-MM-DDTHH:MM:SSZ\`)
+
+### Examples
+
+#### type: reference
+\`\`\`yaml
+id: parallel-session-rules
+type: reference
+created: 2026-05-08
+updated: 2026-05-08
+status: active
+tags: [reference/rules]
+\`\`\`
+#### type: session
+\`\`\`yaml
+id: session-2026-05-08-deep
+type: session
+created: 2026-05-08
+updated: 2026-05-08
+status: archived
+tags: [session/deep]
+\`\`\`
+#### type: learning
+\`\`\`yaml
+id: w1-discovery-shrinks-scope
+type: learning
+created: 2026-05-08
+updated: 2026-05-08
+status: active
+\`\`\`
+#### type: daily
+\`\`\`yaml
+id: 2026-05-08
+type: daily
+created: 2026-05-08
+updated: 2026-05-08
+\`\`\`
+#### type: project
+\`\`\`yaml
+id: session-orchestrator
+type: project
+created: 2026-04-01
+updated: 2026-05-08
+status: active
+\`\`\`
+`;
+}
+
+/**
+ * Heuristic detector: returns true when the current task is likely to write
+ * vault files, in which case the frontmatter-guard snippet should be injected.
+ *
+ * Detection rules (OR logic — any match returns true):
+ *   1. Any file in `fileScope` whose path contains `/Projects/vault/`.
+ *   2. Any file in `fileScope` under known vault subdirectories:
+ *      `40-learnings/`, `50-sessions/`, `03-daily/`, `01-projects/`.
+ *   3. `taskDescription` mentions "vault" or "vault-mirror" AND contains a
+ *      write-intent keyword ("write", "creat", "generat", "emit", "mirror",
+ *      "update", "add", "insert").
+ *
+ * Pure function — no I/O.
+ *
+ * @param {string} taskDescription
+ * @param {string[]} fileScope
+ * @returns {boolean}
+ */
+export function detectVaultTaskScope(taskDescription, fileScope) {
+  const VAULT_PATH_RE = /\/Projects\/vault\//;
+  const VAULT_SUBDIR_RE = /(?:40-learnings|50-sessions|03-daily|01-projects)\//;
+
+  for (const f of fileScope) {
+    if (VAULT_PATH_RE.test(f) || VAULT_SUBDIR_RE.test(f)) {
+      return true;
+    }
+  }
+
+  const desc = taskDescription.toLowerCase();
+  const mentionsVault = desc.includes('vault') || desc.includes('vault-mirror');
+  const WRITE_INTENT_RE = /\b(?:write[a-z]*|creat[a-z]*|generat[a-z]*|emit[a-z]*|mirror[a-z]*|updat[a-z]*|add[a-z]*|insert[a-z]*)\b/;
+  if (mentionsVault && WRITE_INTENT_RE.test(desc)) {
+    return true;
+  }
+
+  return false;
+}

package/scripts/lib/gates/echo-stub-detect.mjs

@@ -0,0 +1,39 @@
+/**
+ * echo-stub-detect.mjs — Detect quality-gate commands that are no-op stubs.
+ * Prevents `echo "no automated tests yet"` from producing a false-positive pass.
+ */
+
+/**
+ * Detect whether a quality-gate command is a no-op echo-stub or a `:` no-op.
+ *
+ * Detection rules (applied in order):
+ *   1. Empty / undefined / `'skip'` → not a stub (skip branch handles these).
+ *   2. Whole command equals `:`  → stub of kind `'noop'`.
+ *   3. Whole command is `echo` followed by a single quoted or simple argument
+ *      with no shell-meta tail (pipe, redirect, command-substitution, etc.)
+ *      → stub of kind `'echo'`.
+ *   4. Otherwise → not a stub.
+ *
+ * @param {string|undefined} cmd
+ * @returns {{ isStub: boolean, kind?: 'echo'|'noop' }}
+ */
+export function detectStubCommand(cmd) {
+  if (!cmd || cmd === 'skip') {
+    return { isStub: false };
+  }
+
+  const trimmed = cmd.trim();
+
+  if (trimmed === ':') {
+    return { isStub: true, kind: 'noop' };
+  }
+
+  // Matches: echo "quoted" | echo 'quoted' | echo simpleArg
+  // Rejects any shell-meta characters after the argument (|, ;, &, <, >, $, `, (, ))
+  const ECHO_STUB_RE = /^echo\s+(?:"[^"]*"|'[^']*'|[^\s|;&<>$`()]+)\s*$/;
+  if (ECHO_STUB_RE.test(trimmed)) {
+    return { isStub: true, kind: 'echo' };
+  }
+
+  return { isStub: false };
+}

package/scripts/lib/gates/gate-baseline.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// gate-baseline.mjs — baseline quality gate handler
+// Runs typecheck (tail-5) + test (tail-5); informational only, always exits 0.
+//
+// Required env: TYPECHECK_CMD, TEST_CMD
+// Each may equal "skip" or empty string → treated as skip.
+
+import { runCheck } from './gate-helpers.mjs';
+
+const typecheckCmd = process.env.TYPECHECK_CMD;
+const testCmd = process.env.TEST_CMD;
+
+if (!typecheckCmd) {
+  process.stderr.write('TYPECHECK_CMD must be set\n');
+  process.exit(1);
+}
+if (!testCmd) {
+  process.stderr.write('TEST_CMD must be set\n');
+  process.exit(1);
+}
+
+let tcResult = { status: 'skip', output: '' };
+let testResult = { status: 'skip', output: '' };
+
+if (typecheckCmd !== 'skip') {
+  tcResult = await runCheck(typecheckCmd);
+}
+
+if (testCmd !== 'skip') {
+  testResult = await runCheck(testCmd);
+}
+
+const result = {
+  variant: 'baseline',
+  typecheck: tcResult.status,
+  test: testResult.status,
+  typecheck_output: tcResult.output,
+  test_output: testResult.output,
+};
+
+process.stdout.write(JSON.stringify(result) + '\n');
+process.exit(0);

package/scripts/lib/gates/gate-full.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// gate-full.mjs — full-gate quality gate handler
+// Runs typecheck + tests + lint sequentially; exits 2 if any check fails, 0 otherwise.
+//
+// Required env: TYPECHECK_CMD, TEST_CMD, LINT_CMD (each may equal "skip")
+// Optional env: SESSION_START_REF
+
+import {
+  runCheck,
+  extractCount,
+  extractTestCounts,
+  collectDebugArtifacts,
+} from './gate-helpers.mjs';
+
+const typecheckCmd = process.env.TYPECHECK_CMD;
+const testCmd = process.env.TEST_CMD;
+const lintCmd = process.env.LINT_CMD;
+const sessionStartRef = process.env.SESSION_START_REF ?? '';
+
+if (!typecheckCmd) {
+  process.stderr.write('TYPECHECK_CMD must be set\n');
+  process.exit(1);
+}
+if (!testCmd) {
+  process.stderr.write('TEST_CMD must be set\n');
+  process.exit(1);
+}
+if (!lintCmd) {
+  process.stderr.write('LINT_CMD must be set\n');
+  process.exit(1);
+}
+
+const startTime = Date.now();
+
+// --- Typecheck ---
+const tcResult = runCheck(typecheckCmd);
+const tcErrorCount =
+  tcResult.status === 'fail'
+    ? extractCount(tcResult.output, /error TS\d+/)
+    : 0;
+
+// --- Test ---
+const testResult = runCheck(testCmd);
+const { passed: testPassed, total: testTotal } =
+  testResult.status !== 'skip'
+    ? extractTestCounts(testResult.output)
+    : { passed: 0, total: 0 };
+
+// --- Lint ---
+const lintResult = runCheck(lintCmd);
+const lintWarnings =
+  lintResult.status !== 'skip'
+    ? extractCount(lintResult.output, /warning/i)
+    : 0;
+
+// --- Debug artifacts ---
+const debugArtifacts = collectDebugArtifacts(sessionStartRef);
+
+// --- Duration ---
+const durationSeconds = Math.round((Date.now() - startTime) / 1000);
+
+// --- Stub map ---
+const stubbed = {};
+if (tcResult.stubbed) stubbed.typecheck = tcResult.stubbed;
+if (testResult.stubbed) stubbed.test = testResult.stubbed;
+if (lintResult.stubbed) stubbed.lint = lintResult.stubbed;
+
+// --- Output ---
+const output = {
+  variant: 'full-gate',
+  duration_seconds: durationSeconds,
+  typecheck: { status: tcResult.status, error_count: tcErrorCount },
+  test: { status: testResult.status, total: testTotal, passed: testPassed },
+  lint: { status: lintResult.status, warnings: lintWarnings },
+  debug_artifacts: debugArtifacts,
+  stubbed,
+};
+
+process.stdout.write(JSON.stringify(output) + '\n');
+
+// Exit 2 if any check failed; skipped counts as pass.
+const failed = [tcResult, testResult, lintResult].some(
+  (r) => r.status === 'fail',
+);
+process.exit(failed ? 2 : 0);