@jaimevalasek/aioson 1.21.7 → 1.22.0

package/src/harness/contract-schema.js

@@ -0,0 +1,324 @@
+'use strict';
+
+/**
+ * Validação de schema do harness-contract.json (loop-guardrails REQ-1).
+ *
+ * Responsabilidade distinta de `harness:validate` (que valida a IMPLEMENTAÇÃO
+ * contra criteria via @validator). Aqui valida-se o CONTRATO em si, no
+ * preflight do `self:loop` — um typo em `allowed_files` não pode desligar o
+ * scope guard silenciosamente. Mensagens usam "contract schema invalid",
+ * nunca "validation verdict".
+ *
+ * Retrocompat (REQ-11 / EC-12): contratos antigos (feature/contract_mode/
+ * governor/criteria) passam; campos novos são todos opcionais.
+ */
+
+const { validateGlobPattern } = require('./glob-match');
+
+/** REQ-4 — defaults proibidos, sempre aplicados e não-removíveis (SEC-SBD-05). */
+const DEFAULT_FORBIDDEN_GLOBS = Object.freeze([
+  '.env*',
+  '*.pem',
+  '*.key',
+  'secrets/**',
+  '.git/**',
+  'node_modules/**',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'npm-shrinkwrap.json',
+  'bun.lockb'
+]);
+
+const HUMAN_GATE_THEMES = Object.freeze([
+  'payment_logic_change',
+  'auth_permission_change',
+  'database_destructive_change',
+  'publish'
+]);
+
+/** Mapa default tema→globs (requirements §2.1); override via human_gate.themes[].paths. */
+const DEFAULT_THEME_PATHS = Object.freeze({
+  payment_logic_change: Object.freeze(['**/billing/**', '**/payment/**']),
+  auth_permission_change: Object.freeze(['**/auth/**']),
+  database_destructive_change: Object.freeze(['**/migrations/**']),
+  publish: Object.freeze([]) // gate de comando (REQ-13), nunca diff
+});
+
+/**
+ * Presets do contract_mode (REQ-19). Preenchem apenas valores do governor
+ * NÃO definidos explicitamente no contrato; valor explícito sempre vence.
+ * `BALANCED` mantém o comportamento atual (nenhum preenchimento).
+ */
+const CONTRACT_PRESETS = Object.freeze({
+  safe: Object.freeze({
+    max_steps: 10,
+    error_streak_limit: 3,
+    cost_ceiling_tokens: 200000,
+    max_runtime_minutes: 30,
+    max_changed_files: 20,
+    max_diff_lines: 1500
+  }),
+  builder: Object.freeze({
+    max_steps: 30,
+    error_streak_limit: 5,
+    cost_ceiling_tokens: 1000000,
+    max_runtime_minutes: 120,
+    max_changed_files: 60,
+    max_diff_lines: 6000
+  }),
+  autopilot: Object.freeze({
+    max_steps: 50,
+    error_streak_limit: 8,
+    cost_ceiling_tokens: 3000000,
+    max_runtime_minutes: 360,
+    max_changed_files: null,
+    max_diff_lines: null
+  })
+});
+
+const KNOWN_TOP_FIELDS = new Set([
+  'feature', 'contract_mode', 'governor', 'criteria',
+  'allowed_files', 'forbidden_files', 'human_gate'
+]);
+const KNOWN_GOVERNOR_FIELDS = new Set([
+  'max_steps', 'error_streak_limit', 'cost_ceiling_tokens',
+  'max_runtime_minutes', 'max_changed_files', 'max_diff_lines'
+]);
+const KNOWN_HUMAN_GATE_FIELDS = new Set(['required_for', 'themes']);
+const KNOWN_THEME_FIELDS = new Set(['name', 'paths']);
+const KNOWN_CRITERIA_FIELDS = new Set(['id', 'description', 'assertion', 'binary', 'verification']);
+
+const VALID_MODES = new Set(['balanced', 'safe', 'builder', 'autopilot']);
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isPositiveInt(v) {
+  return Number.isInteger(v) && v > 0;
+}
+
+function checkOptionalLimit(errors, field, value) {
+  if (value === undefined || value === null) return;
+  if (!isPositiveInt(value)) {
+    errors.push({ field, reason: 'must be a positive integer or null' });
+  }
+}
+
+function checkGlobArray(errors, field, value) {
+  if (!Array.isArray(value)) {
+    errors.push({ field, reason: 'must be an array of glob strings' });
+    return;
+  }
+  value.forEach((pattern, i) => {
+    const result = validateGlobPattern(pattern);
+    if (!result.ok) {
+      errors.push({ field: `${field}[${i}]`, reason: result.reason });
+    }
+  });
+}
+
+/**
+ * Valida o contrato. Retorna { ok, errors: [{field, reason}], warnings: [{field, reason}] }.
+ * `ok === false` quando há ao menos um erro — o preflight deve encerrar antes
+ * de qualquer execução (REQ-1).
+ */
+function validateContract(contract) {
+  const errors = [];
+  const warnings = [];
+
+  if (!isPlainObject(contract)) {
+    return { ok: false, errors: [{ field: '(root)', reason: 'contract must be a JSON object' }], warnings };
+  }
+
+  for (const key of Object.keys(contract)) {
+    if (!KNOWN_TOP_FIELDS.has(key)) {
+      errors.push({ field: key, reason: 'unknown field — check for typos (contract schema invalid)' });
+    }
+  }
+
+  if (typeof contract.feature !== 'string' || !contract.feature.trim()) {
+    errors.push({ field: 'feature', reason: 'must be a non-empty string' });
+  }
+
+  if (contract.contract_mode !== undefined) {
+    if (typeof contract.contract_mode !== 'string' || !VALID_MODES.has(contract.contract_mode.toLowerCase())) {
+      errors.push({ field: 'contract_mode', reason: 'must be one of: BALANCED, safe, builder, autopilot' });
+    }
+  }
+
+  if (!isPlainObject(contract.governor)) {
+    errors.push({ field: 'governor', reason: 'must be an object' });
+  } else {
+    for (const key of Object.keys(contract.governor)) {
+      if (!KNOWN_GOVERNOR_FIELDS.has(key)) {
+        errors.push({ field: `governor.${key}`, reason: 'unknown field — check for typos (contract schema invalid)' });
+      }
+    }
+    const g = contract.governor;
+    if (g.max_steps !== undefined && g.max_steps !== null && !(Number.isInteger(g.max_steps) && g.max_steps >= 0)) {
+      errors.push({ field: 'governor.max_steps', reason: 'must be a non-negative integer' });
+    }
+    if (g.error_streak_limit !== undefined && g.error_streak_limit !== null && !(Number.isInteger(g.error_streak_limit) && g.error_streak_limit >= 0)) {
+      errors.push({ field: 'governor.error_streak_limit', reason: 'must be a non-negative integer' });
+    }
+    checkOptionalLimit(errors, 'governor.cost_ceiling_tokens', g.cost_ceiling_tokens);
+    checkOptionalLimit(errors, 'governor.max_runtime_minutes', g.max_runtime_minutes);
+    checkOptionalLimit(errors, 'governor.max_changed_files', g.max_changed_files);
+    checkOptionalLimit(errors, 'governor.max_diff_lines', g.max_diff_lines);
+  }
+
+  if (contract.allowed_files !== undefined) {
+    checkGlobArray(errors, 'allowed_files', contract.allowed_files);
+    // EC-5: allowlist vazia bloquearia tudo — warning + tratada como ausente
+    if (Array.isArray(contract.allowed_files) && contract.allowed_files.length === 0) {
+      warnings.push({
+        field: 'allowed_files',
+        reason: 'empty allowlist would block every write — treated as absent'
+      });
+    }
+  }
+
+  if (contract.forbidden_files !== undefined) {
+    checkGlobArray(errors, 'forbidden_files', contract.forbidden_files);
+  }
+
+  if (contract.human_gate !== undefined) {
+    if (!isPlainObject(contract.human_gate)) {
+      errors.push({ field: 'human_gate', reason: 'must be an object' });
+    } else {
+      for (const key of Object.keys(contract.human_gate)) {
+        if (!KNOWN_HUMAN_GATE_FIELDS.has(key)) {
+          errors.push({ field: `human_gate.${key}`, reason: 'unknown field — check for typos (contract schema invalid)' });
+        }
+      }
+      const hg = contract.human_gate;
+      if (!Array.isArray(hg.required_for)) {
+        errors.push({ field: 'human_gate.required_for', reason: 'must be an array of themes (required when human_gate is present)' });
+      } else {
+        hg.required_for.forEach((theme, i) => {
+          if (!HUMAN_GATE_THEMES.includes(theme)) {
+            errors.push({ field: `human_gate.required_for[${i}]`, reason: `unknown theme "${theme}" — valid: ${HUMAN_GATE_THEMES.join(', ')}` });
+          }
+        });
+      }
+      if (hg.themes !== undefined) {
+        if (!Array.isArray(hg.themes)) {
+          errors.push({ field: 'human_gate.themes', reason: 'must be an array' });
+        } else {
+          hg.themes.forEach((theme, i) => {
+            if (!isPlainObject(theme)) {
+              errors.push({ field: `human_gate.themes[${i}]`, reason: 'must be an object { name, paths }' });
+              return;
+            }
+            for (const key of Object.keys(theme)) {
+              if (!KNOWN_THEME_FIELDS.has(key)) {
+                errors.push({ field: `human_gate.themes[${i}].${key}`, reason: 'unknown field — check for typos (contract schema invalid)' });
+              }
+            }
+            if (!HUMAN_GATE_THEMES.includes(theme.name)) {
+              errors.push({ field: `human_gate.themes[${i}].name`, reason: `unknown theme "${theme.name}" — valid: ${HUMAN_GATE_THEMES.join(', ')}` });
+            }
+            checkGlobArray(errors, `human_gate.themes[${i}].paths`, theme.paths);
+          });
+        }
+      }
+    }
+  }
+
+  if (contract.criteria !== undefined) {
+    if (!Array.isArray(contract.criteria)) {
+      errors.push({ field: 'criteria', reason: 'must be an array' });
+    } else {
+      contract.criteria.forEach((criterion, i) => {
+        if (!isPlainObject(criterion)) {
+          errors.push({ field: `criteria[${i}]`, reason: 'must be an object' });
+          return;
+        }
+        for (const key of Object.keys(criterion)) {
+          if (!KNOWN_CRITERIA_FIELDS.has(key)) {
+            errors.push({ field: `criteria[${i}].${key}`, reason: 'unknown field — check for typos (contract schema invalid)' });
+          }
+        }
+        if (typeof criterion.id !== 'string' || !criterion.id.trim()) {
+          errors.push({ field: `criteria[${i}].id`, reason: 'must be a non-empty string' });
+        }
+        if (criterion.verification !== undefined && (typeof criterion.verification !== 'string' || !criterion.verification.trim())) {
+          errors.push({ field: `criteria[${i}].verification`, reason: 'must be a non-empty shell command string when present' });
+        }
+        if (criterion.binary !== undefined && typeof criterion.binary !== 'boolean') {
+          errors.push({ field: `criteria[${i}].binary`, reason: 'must be a boolean' });
+        }
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Resolve o contrato VALIDADO para sua forma efetiva:
+ * - preset do contract_mode preenche valores do governor não definidos (REQ-19);
+ * - `forbidden_files` mesclado com os defaults não-removíveis (REQ-4);
+ * - `allowed_files: []` tratado como ausente (EC-5);
+ * - mapa tema→paths resolvido (override substitui, não mescla).
+ *
+ * Não muta o contrato original; retorna um objeto efetivo para os guards.
+ */
+function resolveContract(contract) {
+  const mode = typeof contract.contract_mode === 'string'
+    ? contract.contract_mode.toLowerCase()
+    : 'balanced';
+  const preset = CONTRACT_PRESETS[mode] || null;
+
+  const governor = { ...(contract.governor || {}) };
+  if (preset) {
+    for (const [key, value] of Object.entries(preset)) {
+      if (governor[key] === undefined) governor[key] = value;
+    }
+  }
+
+  const forbidden = [
+    ...DEFAULT_FORBIDDEN_GLOBS,
+    ...(Array.isArray(contract.forbidden_files) ? contract.forbidden_files : [])
+  ];
+
+  const allowed = Array.isArray(contract.allowed_files) && contract.allowed_files.length > 0
+    ? contract.allowed_files.slice()
+    : null;
+
+  const themePaths = { ...DEFAULT_THEME_PATHS };
+  const requiredFor = contract.human_gate && Array.isArray(contract.human_gate.required_for)
+    ? contract.human_gate.required_for.slice()
+    : [];
+  if (contract.human_gate && Array.isArray(contract.human_gate.themes)) {
+    for (const theme of contract.human_gate.themes) {
+      if (theme && HUMAN_GATE_THEMES.includes(theme.name) && Array.isArray(theme.paths)) {
+        themePaths[theme.name] = theme.paths.slice();
+      }
+    }
+  }
+
+  return {
+    feature: contract.feature,
+    contract_mode: mode,
+    governor,
+    criteria: Array.isArray(contract.criteria) ? contract.criteria : [],
+    allowed_files: allowed,
+    forbidden_files: forbidden,
+    human_gate: {
+      required_for: requiredFor,
+      theme_paths: themePaths
+    }
+  };
+}
+
+module.exports = {
+  DEFAULT_FORBIDDEN_GLOBS,
+  HUMAN_GATE_THEMES,
+  DEFAULT_THEME_PATHS,
+  CONTRACT_PRESETS,
+  validateContract,
+  resolveContract
+};

package/src/harness/criteria-runner.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Avaliação determinística de criteria[].verification (loop-guardrails
+ * REQ-16/17 + D7).
+ *
+ * Reusa `executeInSandbox` (src/sandbox.js) — timeout, kill de process tree e
+ * redaction já resolvidos (EC-7). NÃO cria runner novo. Critério sem
+ * `verification` mantém o comportamento atual (não avaliado).
+ *
+ * Assinatura de falha (D7): sha1(criterion_id + exitCode + primeira linha
+ * não-vazia de stderr normalizada — paths absolutos, números e timestamps
+ * removidos). 2 ocorrências no RUN (não precisam ser consecutivas — EC-13,
+ * diferente do error_streak) → failure_signature_repeat + parada.
+ */
+
+const crypto = require('node:crypto');
+
+const DEFAULT_CHECK_TIMEOUT_MS = 120000;
+
+/**
+ * Normaliza uma linha de erro para assinatura estável (D7):
+ * remove paths absolutos, troca dígitos por '#' (line numbers, timestamps,
+ * durações) e colapsa espaços.
+ */
+function normalizeErrorLine(line) {
+  return String(line || '')
+    // paths absolutos (posix e windows, com ou sem drive letter)
+    .replace(/(?:[A-Za-z]:)?[\\/][^\s:'"()]+/g, '<path>')
+    // dígitos (line numbers, timestamps, ms)
+    .replace(/\d+/g, '#')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function firstNonEmptyLine(text) {
+  for (const line of String(text || '').split('\n')) {
+    if (line.trim()) return line;
+  }
+  return '';
+}
+
+/** sha1 hex da assinatura de falha (D7). */
+function failureSignature(criterionId, exitCode, stderr) {
+  const normalized = normalizeErrorLine(firstNonEmptyLine(stderr));
+  return crypto
+    .createHash('sha1')
+    .update(`${criterionId}|${exitCode === null || exitCode === undefined ? 'null' : exitCode}|${normalized}`)
+    .digest('hex');
+}
+
+/**
+ * Executa os critérios com `verification` via sandbox (REQ-16).
+ *
+ * @param {object} params
+ * @param {Array} params.criteria — criteria[] do contrato resolvido
+ * @param {string} params.cwd — raiz do projeto
+ * @param {number} [params.timeoutMs]
+ * @param {Function} [params.sandboxExec] — injeção para teste; default executeInSandbox
+ * @returns {Promise<Array<{id, command, exitCode, durationMs, stdout, stderr, timedOut, ok, signature}>>}
+ */
+async function runCriteria({ criteria = [], cwd, timeoutMs = DEFAULT_CHECK_TIMEOUT_MS, sandboxExec = null }) {
+  const exec = sandboxExec || require('../sandbox').executeInSandbox;
+  const checks = [];
+  for (const criterion of criteria) {
+    if (!criterion || typeof criterion.verification !== 'string' || !criterion.verification.trim()) {
+      continue; // sem verification = não avaliado automaticamente (REQ-16)
+    }
+    const startedAt = Date.now();
+    let result;
+    try {
+      result = await exec(criterion.verification, {
+        cwd,
+        timeout: timeoutMs,
+        intent: `criteria:${criterion.id}`
+      });
+    } catch (err) {
+      result = { ok: false, stdout: '', stderr: String(err.message || err), exitCode: null, timedOut: false };
+    }
+    const check = {
+      id: criterion.id,
+      command: criterion.verification,
+      exitCode: result.exitCode,
+      durationMs: Date.now() - startedAt,
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      timedOut: Boolean(result.timedOut),
+      ok: Boolean(result.ok)
+    };
+    // EC-7: timeout = check falho com assinatura própria (stderr do sandbox
+    // "Command timed out after Xms" normaliza estável via '#')
+    check.signature = check.ok ? null : failureSignature(check.id, check.exitCode, check.stderr);
+    checks.push(check);
+  }
+  return checks;
+}
+
+/**
+ * Registra assinaturas de falha no run (D7) e detecta repetições.
+ * Muta `progress.failure_signatures[]` (caller persiste).
+ *
+ * @returns {Array<{signature, criterion_id}>} repetições (>= 2 no run)
+ */
+function registerFailureSignatures(progress, failedChecks) {
+  if (!Array.isArray(progress.failure_signatures)) progress.failure_signatures = [];
+  const repeats = [];
+  for (const check of failedChecks) {
+    if (!check.signature) continue;
+    const priorOccurrences = progress.failure_signatures.filter((s) => s.signature === check.signature).length;
+    progress.failure_signatures.push({
+      signature: check.signature,
+      criterion_id: check.id,
+      recorded_at: new Date().toISOString()
+    });
+    if (priorOccurrences + 1 >= 2) {
+      repeats.push({ signature: check.signature, criterion_id: check.id });
+    }
+  }
+  return repeats;
+}
+
+/** Zera as assinaturas para um run novo (chamado no preflight junto do budget). */
+function startRunSignatures(progress) {
+  progress.failure_signatures = [];
+  return progress;
+}
+
+module.exports = {
+  DEFAULT_CHECK_TIMEOUT_MS,
+  normalizeErrorLine,
+  failureSignature,
+  runCriteria,
+  registerFailureSignatures,
+  startRunSignatures
+};

package/src/harness/git-baseline.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * Baseline git do self:loop (loop-guardrails REQ-2/3 + D2).
+ *
+ * Única fronteira `child_process` da Fase 1 além do sandbox — todo o I/O git
+ * dos guards vive aqui. Módulos consumidores recebem objetos puros.
+ *
+ * - `captureBaseline`: no preflight, grava HEAD + dirty_paths (porcelain) e o
+ *   `git hash-object` dos dirty paths que casam `forbidden_files` (D2 — fecha
+ *   EC-2: tentativa que re-modifica um path sujo proibido ainda viola).
+ * - `computeChangedSet`: pós-attempt, changed set = porcelain atual −
+ *   dirty_paths do baseline. NUNCA `git diff --name-only` (não vê untracked,
+ *   EC-1). Paths normalizados `/` (EC-6). Rename conta os dois paths (EC-3);
+ *   deleção conta (EC-4).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { normalizePath, matchGlob, matchAny } = require('./glob-match');
+
+/**
+ * Estado do framework: o próprio loop escreve progress.json/baseline.json/
+ * attempts/ sob `.aioson/` durante a execução — esses paths são excluídos do
+ * changed-set para não gerar falsa violação (mesmo precedente do git ingest
+ * do neural-chain, que exclui `.aioson/*`).
+ */
+const FRAMEWORK_STATE_GLOB = '.aioson/**';
+
+function git(targetDir, gitArgs) {
+  return execFileSync('git', gitArgs, {
+    cwd: targetDir,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024 * 10,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+/** Map porcelain XY → status do schema §2.3. */
+function porcelainStatus(xy) {
+  if (xy.includes('R') || xy.includes('C')) return 'renamed';
+  if (xy === '??') return 'added';
+  if (xy.includes('A')) return 'added';
+  if (xy.includes('D')) return 'deleted';
+  return 'modified';
+}
+
+/**
+ * Parseia `git status --porcelain` em entradas { path, status }.
+ * Rename (`R  old -> new`) produz DUAS entradas (EC-3).
+ * Exportada pura para teste determinístico.
+ */
+function parsePorcelain(output) {
+  const entries = [];
+  for (const rawLine of String(output || '').split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim()) continue;
+    const xy = line.slice(0, 2);
+    let rest = line.slice(3);
+    // porcelain pode citar paths com espaços/especiais entre aspas
+    const unquote = (p) => {
+      const trimmed = p.trim();
+      if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try { return JSON.parse(trimmed); } catch { return trimmed.slice(1, -1); }
+      }
+      return trimmed;
+    };
+    const status = porcelainStatus(xy);
+    if (status === 'renamed' && rest.includes(' -> ')) {
+      const [from, to] = rest.split(' -> ');
+      entries.push({ path: normalizePath(unquote(from)), status: 'renamed' });
+      entries.push({ path: normalizePath(unquote(to)), status: 'renamed' });
+      continue;
+    }
+    entries.push({ path: normalizePath(unquote(rest)), status });
+  }
+  return entries;
+}
+
+function readPorcelain(targetDir) {
+  // -uall: untracked listados arquivo a arquivo — sem ele o porcelain colapsa
+  // dirs novos (`?? secrets/`) e `secrets/**` não casaria o dir vazio de sufixo.
+  const entries = parsePorcelain(git(targetDir, ['status', '--porcelain', '-uall']));
+  return entries.filter((entry) => !matchGlob(FRAMEWORK_STATE_GLOB, entry.path));
+}
+
+function readHead(targetDir) {
+  try {
+    return git(targetDir, ['rev-parse', 'HEAD']).trim();
+  } catch {
+    return null; // repo sem commits ainda
+  }
+}
+
+/**
+ * `git hash-object` de um path do working tree; null para path
+ * inexistente/deletado (deleção posterior será detectada por hash null≠hash).
+ */
+function hashWorkingTreePath(targetDir, relPath) {
+  const abs = path.join(targetDir, relPath);
+  if (!fs.existsSync(abs) || fs.statSync(abs).isDirectory()) return null;
+  try {
+    return git(targetDir, ['hash-object', '--', relPath]).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Captura o baseline no preflight (REQ-2 + D2) e grava
+ * `.aioson/plans/{slug}/baseline.json`.
+ *
+ * @returns {{ baseline, warnings: [{path, reason}] }}
+ */
+function captureBaseline(targetDir, planDir, { forbiddenGlobs = [] } = {}) {
+  const dirtyEntries = readPorcelain(targetDir);
+  const dirtyPaths = dirtyEntries.map((e) => e.path);
+
+  // D2: hash apenas dos dirty paths que casam forbidden (conjunto bounded)
+  const forbiddenDirtyHashes = {};
+  const warnings = [];
+  for (const dirtyPath of dirtyPaths) {
+    const matched = matchAny(forbiddenGlobs, dirtyPath);
+    if (matched) {
+      forbiddenDirtyHashes[dirtyPath] = hashWorkingTreePath(targetDir, dirtyPath);
+      warnings.push({
+        path: dirtyPath,
+        reason: `dirty path matches forbidden glob "${matched}" at loop start — re-modification will be a scope violation`
+      });
+    }
+  }
+
+  const baseline = {
+    captured_at: new Date().toISOString(),
+    head: readHead(targetDir),
+    dirty_paths: dirtyPaths,
+    forbidden_dirty_hashes: forbiddenDirtyHashes
+  };
+
+  fs.mkdirSync(planDir, { recursive: true });
+  fs.writeFileSync(path.join(planDir, 'baseline.json'), JSON.stringify(baseline, null, 2), 'utf8');
+
+  return { baseline, warnings };
+}
+
+function loadBaseline(planDir) {
+  const baselinePath = path.join(planDir, 'baseline.json');
+  if (!fs.existsSync(baselinePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Changed set da tentativa (REQ-3): porcelain atual − dirty_paths do baseline,
+ * MAIS dirty paths proibidos cujo hash mudou desde o baseline (D2 / EC-2).
+ *
+ * @returns {{ files: [{path, status}], rehashViolations: [{path, reason}] }}
+ */
+function computeChangedSet(targetDir, baseline) {
+  const current = readPorcelain(targetDir);
+  const baselineDirty = new Set((baseline && baseline.dirty_paths) || []);
+
+  const files = current.filter((entry) => !baselineDirty.has(entry.path));
+
+  const rehashViolations = [];
+  const hashes = (baseline && baseline.forbidden_dirty_hashes) || {};
+  for (const [dirtyPath, baselineHash] of Object.entries(hashes)) {
+    const currentHash = hashWorkingTreePath(targetDir, dirtyPath);
+    if (currentHash !== baselineHash) {
+      rehashViolations.push({
+        path: dirtyPath,
+        reason: 'forbidden dirty path was re-modified after baseline (content hash changed)'
+      });
+    }
+  }
+
+  return { files, rehashViolations };
+}
+
+/** `git diff` da tentativa para attempts/{n}/diff.patch (should-have REQ-9). */
+function captureDiffPatch(targetDir) {
+  try {
+    return git(targetDir, ['diff', 'HEAD']);
+  } catch {
+    try {
+      return git(targetDir, ['diff']);
+    } catch {
+      return '';
+    }
+  }
+}
+
+module.exports = {
+  parsePorcelain,
+  captureBaseline,
+  loadBaseline,
+  computeChangedSet,
+  captureDiffPatch
+};