@jaimevalasek/aioson 1.21.7 → 1.22.0

package/src/constants.js

@@ -35,7 +35,8 @@ const MANAGED_FILES = [
   '.aioson/agents/committer.md',
   '.aioson/agents/copywriter.md',
   '.aioson/agents/briefing.md',
-  '.aioson/docs/squad/package-contract.md',
+  '.aioson/agents/briefing-refiner.md',
+  '.aioson/docs/squad/package-contract.md',
   '.aioson/docs/squad/creation-flow.md',
   '.aioson/docs/squad/research-loop.md',
   '.aioson/docs/squad/quality-lens.md',
@@ -438,17 +439,26 @@ const AGENT_DEFINITIONS = [
     dependsOn: [],
     output: 'marketing copy + content assets'
   },
-  {
-    id: 'briefing',
-    displayName: 'Briefing',
-    description: 'Pre-production briefings and planning',
-    command: '@briefing',
+  {
+    id: 'briefing',
+    displayName: 'Briefing',
+    description: 'Pre-production briefings and planning',
+    command: '@briefing',
     path: '.aioson/agents/briefing.md',
-    dependsOn: ['.aioson/context/project.context.md'],
-    output: '.aioson/briefings/{slug}/'
-  },
-  {
-    id: 'profiler-researcher',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: '.aioson/briefings/{slug}/'
+  },
+  {
+    id: 'briefing-refiner',
+    displayName: 'Briefing Refiner',
+    description: 'Interactive refinement of briefing artifacts before Product PRD generation',
+    command: '@briefing-refiner',
+    path: '.aioson/agents/briefing-refiner.md',
+    dependsOn: ['.aioson/context/project.context.md', '.aioson/briefings/config.md'],
+    output: '.aioson/briefings/{slug}/review.html + refinement-feedback.json + refinement-report.md'
+  },
+  {
+    id: 'profiler-researcher',
     displayName: 'Profiler Researcher',
     description: 'Clone profiler: research phase',
     command: '@profiler-researcher',

package/src/context-search.js

@@ -18,6 +18,9 @@ function openDb(dbPath) {
   const db = new Database(dbPath);
   db.pragma('journal_mode = WAL');
   db.pragma('synchronous = NORMAL');
+  // Wait up to 5s for a transient lock (e.g. WAL checkpoint, AV file-lock on
+  // Windows) instead of throwing SQLITE_BUSY immediately.
+  db.pragma('busy_timeout = 5000');
   db.exec(`
     CREATE TABLE IF NOT EXISTS schema_version (
       version INTEGER NOT NULL

package/src/doctor.js

@@ -106,7 +106,7 @@ async function fileContainsAll(filePath, patterns) {
   }
 }
 
-const DESIGN_GOVERNANCE_FILES = [
+const DESIGN_GOVERNANCE_FILES = [
   '.aioson/design-docs/code-reuse.md',
   '.aioson/design-docs/componentization.md',
   '.aioson/design-docs/file-size.md',
@@ -114,11 +114,11 @@ const DESIGN_GOVERNANCE_FILES = [
   '.aioson/design-docs/naming.md'
 ];
 
-const GATEWAY_FILE_BY_CHECK_ID = {
-  'gateway:claude:contract': 'CLAUDE.md',
-  'gateway:codex:contract': 'AGENTS.md',
-  'gateway:opencode:contract': 'OPENCODE.md'
-};
+const GATEWAY_FILE_BY_CHECK_ID = {
+  'gateway:claude:contract': 'CLAUDE.md',
+  'gateway:codex:contract': 'AGENTS.md',
+  'gateway:opencode:contract': 'OPENCODE.md'
+};
 
 async function restoreTemplateFiles(targetDir, relPaths, options = {}) {
   const dryRun = Boolean(options.dryRun);
@@ -175,7 +175,7 @@ async function runDoctor(targetDir) {
       hintKey: 'doctor.gateway_codex_pointer_hint',
       patterns: ['.aioson/config.md', '.aioson/agents/']
     },
-    {
+    {
       id: 'gateway:opencode:contract',
       rel: 'OPENCODE.md',
       key: 'doctor.gateway_opencode_pointer',
@@ -196,7 +196,7 @@ async function runDoctor(targetDir) {
     });
   }
 
-  const contextPath = path.join(targetDir, '.aioson/context/project.context.md');
+  const contextPath = path.join(targetDir, '.aioson/context/project.context.md');
   checks.push({
     id: 'context:project',
     key: 'doctor.context_generated',
@@ -227,6 +227,22 @@ async function runDoctor(targetDir) {
     }
   }
 
+  // Autopilot handoff: protocol doc installed but flag never declared in the
+  // context frontmatter — autopilot stays silently inactive (absent = manual
+  // handoffs). An explicit true/false is a deliberate choice and passes.
+  const autopilotDocExists = await exists(path.join(targetDir, '.aioson/docs/autopilot-handoff.md'));
+  if (autopilotDocExists && contextValidation.exists && contextValidation.data) {
+    const autoHandoffDeclared = Object.prototype.hasOwnProperty.call(contextValidation.data, 'auto_handoff');
+    checks.push({
+      id: 'context:auto_handoff_declared',
+      severity: 'warning',
+      key: 'doctor.auto_handoff_declared',
+      params: {},
+      ok: autoHandoffDeclared,
+      hintKey: autoHandoffDeclared ? undefined : 'doctor.auto_handoff_declared_hint'
+    });
+  }
+
   const major = parseMajor(process.version);
   checks.push({
     id: 'node:version',

package/src/dossier/schema.js

@@ -5,9 +5,10 @@ const SUPPORTED_SCHEMA_VERSIONS = Object.freeze(new Set(['1.0', '1.1', '1.2']));
 
 const CANONICAL_AGENT_IDS = Object.freeze(new Set([
   'analyst',
-  'architect',
-  'briefing',
-  'committer',
+  'architect',
+  'briefing',
+  'briefing-refiner',
+  'committer',
   'copywriter',
   'cypher',
   'design-hybrid-forge',

package/src/harness/active-contract.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * Descoberta do contrato de harness ATIVO (loop-guardrails C-01 / REQ-20).
+ *
+ * Heurística única, compartilhada entre `git:guard` (camada 2 do scope guard)
+ * e `self:loop` (auto-descoberta quando nem --contract nem --spec são
+ * passados): varre `.aioson/plans/{slug}/progress.json`, considera candidato quem
+ * está `in_progress` ou `human_gate` e tem `harness-contract.json` ao lado,
+ * e desempata pelo `last_updated` mais recente.
+ *
+ * Best-effort por contrato (progress ilegível não é candidato), mas a função
+ * em si lança apenas em falha de I/O inesperada — chamadores que precisam de
+ * "nunca quebrar" devem envolver em try/catch.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+function findActiveContract(targetDir) {
+  const plansDir = path.join(targetDir, '.aioson', 'plans');
+  if (!fs.existsSync(plansDir)) return null;
+  const candidates = [];
+  for (const slug of fs.readdirSync(plansDir)) {
+    const planDir = path.join(plansDir, slug);
+    try {
+      const progress = JSON.parse(fs.readFileSync(path.join(planDir, 'progress.json'), 'utf8'));
+      if (progress.status === 'in_progress' || progress.status === 'human_gate') {
+        const contractPath = path.join(planDir, 'harness-contract.json');
+        if (fs.existsSync(contractPath)) {
+          candidates.push({ slug, contractPath, lastUpdated: progress.last_updated || '' });
+        }
+      }
+    } catch { /* sem progress legível — não é candidato */ }
+  }
+  if (!candidates.length) return null;
+  candidates.sort((a, b) => String(b.lastUpdated).localeCompare(String(a.lastUpdated)));
+  return candidates[0];
+}
+
+module.exports = { findActiveContract };

package/src/harness/attempt-artifacts.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Writer único de `.aioson/plans/{slug}/attempts/{n}/` (loop-guardrails REQ-9).
+ *
+ * Scope guard e criteria-runner ENTREGAM dados a este módulo — nunca escrevem
+ * direto. Registrar primeiro, julgar depois (D5: artifacts é o passo 1 do hook,
+ * sempre executado mesmo em falha).
+ *
+ * Estrutura:
+ *   attempts/{n}/changed-files.json   — { attempt, detected_at, files[] }
+ *   attempts/{n}/checks/{id}.log      — stdout+stderr + exit code + duração
+ *   attempts/{n}/diff.patch           — git diff da tentativa (should-have)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function attemptDir(planDir, attempt) {
+  return path.join(planDir, 'attempts', String(attempt));
+}
+
+/**
+ * Grava os artefatos da tentativa. Cada seção é opcional e best-effort
+ * independente — falha em uma não impede as outras.
+ *
+ * @param {string} planDir — .aioson/plans/{slug}
+ * @param {number} attempt — número da tentativa (1-based)
+ * @param {object} data
+ * @param {Array<{path, status}>} [data.changedFiles]
+ * @param {Array<{id, command, exitCode, durationMs, stdout, stderr, timedOut}>} [data.checks]
+ * @param {string} [data.diffPatch]
+ * @returns {{ ok: boolean, dir: string, written: string[] }}
+ */
+function writeAttemptArtifacts(planDir, attempt, { changedFiles, checks, diffPatch } = {}) {
+  const dir = attemptDir(planDir, attempt);
+  const written = [];
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    return { ok: false, dir, written };
+  }
+
+  if (Array.isArray(changedFiles)) {
+    try {
+      const payload = {
+        attempt,
+        detected_at: new Date().toISOString(),
+        files: changedFiles.map((f) => ({ path: f.path, status: f.status }))
+      };
+      fs.writeFileSync(path.join(dir, 'changed-files.json'), JSON.stringify(payload, null, 2), 'utf8');
+      written.push('changed-files.json');
+    } catch { /* best-effort */ }
+  }
+
+  if (Array.isArray(checks) && checks.length > 0) {
+    try {
+      const checksDir = path.join(dir, 'checks');
+      fs.mkdirSync(checksDir, { recursive: true });
+      for (const check of checks) {
+        const safeId = String(check.id || 'check').replace(/[^A-Za-z0-9._-]/g, '_');
+        const body = [
+          `# criterion: ${check.id}`,
+          `# command: ${check.command || ''}`,
+          `# exit_code: ${check.exitCode === null || check.exitCode === undefined ? 'null' : check.exitCode}`,
+          `# duration_ms: ${check.durationMs ?? 0}`,
+          `# timed_out: ${Boolean(check.timedOut)}`,
+          '',
+          '## stdout',
+          check.stdout || '',
+          '',
+          '## stderr',
+          check.stderr || ''
+        ].join('\n');
+        fs.writeFileSync(path.join(checksDir, `${safeId}.log`), body, 'utf8');
+        written.push(`checks/${safeId}.log`);
+      }
+    } catch { /* best-effort */ }
+  }
+
+  if (typeof diffPatch === 'string' && diffPatch.length > 0) {
+    try {
+      fs.writeFileSync(path.join(dir, 'diff.patch'), diffPatch, 'utf8');
+      written.push('diff.patch');
+    } catch { /* best-effort */ }
+  }
+
+  return { ok: true, dir, written };
+}
+
+module.exports = {
+  writeAttemptArtifacts,
+  attemptDir
+};

package/src/harness/budget-guard.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * Orçamento do self:loop (loop-guardrails REQ-7/8 + D3).
+ *
+ * Módulo puro: opera sobre o objeto `progress` (de progress.json) e devolve
+ * eventos a emitir + decisão de pausa. O wiring persiste e emite.
+ *
+ * Fonte de enforcement é o acumulador `progress.budget` — nunca SQLite no hot
+ * path (D3). `execution_events.token_count` é só telemetria. "Run atual" =
+ * acumulador zerado a cada run novo (EC-10: legados null irrelevantes).
+ *
+ * Estimativa: chars/4 sobre o output do agente (erro 5-15% aceito pelo PRD;
+ * `tokenx` é upgrade path documentado).
+ */
+
+/** Estimativa heurística chars/4 (REQ-7). */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(String(text).length / 4);
+}
+
+/**
+ * Inicializa o acumulador de budget para um run NOVO (preflight, passo 4).
+ * Zera tokens e flags; muta `progress` (caller persiste).
+ */
+function startRunBudget(progress, runId) {
+  progress.budget = {
+    tokens_estimated: 0,
+    warned_80: false,
+    run_started_at: new Date().toISOString(),
+    run_id: runId
+  };
+  return progress.budget;
+}
+
+/** Garante que progress.budget existe (retomada de run antigo sem o campo). */
+function ensureBudget(progress, runId) {
+  if (!progress.budget || typeof progress.budget !== 'object') {
+    startRunBudget(progress, runId);
+  }
+  return progress.budget;
+}
+
+/** Acumula a estimativa da tentativa; muta `progress` (caller persiste). */
+function recordAttemptTokens(progress, tokens) {
+  ensureBudget(progress, null);
+  progress.budget.tokens_estimated += Math.max(0, Math.round(tokens) || 0);
+  return progress.budget.tokens_estimated;
+}
+
+/**
+ * Política 80/100% (REQ-7) + max_runtime_minutes na fronteira (REQ-8).
+ *
+ * EC-11: 80% e 100% cruzados na mesma tentativa → AMBOS os eventos em ordem,
+ * pausa uma vez. `warned_80` garante o warning 1x por run; muta `progress`.
+ *
+ * @returns {{ ok, pause, events: [{type, message, payload}] }}
+ */
+function checkBudget(progress, { costCeilingTokens = null, maxRuntimeMinutes = null, now = null } = {}) {
+  const events = [];
+  let pause = false;
+  const budget = ensureBudget(progress, null);
+
+  if (Number.isInteger(costCeilingTokens) && costCeilingTokens > 0) {
+    const spent = budget.tokens_estimated;
+    const pct = spent / costCeilingTokens;
+
+    if (pct >= 0.8 && !budget.warned_80) {
+      budget.warned_80 = true;
+      events.push({
+        type: 'budget_warning',
+        message: `token budget at ${Math.round(pct * 100)}% (${spent}/${costCeilingTokens} estimated)`,
+        payload: { tokens_estimated: spent, cost_ceiling_tokens: costCeilingTokens, pct: Math.round(pct * 100) }
+      });
+    }
+
+    if (pct >= 1) {
+      events.push({
+        type: 'budget_exceeded',
+        message: `token budget exceeded (${spent}/${costCeilingTokens} estimated) — pausing loop`,
+        payload: { tokens_estimated: spent, cost_ceiling_tokens: costCeilingTokens }
+      });
+      pause = true;
+    }
+  }
+
+  if (Number.isInteger(maxRuntimeMinutes) && maxRuntimeMinutes > 0 && budget.run_started_at) {
+    const startedAt = Date.parse(budget.run_started_at);
+    const current = now ? Date.parse(now) : Date.now();
+    if (Number.isFinite(startedAt) && current - startedAt > maxRuntimeMinutes * 60000) {
+      const elapsedMin = Math.round((current - startedAt) / 60000);
+      events.push({
+        type: 'runtime_exceeded',
+        message: `max_runtime_minutes exceeded (${elapsedMin}min > ${maxRuntimeMinutes}min) — pausing loop`,
+        payload: { elapsed_minutes: elapsedMin, max_runtime_minutes: maxRuntimeMinutes }
+      });
+      pause = true;
+    }
+  }
+
+  return { ok: !pause, pause, events };
+}
+
+/**
+ * Resumo feito/faltante para a pausa de 100% (REQ-7).
+ */
+function buildBudgetSummary(progress, { maxIterations = null } = {}) {
+  const budget = progress.budget || {};
+  const iterations = progress.iterations || 0;
+  return [
+    `Budget pause summary:`,
+    `  iterations completed: ${iterations}${maxIterations ? `/${maxIterations}` : ''}`,
+    `  tokens estimated (chars/4): ${budget.tokens_estimated || 0}`,
+    `  run started at: ${budget.run_started_at || 'unknown'}`,
+    `  resume: review scope/budget in harness-contract.json, then re-run self:loop`
+  ].join('\n');
+}
+
+module.exports = {
+  estimateTokens,
+  startRunBudget,
+  ensureBudget,
+  recordAttemptTokens,
+  checkBudget,
+  buildBudgetSummary
+};

package/src/harness/circuit-breaker.js

@@ -47,6 +47,13 @@ class CircuitBreaker {
     const { circuit_state, iterations, consecutive_errors } = this.progress;
     const { max_steps, error_streak_limit } = this.contract.governor;
 
+    // HUMAN_GATE (loop-guardrails D4): gate humano pendente nega execução até
+    // decisão via harness:approve / harness:reject (REQ-12/15).
+    const pendingGates = Array.isArray(this.progress.pending_gates) ? this.progress.pending_gates : [];
+    if (this.progress.status === 'human_gate' || pendingGates.length > 0) {
+      return { allowed: false, reason: 'human_gate_pending' };
+    }
+
     if (circuit_state === 'OPEN') {
       return { allowed: false, reason: 'circuit_open' };
     }