@kodevibe/harness 0.11.0 → 0.11.2

package/src/guard.js

@@ -0,0 +1,717 @@
+'use strict';
+
+// kode:harness — Deterministic Guardrail (Harness Guard)
+//
+// Purpose: mechanically eliminate the top recurring root causes that LLMs
+// fail to honor via markdown instructions alone. Pure functions (no I/O) so
+// they are trivially testable; runGuard() is the only file-reading wrapper.
+//
+// Checks:
+//   R5  scanSecrets        — Iron Law #4 (no hardcoded credentials)
+//   R1  checkStateFile     — Iron Law #8/#11 (session handoff + proof-first)
+//   R3  checkReviewerHandoff — reviewed/done work must be handoff-ready
+//   R6  lintMarkdownTables — L3-8 (markdown state file integrity)
+//   R6  lintLineLimit      — project-state.md "keep under 200 lines"
+//   R7  checkStateSync     — Story/feature/dependency state stays in sync
+//   R8  checkPublicBoundary — public package surface does not leak internal refs
+//   R9  checkEnvSeal       — proof records include reproducible environment seal
+//   R10 checkInstructionBudget — instruction files fit model-tier budgets
+//
+// Severity: 'error' blocks the commit (exit 1). 'warn' is informational.
+
+// ─── Secret patterns (R5 / Iron Law #4) ──────────────────────────────
+// Conservative set to minimize false positives. Each entry: { id, re, label }.
+const SECRET_PATTERNS = [
+  { id: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/, label: 'AWS access key id' },
+  { id: 'github-token', re: /\bgh[pousr]_[0-9A-Za-z]{36,}\b/, label: 'GitHub token' },
+  { id: 'slack-token', re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/, label: 'Slack token' },
+  { id: 'private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/, label: 'private key block' },
+  { id: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/, label: 'Google API key' },
+  // Generic assignment: key/secret/password/token = "literal value"
+  {
+    id: 'generic-secret-assignment',
+    re: /\b(?:api[_-]?key|secret|password|passwd|pwd|access[_-]?token|auth[_-]?token|private[_-]?key)\b\s*[:=]\s*['"]([^'"\n]{8,})['"]/i,
+    label: 'hardcoded secret assignment',
+  },
+];
+
+// Values that look like secrets but are safe placeholders / env references.
+const SECRET_ALLOWLIST = [
+  /process\.env/i,
+  /os\.environ/i,
+  /import\.meta\.env/i,
+  /\bgetenv\b/i,
+  /\byour[_-]?(?:api[_-]?key|token|secret|password)\b/i,
+  /\bexample\b/i,
+  /\bplaceholder\b/i,
+  /\bchangeme\b/i,
+  /\bdummy\b/i,
+  /\bredacted\b/i,
+  /\bxxx+\b/i,
+  /\bsample\b/i,
+  /<[^>]+>/, // <your-token-here>
+  /\$\{[^}]+\}/, // ${TOKEN}
+  /\*{3,}/, // ****
+  // Config/reference patterns: the value is a name/path/enum, not a literal secret.
+  /(?:_env(?:_var)?|_name|_key_id|_path|_file|_field|_header|_param|_var)\b/i,
+  /\b(?:enum|type|interface|column|field|label)\b/i,
+];
+
+function isAllowlisted(line) {
+  return SECRET_ALLOWLIST.some((re) => re.test(line));
+}
+
+function decodedBase64Secret(line) {
+  const candidates = line.matchAll(/['"]([A-Za-z0-9+/]{24,}={0,2})['"]/g);
+  for (const m of candidates) {
+    const raw = m[1];
+    if (raw.length % 4 !== 0) continue;
+    let decoded = '';
+    try {
+      decoded = Buffer.from(raw, 'base64').toString('utf8');
+    } catch {
+      continue;
+    }
+    if (!decoded || decoded.includes('\uFFFD')) continue;
+    const printable = decoded.replace(/[\t\r\n\x20-\x7E]/g, '').length === 0;
+    if (!printable) continue;
+    const hit = SECRET_PATTERNS.find((pat) => pat.re.test(decoded));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Scan text for hardcoded credentials.
+ * @param {string} content
+ * @param {string} [filename]
+ * @returns {Array<{check:string,severity:string,line:number,message:string}>}
+ */
+function scanSecrets(content, filename = '') {
+  const violations = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isAllowlisted(line)) continue;
+    const decodedHit = decodedBase64Secret(line);
+    if (decodedHit) {
+      violations.push({
+        check: 'secret',
+        severity: 'error',
+        line: i + 1,
+        message: `${filename ? filename + ': ' : ''}possible base64-encoded ${decodedHit.label} (${decodedHit.id}) on line ${i + 1}`,
+      });
+      continue;
+    }
+    for (const pat of SECRET_PATTERNS) {
+      if (pat.re.test(line)) {
+        violations.push({
+          check: 'secret',
+          severity: 'error',
+          line: i + 1,
+          message: `${filename ? filename + ': ' : ''}possible ${pat.label} (${pat.id}) on line ${i + 1}`,
+        });
+        break; // one finding per line is enough
+      }
+    }
+  }
+  return violations;
+}
+
+// ─── State file checker (R1 / Iron Law #8 + #11) ─────────────────────
+
+// Template sentinel: identical to runValidate() in init.js (unfilled template).
+const STATE_TEMPLATE_SENTINEL = 'S1-1 | Project scaffolding';
+
+function stripHtmlComments(content) {
+  return content.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+function getSection(content, header) {
+  // Returns the body text between `## header` and the next `## ` (or EOF).
+  const re = new RegExp(`^##\\s+${header}\\s*$`, 'm');
+  const m = re.exec(content);
+  if (!m) return null;
+  const start = m.index + m[0].length;
+  const rest = content.slice(start);
+  const next = /^##\s+/m.exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+}
+
+function parseMarkdownTable(section) {
+  const lines = section.split('\n').map((l) => l.trim()).filter((l) => l.startsWith('|'));
+  if (lines.length < 2) return [];
+  const header = lines[0].replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+  return lines.slice(2)
+    .filter((line) => !/^\|\s*[-:|\s]+\|?$/.test(line))
+    .map((line) => {
+      const cells = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+      const row = {};
+      header.forEach((name, i) => { row[name] = cells[i] || ''; });
+      row.__raw = line;
+      return row;
+    });
+}
+
+function storyIdFromRow(row) {
+  return row.ID || row.Id || row.Story || row['Story ID'] || row['Story'] || '';
+}
+
+function rowStatus(row) {
+  return row.Status || row.status || '';
+}
+
+/**
+ * Validate docs/project-state.md content for handoff + proof-first integrity.
+ * @param {string} content
+ * @returns {Array<{check:string,severity:string,line:number,message:string}>}
+ */
+function checkStateFile(content) {
+  const violations = [];
+  const visible = stripHtmlComments(content);
+
+  // 1) Unfilled template sentinel still present → setup not run.
+  if (content.includes(STATE_TEMPLATE_SENTINEL)) {
+    violations.push({
+      check: 'state',
+      severity: 'error',
+      line: 0,
+      message: 'project-state.md still contains the unfilled template (run setup before committing work).',
+    });
+  }
+
+  // 2) Quick Summary must have the 3 handoff lines filled (outside comments).
+  const quick = getSection(visible, 'Quick Summary');
+  if (quick !== null) {
+    const hasDone = /✅/.test(quick);
+    const hasProgress = /🔄/.test(quick);
+    const hasNext = /➡️/.test(quick);
+    if (!(hasDone && hasProgress && hasNext)) {
+      violations.push({
+        check: 'state',
+        severity: 'error',
+        line: 0,
+        message: 'Quick Summary is missing the 3 handoff lines (✅ last / 🔄 in-progress / ➡️ next). Update before commit (Iron Law #8).',
+      });
+    }
+  }
+
+  // 3) Proof-First: any ✅ done Story requires at least one Proof Ledger row.
+  //    Strict: only a Story Status *table row* whose status cell is "✅ done"
+  //    counts (avoids false positives from prose mentioning "✅ done").
+  const storySection = getSection(visible, 'Story Status') || '';
+  const hasDoneStory = /^\s*\|.*\|\s*✅\s*done\s*(?:\|.*)?$/m.test(storySection);
+  if (hasDoneStory) {
+    const ledger = getSection(visible, 'Proof Ledger') || '';
+    // A real ledger row is a table data row referencing a result (✅/❌/pass/fail).
+    const hasLedgerRow = /\|.*\|.*\|.*(✅|❌|pass|fail).*\|/i.test(ledger);
+    if (!hasLedgerRow) {
+      violations.push({
+        check: 'state',
+        severity: 'error',
+        line: 0,
+        message: 'A Story is marked "✅ done" but the Proof Ledger has no proof row (Iron Law #11 Proof-First).',
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ─── Reviewer Handoff Gate (R3) ──────────────────────────────────────
+
+/**
+ * Reviewer Handoff DoD: reviewed/done Stories must carry a compact handoff row
+ * so the next session can continue from evidence, risks, and next action.
+ *
+ * @param {string} content project-state.md
+ * @returns {Array}
+ */
+function checkReviewerHandoff(content) {
+  const violations = [];
+  const visible = stripHtmlComments(content);
+  const storyRows = parseMarkdownTable(getSection(visible, 'Story Status') || '');
+  const completed = storyRows.filter((row) => /✅\s*done|reviewed|리뷰\s*완료/i.test(rowStatus(row)));
+  if (completed.length === 0) return violations;
+
+  const handoff = getSection(visible, 'Reviewer Handoff') || '';
+  const handoffRows = parseMarkdownTable(handoff);
+
+  for (const story of completed) {
+    const id = storyIdFromRow(story);
+    const match = handoffRows.find((row) => Object.values(row).some((v) => typeof v === 'string' && v.includes(id)));
+    if (!match) {
+      violations.push({
+        check: 'handoff',
+        severity: 'error',
+        line: 0,
+        message: `Story ${id || '(unknown)'} is reviewed/done but has no Reviewer Handoff row (R3). Add evidence, risk/blocker, and next-action handoff before closing.`,
+      });
+      continue;
+    }
+    const raw = match.__raw || '';
+    if (!/(proof|evidence|증거|risk|blocker|next|다음|handoff)/i.test(raw)) {
+      violations.push({
+        check: 'handoff',
+        severity: 'error',
+        line: 0,
+        message: `Story ${id || '(unknown)'} Reviewer Handoff row is too thin. Include proof/evidence, risk or blocker, and next action (R3).`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ─── Learn Completion Gate (R2 / wrap-up + Iron Law #8) ──────────────
+
+/**
+ * Verify that a session-end "Learn / wrap-up" actually completed its required
+ * outputs. The recurring failure (실증 #2) was that Step 6 (Learn) ran
+ * selectively, leaving state files stale. This gate is invoked only when the
+ * caller asserts a wrap-up just happened (e.g. CLI --wrap-up), so it does not
+ * fire on ordinary commits.
+ *
+ * Required outputs of a non-quiet session:
+ *   1. project-state.md Quick Summary 3 handoff lines  (checked here too)
+ *   2. project-state.md has a Recent Changes entry for the session
+ *   3. features.md is not the untouched template (if features were added)
+ *
+ * @param {{projectState?:string, features?:string, quiet?:boolean}} files
+ * @returns {Array}
+ */
+function checkLearnCompletion({ projectState = '', features = '', quiet = false } = {}) {
+  const violations = [];
+  if (quiet) return violations; // zero-change session: wrap-up legitimately skips most steps
+
+  const ps = stripHtmlComments(projectState);
+
+  // 1) Quick Summary handoff lines (reuse the strict rule).
+  const quick = getSection(ps, 'Quick Summary');
+  if (quick !== null) {
+    if (!(/✅/.test(quick) && /🔄/.test(quick) && /➡️/.test(quick))) {
+      violations.push({
+        check: 'learn',
+        severity: 'error',
+        line: 0,
+        message: 'Learn incomplete: Quick Summary handoff lines (✅/🔄/➡️) not updated at session end (wrap-up Step 4).',
+      });
+    }
+  }
+
+  // 2) Recent Changes must have at least one real entry (not just the template comment).
+  const recent = getSection(ps, 'Recent Changes');
+  if (recent !== null) {
+    const hasEntry = recent.split('\n').some((l) => {
+      const t = l.trim();
+      return t.length > 0 && !t.startsWith('<!--') && !t.startsWith('-->') && (t.startsWith('-') || t.startsWith('|') || t.startsWith('*'));
+    });
+    if (!hasEntry) {
+      violations.push({
+        check: 'learn',
+        severity: 'error',
+        line: 0,
+        message: 'Learn incomplete: Recent Changes has no session entry (wrap-up Step 4 not finished).',
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ─── State Auto-Sync Gate (R7) ───────────────────────────────────────
+
+function splitPathList(value) {
+  return String(value || '')
+    .split(/[,;<br>`]+|\s{2,}/)
+    .map((v) => v.trim())
+    .filter((v) => v && !/^n\/a$/i.test(v) && !/^\(?none\)?$/i.test(v));
+}
+
+/**
+ * Cross-check project-state.md, features.md, and dependency-map.md so LLM state
+ * updates cannot drift silently after code/docs changes.
+ *
+ * @param {{projectState?:string, features?:string, dependencyMap?:string}} files
+ * @returns {Array}
+ */
+function checkStateSync({ projectState = '', features = '', dependencyMap = '' } = {}) {
+  const violations = [];
+  const stateVisible = stripHtmlComments(projectState);
+  const featureVisible = stripHtmlComments(features);
+  const depVisible = stripHtmlComments(dependencyMap);
+
+  const storyRows = parseMarkdownTable(getSection(stateVisible, 'Story Status') || '');
+  const doneStories = storyRows.filter((row) => /✅\s*done/i.test(rowStatus(row)));
+  const featureSection = getSection(featureVisible, 'Feature Registry')
+    || getSection(featureVisible, 'Feature List')
+    || featureVisible;
+  const featureRows = parseMarkdownTable(featureSection);
+  const depSection = getSection(depVisible, 'Module Dependency Map')
+    || getSection(depVisible, 'Module Map')
+    || depVisible;
+  const depRows = parseMarkdownTable(depSection);
+  const depText = depRows.map((row) => Object.values(row).join(' ')).join('\n');
+
+  for (const story of doneStories) {
+    const id = storyIdFromRow(story);
+    const matchedFeature = featureRows.find((row) => Object.values(row).some((v) => typeof v === 'string' && v.includes(id)));
+    if (!matchedFeature) {
+      violations.push({
+        check: 'sync',
+        severity: 'error',
+        line: 0,
+        message: `Story ${id || '(unknown)'} is done but no feature registry row references it (R7 state auto-sync).`,
+      });
+    }
+  }
+
+  for (const feature of featureRows) {
+    const keyFiles = feature['Key Files'] || feature['Key files'] || feature.Files || feature.Scope || '';
+    for (const file of splitPathList(keyFiles)) {
+      if (/^docs\//.test(file)) continue;
+      const firstSegment = file.split('/').filter(Boolean)[0];
+      if (firstSegment && depText && !depText.includes(firstSegment) && !depText.includes(file)) {
+        violations.push({
+          check: 'sync',
+          severity: 'error',
+          line: 0,
+          message: `Feature registry references ${file}, but dependency-map.md does not mention it (R7 state auto-sync).`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ─── Integration / Persistence DoD (R4) ──────────────────────────────
+
+// Evidence terms that prove only in-memory/unit behaviour (insufficient alone).
+const UNIT_ONLY_TERMS = /\bunit\b|단위\s*테스트/i;
+// Evidence terms that prove integration / persistence reached real boundaries.
+const INTEGRATION_TERMS = /\bintegration\b|통합|\bpersist|영속|\brow count|적재|\bcontext test|\be2e\b|database|\bdb\b|repository|commit boundary/i;
+
+/**
+ * Integration/Persistence DoD: a Story marked "✅ done" must have at least one
+ * Proof Ledger row whose evidence indicates integration/persistence — not only
+ * unit tests. Root cause (실증 #3 FP-KR-005): green unit tests hid a commit-
+ * boundary defect (LAMT=0). This makes "green unit tests alone = done" illegal.
+ *
+ * @param {string} content  project-state.md
+ * @returns {Array}
+ */
+function checkIntegrationDoD(content) {
+  const violations = [];
+  const visible = stripHtmlComments(content);
+  const storySection = getSection(visible, 'Story Status') || '';
+  const hasDoneStory = /^\s*\|.*\|\s*✅\s*done\s*(?:\|.*)?$/m.test(storySection);
+  if (!hasDoneStory) return violations;
+
+  const ledger = getSection(visible, 'Proof Ledger') || '';
+  const rows = ledger.split('\n').filter((l) => {
+    const t = l.trim();
+    return t.startsWith('|') && /(✅|❌|pass|fail)/i.test(t) && !/^\|\s*[-:|\s]+\|?$/.test(t);
+  });
+  if (rows.length === 0) return violations; // Proof-First rule (checkStateFile) handles the empty case.
+
+  const hasIntegrationEvidence = rows.some((r) => INTEGRATION_TERMS.test(r));
+  const onlyUnitEvidence = rows.every((r) => UNIT_ONLY_TERMS.test(r) && !INTEGRATION_TERMS.test(r));
+
+  if (!hasIntegrationEvidence && onlyUnitEvidence) {
+    violations.push({
+      check: 'integration',
+      severity: 'error',
+      line: 0,
+      message: 'A "✅ done" Story has only unit-test proof. Add integration/persistence evidence (row count, context/DB test) before marking done (R4 DoD — green unit tests can hide persistence defects).',
+    });
+  }
+  return violations;
+}
+
+// ─── Environment Seal Gate (R9) ──────────────────────────────────────
+
+/**
+ * Proof rows for done Stories need enough environment detail to reproduce the
+ * result. This catches "works on my machine" proof drift.
+ *
+ * @param {string} content project-state.md
+ * @returns {Array}
+ */
+function checkEnvSeal(content) {
+  const violations = [];
+  const visible = stripHtmlComments(content);
+  const storyRows = parseMarkdownTable(getSection(visible, 'Story Status') || '');
+  const hasDoneStory = storyRows.some((row) => /✅\s*done/i.test(rowStatus(row)));
+  if (!hasDoneStory) return violations;
+
+  const ledger = getSection(visible, 'Proof Ledger') || '';
+  const passingProof = parseMarkdownTable(ledger).some((row) => /(✅|pass)/i.test(Object.values(row).join(' ')));
+  if (!passingProof) return violations;
+
+  const env = getSection(visible, 'Environment Seal') || '';
+  const hasCommit = /\b(commit|sha|head|revision)\b\s*[:=]/i.test(env);
+  const hasRuntime = /\b(node|npm|python|java|jdk|go|rust|os)\b\s*[:=]/i.test(env);
+  const hasCommand = /\b(command|proof|test|검증)\b\s*[:=]/i.test(env);
+  if (!(hasCommit && hasRuntime && hasCommand)) {
+    violations.push({
+      check: 'env-seal',
+      severity: 'error',
+      line: 0,
+      message: 'Done Story proof is missing Environment Seal details (R9). Add commit/head, runtime/OS, and proof command before closing.',
+    });
+  }
+
+  return violations;
+}
+
+// ─── Public Boundary Gate (R8) ───────────────────────────────────────
+
+const PUBLIC_LEAK_PATTERNS = [
+  { id: 'local-path', re: /(?:^|[\s"'(])(?:\/Users\/|file:\/\/|[A-Za-z]:\\)/, label: 'local machine path' },
+  { id: 'private-page-id', re: /\bpageId\b\s*[:=]?\s*`?["']?\d{6,}\b/i, label: 'private pageId' },
+  { id: 'private-wiki-url', re: /https?:\/\/[^/\s]*(?:atlassian|confluence|jira|wiki)[^/\s]*/i, label: 'private docs URL' },
+  { id: 'container-registry', re: /\b[A-Za-z0-9.-]*(?:acr|registry)[A-Za-z0-9.-]*\.(?:azurecr\.io|local|internal)\b/i, label: 'internal registry reference' },
+];
+
+/**
+ * Detect internal references that must not ship in the public npm package.
+ *
+ * @param {string} content
+ * @param {string} [filename]
+ * @returns {Array}
+ */
+function checkPublicBoundary(content, filename = '') {
+  const violations = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const pat of PUBLIC_LEAK_PATTERNS) {
+      if (pat.re.test(line)) {
+        violations.push({
+          check: 'public-boundary',
+          severity: 'error',
+          line: i + 1,
+          message: `${filename ? filename + ': ' : ''}public package surface contains ${pat.label} (${pat.id}) on line ${i + 1} (R8 two-track boundary).`,
+        });
+        break;
+      }
+    }
+  }
+  return violations;
+}
+
+// ─── Markdown lint (R6 / L3-8) ───────────────────────────────────────
+
+/**
+ * Detect malformed markdown tables (column count mismatch vs header).
+ * Only inspects contiguous table blocks (lines starting with `|`).
+ * @param {string} content
+ * @param {string} [filename]
+ * @returns {Array<{check:string,severity:string,line:number,message:string}>}
+ */
+function lintMarkdownTables(content, filename = '') {
+  const violations = [];
+  const lines = content.split('\n');
+  let headerCols = null;
+  let inComment = false;
+
+  const countCols = (row) => {
+    // Trim leading/trailing pipe, then split. Escaped \| is rare in state files.
+    const trimmed = row.trim().replace(/^\|/, '').replace(/\|$/, '');
+    return trimmed.split('|').length;
+  };
+  const isSeparator = (row) => /^\s*\|?[\s:|-]+\|?\s*$/.test(row) && row.includes('-');
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    // Skip HTML comment blocks (templates embed example tables in comments).
+    if (raw.includes('<!--')) inComment = true;
+    if (inComment) {
+      if (raw.includes('-->')) inComment = false;
+      continue;
+    }
+    const line = raw.trim();
+    if (line.startsWith('|')) {
+      if (headerCols === null) {
+        headerCols = countCols(line);
+      } else if (isSeparator(line)) {
+        // separator row — ignore column count
+      } else {
+        const cols = countCols(line);
+        if (cols !== headerCols) {
+          violations.push({
+            check: 'markdown',
+            severity: 'error',
+            line: i + 1,
+            message: `${filename ? filename + ': ' : ''}table row on line ${i + 1} has ${cols} columns, expected ${headerCols}.`,
+          });
+        }
+      }
+    } else if (line === '') {
+      headerCols = null; // table block ended
+    }
+  }
+  return violations;
+}
+
+/**
+ * Enforce a maximum line count (state files must stay compact).
+ * @param {string} content
+ * @param {number} limit
+ * @param {string} [filename]
+ */
+function lintLineLimit(content, limit, filename = '') {
+  const count = content.split('\n').length;
+  if (count > limit) {
+    return [{
+      check: 'markdown',
+      severity: 'warn',
+      line: 0,
+      message: `${filename ? filename + ': ' : ''}${count} lines exceeds the ${limit}-line limit — archive completed entries.`,
+    }];
+  }
+  return [];
+}
+
+// ─── Model-Tier Instruction Budget (R10) ─────────────────────────────
+
+const INSTRUCTION_BUDGETS = {
+  dispatcher: { words: 1500, tokens: 1950 },
+  skill: { words: 2500, tokens: 3250 },
+  agent: { words: 2500, tokens: 3250 },
+};
+
+function estimateTokens(content) {
+  const words = content.trim() ? content.trim().split(/\s+/).length : 0;
+  return { words, tokens: Math.ceil(words * 1.3) };
+}
+
+function instructionRoleForFile(file) {
+  if (/core-rules\.md$|copilot-instructions\.md$|AGENTS\.md$|CLAUDE\.md$/.test(file)) return 'dispatcher';
+  if (/\/skills\/|\.skill\.md$/.test(file)) return 'skill';
+  if (/\/agents\/|\.agent\.md$|\.toml$/.test(file)) return 'agent';
+  return null;
+}
+
+/**
+ * Keep generated instructions inside model-tier budgets so smaller/private LLMs
+ * can follow the harness without context collapse.
+ *
+ * @param {string} content
+ * @param {string} filename
+ * @param {string} [role]
+ * @returns {Array}
+ */
+function checkInstructionBudget(content, filename = '', role = instructionRoleForFile(filename)) {
+  if (!role || !INSTRUCTION_BUDGETS[role]) return [];
+  const budget = INSTRUCTION_BUDGETS[role];
+  const usage = estimateTokens(content);
+  if (usage.words <= budget.words && usage.tokens <= budget.tokens) return [];
+  return [{
+    check: 'model-budget',
+    severity: 'error',
+    line: 0,
+    message: `${filename ? filename + ': ' : ''}${role} instruction budget exceeded (${usage.words} words / ~${usage.tokens} tokens; limit ${budget.words} words / ~${budget.tokens} tokens) (R10).`,
+  }];
+}
+
+// ─── Orchestrator ────────────────────────────────────────────────────
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_LINE_LIMITS = { 'project-state.md': 200 };
+const PUBLIC_PACKAGE_PATHS = [
+  /^bin\//,
+  /^src\//,
+  /^harness\//,
+  /^templates\//,
+  /^README(?:\.ko)?\.md$/,
+  /^LICENSE$/,
+  /^package\.json$/,
+];
+
+function isStateFile(file) {
+  return /(?:^|\/)(?:docs|\.harness)\/project-state\.md$/.test(file);
+}
+
+function isStateMarkdownFile(file) {
+  return /(?:^|\/)(?:docs|\.harness)\/(?:project-state|features|dependency-map|project-brief|failure-patterns)\.md$/.test(file);
+}
+
+function isScannableForSecrets(file) {
+  return /\.(js|ts|jsx|tsx|json|jsonc|ya?ml|env|sh|py|java|md|properties|toml)$/i.test(file)
+    && !/\.lock$/.test(file);
+}
+
+function isPublicPackageFile(file) {
+  const normalized = file.replace(/\\/g, '/');
+  return PUBLIC_PACKAGE_PATHS.some((re) => re.test(normalized));
+}
+
+/**
+ * Run all guard checks over a set of files.
+ * @param {{files: string[], cwd?: string}} opts
+ * @returns {{ok: boolean, violations: Array, errorCount: number, warnCount: number, scanned: number}}
+ */
+function runGuard({ files, cwd = process.cwd() }) {
+  const all = [];
+  let scanned = 0;
+
+  for (const file of files) {
+    const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+    const content = fs.readFileSync(abs, 'utf8');
+    const rel = path.relative(cwd, abs);
+    scanned++;
+
+    if (isScannableForSecrets(file)) {
+      all.push(...scanSecrets(content, rel));
+    }
+    if (isPublicPackageFile(rel)) {
+      all.push(...checkPublicBoundary(content, rel));
+    }
+    if (file.endsWith('.md') && isStateMarkdownFile(file)) {
+      all.push(...lintMarkdownTables(content, rel));
+    }
+    if (file.endsWith('.md')) {
+      all.push(...checkInstructionBudget(content, rel));
+    }
+    if (isStateFile(file)) {
+      const base = path.basename(file);
+      all.push(...checkStateFile(content));
+      all.push(...checkReviewerHandoff(content));
+      all.push(...checkIntegrationDoD(content));
+      all.push(...checkEnvSeal(content));
+      if (STATE_LINE_LIMITS[base]) {
+        all.push(...lintLineLimit(content, STATE_LINE_LIMITS[base], rel));
+      }
+    }
+  }
+
+  const errorCount = all.filter((v) => v.severity === 'error').length;
+  const warnCount = all.filter((v) => v.severity === 'warn').length;
+  return { ok: errorCount === 0, violations: all, errorCount, warnCount, scanned };
+}
+
+module.exports = {
+  scanSecrets,
+  checkStateFile,
+  checkReviewerHandoff,
+  checkLearnCompletion,
+  checkStateSync,
+  checkIntegrationDoD,
+  checkEnvSeal,
+  checkPublicBoundary,
+  lintMarkdownTables,
+  lintLineLimit,
+  checkInstructionBudget,
+  estimateTokens,
+  runGuard,
+  isScannableForSecrets,
+  isStateFile,
+  isStateMarkdownFile,
+  isPublicPackageFile,
+  SECRET_PATTERNS,
+};