@jaimevalasek/aioson 1.21.8 → 1.22.0

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
+};

package/src/harness/glob-match.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * Glob matcher mínimo e determinístico para o scope guard (loop-guardrails D1).
+ *
+ * Subset estrito suportado: `**`, `*`, `?` (incluindo `**` + `/` nas bordas).
+ * Qualquer sintaxe fora do subset (extglob `{}[]!()`, classes, negação) é
+ * REJEITADA pelo validador — nunca mismatch silencioso em fronteira de
+ * segurança. `picomatch` é o upgrade path documentado se o subset apertar.
+ *
+ * Semântica de caminho (decisão registrada em spec-loop-guardrails.md):
+ * - paths e patterns são normalizados para `/` antes do match (EC-6);
+ * - pattern SEM `/` casa contra o basename de qualquer profundidade
+ *   (estilo gitignore: `*.pem` casa `certs/server.pem`);
+ * - pattern COM `/` casa contra o caminho relativo completo.
+ */
+
+const INVALID_GLOB_CHARS = /[{}[\]()!]/;
+
+/** Normaliza separadores para `/` e remove `./` inicial. */
+function normalizePath(p) {
+  let out = String(p == null ? '' : p).replace(/\\/g, '/');
+  while (out.startsWith('./')) out = out.slice(2);
+  return out;
+}
+
+/**
+ * Valida um pattern contra o subset estrito.
+ * Retorna { ok: true } ou { ok: false, reason }.
+ */
+function validateGlobPattern(pattern) {
+  if (typeof pattern !== 'string' || pattern.trim() === '') {
+    return { ok: false, reason: 'pattern must be a non-empty string' };
+  }
+  const normalized = normalizePath(pattern);
+  const invalid = normalized.match(INVALID_GLOB_CHARS);
+  if (invalid) {
+    return {
+      ok: false,
+      reason: `unsupported glob syntax "${invalid[0]}" — only **, * and ? are allowed (strict subset)`
+    };
+  }
+  return { ok: true };
+}
+
+const REGEX_SPECIALS = /[.+^$|]/g;
+
+/** Compila um pattern (já validado) para RegExp anchored. */
+function globToRegExp(pattern) {
+  const normalized = normalizePath(pattern);
+  let regex = '';
+  let i = 0;
+  while (i < normalized.length) {
+    const ch = normalized[i];
+    if (ch === '*') {
+      if (normalized[i + 1] === '*') {
+        // `**` — atravessa separadores
+        const prev = normalized[i - 1];
+        const next = normalized[i + 2];
+        if ((prev === undefined || prev === '/') && next === '/') {
+          // `**/` no início ou após `/` — zero ou mais segmentos completos
+          regex += '(?:[^/]+/)*';
+          i += 3;
+          continue;
+        }
+        if (next === undefined && (prev === undefined || prev === '/')) {
+          // `/**` no fim ou pattern `**` puro — qualquer resto (inclusive vazio? não:
+          // `secrets/**` exige algo dentro de secrets/; `**` puro casa tudo)
+          regex += prev === '/' ? '.+' : '.*';
+          i += 2;
+          continue;
+        }
+        // `**` colado em texto (ex.: `a**b`) — trata como `.*`
+        regex += '.*';
+        i += 2;
+        continue;
+      }
+      regex += '[^/]*';
+      i += 1;
+      continue;
+    }
+    if (ch === '?') {
+      regex += '[^/]';
+      i += 1;
+      continue;
+    }
+    regex += ch.replace(REGEX_SPECIALS, '\\$&');
+    i += 1;
+  }
+  return new RegExp(`^${regex}$`);
+}
+
+/**
+ * Casa um path contra um pattern do subset.
+ * Pattern sem `/` casa contra o basename (estilo gitignore).
+ */
+function matchGlob(pattern, filePath) {
+  const normalizedPattern = normalizePath(pattern);
+  const normalizedPath = normalizePath(filePath);
+  if (!normalizedPattern || !normalizedPath) return false;
+
+  if (!normalizedPattern.includes('/')) {
+    const basename = normalizedPath.split('/').pop();
+    return globToRegExp(normalizedPattern).test(basename);
+  }
+  return globToRegExp(normalizedPattern).test(normalizedPath);
+}
+
+/**
+ * Retorna o primeiro pattern da lista que casa o path, ou null.
+ */
+function matchAny(patterns, filePath) {
+  if (!Array.isArray(patterns)) return null;
+  for (const pattern of patterns) {
+    if (matchGlob(pattern, filePath)) return pattern;
+  }
+  return null;
+}
+
+module.exports = {
+  normalizePath,
+  validateGlobPattern,
+  globToRegExp,
+  matchGlob,
+  matchAny
+};

package/src/harness/guard-events.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Telemetria dos guards do self:loop (loop-guardrails D6).
+ *
+ * Helper único de emissão para os tipos de evento novos (requirements §2.5):
+ * scope_violation, budget_warning, budget_exceeded, runtime_exceeded,
+ * human_gate_requested, human_gate_decision, criteria_check_failed,
+ * failure_signature_repeat, contract_invalid, diff_limit_exceeded.
+ *
+ * Sempre best-effort (espelha BR-NC-11 / neural-chain-telemetry): telemetria
+ * NUNCA quebra o loop. `token_count` carrega a estimativa chars/4 quando o
+ * evento é de tentativa (REQ-7) — telemetria apenas; enforcement lê o
+ * acumulador em progress.json (D3).
+ */
+
+const GUARD_EVENT_TYPES = Object.freeze([
+  'scope_violation',
+  'budget_warning',
+  'budget_exceeded',
+  'runtime_exceeded',
+  'human_gate_requested',
+  'human_gate_decision',
+  'criteria_check_failed',
+  'failure_signature_repeat',
+  'contract_invalid',
+  'diff_limit_exceeded'
+]);
+
+/**
+ * Emite um evento de guard no runtime store. Nunca lança.
+ *
+ * @param {string} targetDir — raiz do projeto
+ * @param {object} event
+ * @param {string} event.eventType — um de GUARD_EVENT_TYPES
+ * @param {string} [event.agent] — default 'self-loop'
+ * @param {string} [event.message]
+ * @param {object} [event.payload] — vai para payload_json (slug, attempt, etc.)
+ * @param {number|null} [event.tokenCount] — estimativa chars/4 da tentativa
+ * @returns {boolean} true se gravou
+ */
+async function emitGuardEvent(targetDir, { eventType, agent = 'self-loop', message = '', payload = null, tokenCount = null } = {}) {
+  if (!GUARD_EVENT_TYPES.includes(eventType)) return false;
+  let db = null;
+  try {
+    const { openRuntimeDb } = require('../runtime-store');
+    const opened = await openRuntimeDb(targetDir);
+    db = opened.db;
+    db.prepare(`
+      INSERT INTO execution_events (event_type, agent_name, message, payload_json, token_count, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(
+      eventType,
+      agent,
+      message || eventType,
+      payload ? JSON.stringify(payload) : null,
+      tokenCount === null || tokenCount === undefined ? null : Math.round(tokenCount),
+      new Date().toISOString()
+    );
+    return true;
+  } catch {
+    return false; // D6: telemetria nunca quebra o loop
+  } finally {
+    try { if (db) db.close(); } catch { /* ignore */ }
+  }
+}
+
+module.exports = {
+  GUARD_EVENT_TYPES,
+  emitGuardEvent
+};

package/src/harness/human-gate.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * Human gates temáticos do self:loop (loop-guardrails REQ-12/13/14/15 + D4).
+ *
+ * Estado em disco:
+ * - `.aioson/plans/{slug}/gates/{id}.json` — decisão humana persistida
+ *   (schema requirements §2.4 + campo aditivo `run_id` para suprimir
+ *   re-detecção do mesmo tema dentro do run)
+ * - `progress.json` — `status='human_gate'` + `pending_gates[]` (D4)
+ *
+ * O tema `publish` é gate de COMANDO (intercepta feature:close, REQ-13) —
+ * nunca entra na detecção por diff.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { matchAny } = require('./glob-match');
+
+const GATE_STATUSES = Object.freeze(['pending', 'approved', 'rejected']);
+
+function gatesDir(planDir) {
+  return path.join(planDir, 'gates');
+}
+
+function gatePath(planDir, gateId) {
+  const safeId = String(gateId).replace(/[^A-Za-z0-9._-]/g, '_');
+  return path.join(gatesDir(planDir), `${safeId}.json`);
+}
+
+/** Carrega todos os gates do slug (array vazio se nenhum). */
+function loadGates(planDir) {
+  const dir = gatesDir(planDir);
+  if (!fs.existsSync(dir)) return [];
+  const gates = [];
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      gates.push(JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8')));
+    } catch { /* gate corrompido — ignorado na leitura, decisão manual via fs */ }
+  }
+  return gates;
+}
+
+function pendingGates(planDir) {
+  return loadGates(planDir).filter((g) => g.status === 'pending');
+}
+
+/**
+ * Detecção por tema (REQ-12): diff da tentativa casando os globs do tema E
+ * tema listado em required_for. `publish` nunca é detectado por diff (REQ-13).
+ * Temas já cobertos por gate `approved` do MESMO run não re-disparam.
+ *
+ * @returns {Array<{theme, triggeredBy: string[]}>}
+ */
+function detectGates({ changedFiles = [], requiredFor = [], themePaths = {}, existingGates = [], runId = null }) {
+  const detections = [];
+  for (const theme of requiredFor) {
+    if (theme === 'publish') continue; // gate de comando, nunca diff
+    const globs = themePaths[theme] || [];
+    if (!globs.length) continue;
+    const alreadyHandled = existingGates.some(
+      (g) => g.theme === theme && g.run_id === runId && (g.status === 'approved' || g.status === 'pending')
+    );
+    if (alreadyHandled) continue;
+    const triggeredBy = changedFiles
+      .filter((f) => matchAny(globs, f.path))
+      .map((f) => f.path);
+    if (triggeredBy.length > 0) {
+      detections.push({ theme, triggeredBy });
+    }
+  }
+  return detections;
+}
+
+/**
+ * Cria e persiste um gate `pending` (schema §2.4). `id` único por slug:
+ * `{theme}-{n}` com n incremental sobre os gates existentes do tema.
+ */
+function createGate(planDir, { theme, attempt, triggeredBy = [], diffSummary = '', runId = null }) {
+  const existing = loadGates(planDir).filter((g) => g.theme === theme);
+  const id = `${theme}-${existing.length + 1}`;
+  const gate = {
+    id,
+    theme,
+    status: 'pending',
+    attempt,
+    triggered_by: triggeredBy,
+    diff_summary: diffSummary,
+    requested_at: new Date().toISOString(),
+    decided_at: null,
+    decided_by: null,
+    reason: null,
+    run_id: runId
+  };
+  fs.mkdirSync(gatesDir(planDir), { recursive: true });
+  fs.writeFileSync(gatePath(planDir, id), JSON.stringify(gate, null, 2), 'utf8');
+  return gate;
+}
+
+/**
+ * Entra no estado HUMAN_GATE (D4): muta `progress` (caller persiste via cb).
+ */
+function enterHumanGate(progress, gateIds) {
+  progress.status = 'human_gate';
+  const pending = new Set(Array.isArray(progress.pending_gates) ? progress.pending_gates : []);
+  for (const id of gateIds) pending.add(id);
+  progress.pending_gates = [...pending];
+  progress.last_updated = new Date().toISOString();
+  return progress;
+}
+
+/**
+ * Decide um gate (REQ-14). Idempotente: gate já decidido → no-op com aviso.
+ * EC-8: gate inexistente → erro explícito sem efeito colateral.
+ *
+ * @returns {{ ok, error?, idempotent?, gate? }}
+ */
+function decideGate(planDir, gateId, { decision, by = null, reason = null }) {
+  if (!GATE_STATUSES.includes(decision) || decision === 'pending') {
+    return { ok: false, error: 'invalid_decision' };
+  }
+  const file = gatePath(planDir, gateId);
+  if (!fs.existsSync(file)) {
+    return { ok: false, error: 'gate_not_found', gateId };
+  }
+  let gate;
+  try {
+    gate = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { ok: false, error: 'gate_corrupted', gateId };
+  }
+  if (gate.status !== 'pending') {
+    return { ok: true, idempotent: true, gate };
+  }
+  if (decision === 'rejected' && !(reason && String(reason).trim())) {
+    return { ok: false, error: 'reason_required_on_reject', gateId };
+  }
+  gate.status = decision;
+  gate.decided_at = new Date().toISOString();
+  gate.decided_by = by || null;
+  gate.reason = reason || null;
+  fs.writeFileSync(file, JSON.stringify(gate, null, 2), 'utf8');
+  return { ok: true, idempotent: false, gate };
+}
+
+/**
+ * Reconcilia `progress` após decisões (REQ-15): remove o gate decidido de
+ * `pending_gates`; sem pendências → `status='in_progress'` (retomada
+ * idempotente; gate rejeitado fica como auditoria e não bloqueia runs novos).
+ * Muta `progress` (caller persiste).
+ */
+function resolveGateState(progress, planDir) {
+  const stillPending = new Set(pendingGates(planDir).map((g) => g.id));
+  const current = Array.isArray(progress.pending_gates) ? progress.pending_gates : [];
+  progress.pending_gates = current.filter((id) => stillPending.has(id));
+  if (progress.pending_gates.length === 0 && progress.status === 'human_gate') {
+    progress.status = 'in_progress';
+  }
+  progress.last_updated = new Date().toISOString();
+  return progress;
+}
+
+/**
+ * Gate de comando `publish` (REQ-13): existe gate publish aprovado?
+ */
+function hasApprovedPublishGate(planDir) {
+  return loadGates(planDir).some((g) => g.theme === 'publish' && g.status === 'approved');
+}
+
+module.exports = {
+  loadGates,
+  pendingGates,
+  detectGates,
+  createGate,
+  enterHumanGate,
+  decideGate,
+  resolveGateState,
+  hasApprovedPublishGate,
+  gatePath
+};

package/src/harness/scope-guard.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Scope guard do self:loop (loop-guardrails REQ-4/5/6 + REQ-10).
+ *
+ * Módulo puro: recebe o changed set (já calculado por git-baseline) e o
+ * contrato RESOLVIDO (contract-schema.resolveContract — defaults proibidos já
+ * mesclados). Não faz I/O.
+ *
+ * Precedência (REQ-5): deny vence allow — path que casa `forbidden_files` é
+ * violação mesmo casando `allowed_files`. Defaults proibidos são sempre
+ * aplicados (REQ-4) porque vêm mesclados do resolveContract.
+ */
+
+const { matchAny } = require('./glob-match');
+
+/**
+ * @param {object} params
+ * @param {Array<{path, status}>} params.changedFiles — changed set da tentativa
+ * @param {Array<{path, reason}>} [params.rehashViolations] — D2 (git-baseline)
+ * @param {string[]|null} params.allowedGlobs — null = sem allowlist
+ * @param {string[]} params.forbiddenGlobs — já mesclados com defaults
+ * @returns {{ ok: boolean, violations: Array<{path, status, glob, reason}> }}
+ */
+function checkScope({ changedFiles = [], rehashViolations = [], allowedGlobs = null, forbiddenGlobs = [] }) {
+  const violations = [];
+
+  for (const file of changedFiles) {
+    const forbiddenMatch = matchAny(forbiddenGlobs, file.path);
+    if (forbiddenMatch) {
+      violations.push({
+        path: file.path,
+        status: file.status,
+        glob: forbiddenMatch,
+        reason: `matches forbidden glob "${forbiddenMatch}"${file.status === 'deleted' ? ' (deletion counts — EC-4)' : ''}`
+      });
+      continue; // deny vence allow (REQ-5)
+    }
+    if (allowedGlobs && !matchAny(allowedGlobs, file.path)) {
+      violations.push({
+        path: file.path,
+        status: file.status,
+        glob: null,
+        reason: 'outside allowed_files allowlist'
+      });
+    }
+  }
+
+  for (const rehash of rehashViolations) {
+    violations.push({
+      path: rehash.path,
+      status: 'modified',
+      glob: null,
+      reason: rehash.reason
+    });
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/** Conta linhas efetivas de diff (+/− excluindo headers +++/---). */
+function countDiffLines(diffPatch) {
+  if (!diffPatch) return 0;
+  let count = 0;
+  for (const line of String(diffPatch).split('\n')) {
+    if ((line.startsWith('+') && !line.startsWith('+++')) ||
+        (line.startsWith('-') && !line.startsWith('---'))) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Limites de diff (REQ-10, should-have). Avaliados sobre o MESMO conjunto do
+ * scope guard. `null`/`undefined` = sem limite.
+ *
+ * @returns {{ ok: boolean, exceeded: Array<{limit, actual, max}> }}
+ */
+function checkDiffLimits({ changedFiles = [], diffPatch = '', maxChangedFiles = null, maxDiffLines = null }) {
+  const exceeded = [];
+
+  if (Number.isInteger(maxChangedFiles) && maxChangedFiles > 0 && changedFiles.length > maxChangedFiles) {
+    exceeded.push({ limit: 'max_changed_files', actual: changedFiles.length, max: maxChangedFiles });
+  }
+
+  if (Number.isInteger(maxDiffLines) && maxDiffLines > 0) {
+    const actual = countDiffLines(diffPatch);
+    if (actual > maxDiffLines) {
+      exceeded.push({ limit: 'max_diff_lines', actual, max: maxDiffLines });
+    }
+  }
+
+  return { ok: exceeded.length === 0, exceeded };
+}
+
+/**
+ * Feedback de reparo/rollback injetado na próxima iteração após violação
+ * (REQ-6). Texto direto para o agente: reverter os paths e permanecer no escopo.
+ */
+function buildRollbackFeedback(violations) {
+  const lines = violations.slice(0, 10).map((v) => `  - ${v.path} (${v.reason})`);
+  return [
+    'SCOPE VIOLATION — files were changed outside the contract scope:',
+    ...lines,
+    'Revert these changes (git checkout -- <path> / delete untracked files) and redo the task touching ONLY files inside the allowed scope.'
+  ].join('\n');
+}
+
+module.exports = {
+  checkScope,
+  checkDiffLimits,
+  countDiffLines,
+  buildRollbackFeedback
+};