@jaimevalasek/aioson 1.21.8 → 1.23.0

package/src/commands/self-implement-loop.js

@@ -26,6 +26,16 @@ const fsp = require('node:fs/promises');
 const bus = require('../squad/intra-bus');
 const stateManager = require('../squad/state-manager');
 const { createCircuitBreaker } = require('../harness/circuit-breaker');
+const { validateContract, resolveContract } = require('../harness/contract-schema');
+const { captureBaseline, computeChangedSet, captureDiffPatch } = require('../harness/git-baseline');
+const { checkScope, checkDiffLimits, buildRollbackFeedback } = require('../harness/scope-guard');
+const { estimateTokens, startRunBudget, recordAttemptTokens, checkBudget, buildBudgetSummary } = require('../harness/budget-guard');
+const { writeAttemptArtifacts } = require('../harness/attempt-artifacts');
+const { previewArtifact } = require('../harness/preview-artifact');
+const { emitGuardEvent } = require('../harness/guard-events');
+const { detectGates, createGate, enterHumanGate, resolveGateState, pendingGates, loadGates } = require('../harness/human-gate');
+const { runCriteria, registerFailureSignatures, startRunSignatures } = require('../harness/criteria-runner');
+const { findActiveContract } = require('../harness/active-contract');
 
 // ─── Agent execution ─────────────────────────────────────────────────────────
 
@@ -127,6 +137,204 @@ async function criteriaOnlyVerify(projectDir, artifactPath, criteria) {
   };
 }
 
+// ─── Loop Guardrails (loop-guardrails) ───────────────────────────────────────
+
+/**
+ * Hook pós-attempt na ordem D5: (1) artifacts → (2) scope guard + re-hash D2 →
+ * (3) diff limits → (4) human gates (Fase 2) → (5) criteria (Fase 2) →
+ * (6) budget/runtime. Registrar primeiro, julgar depois.
+ *
+ * Retorna { blocked, reason, feedback, issues } — `blocked` encerra o run;
+ * `feedback` injeta instrução de rollback e segue para a próxima iteração.
+ */
+async function runPostAttemptGuards({ targetDir, guards, cb, logger, attempt, agentOutput }) {
+  const { resolved, planDir } = guards;
+  const slug = resolved.feature;
+
+  // (1) registrar sempre, mesmo em falha
+  let changed = { files: [], rehashViolations: [] };
+  let diffPatch = '';
+  if (guards.baseline) {
+    try {
+      changed = computeChangedSet(targetDir, guards.baseline);
+      diffPatch = captureDiffPatch(targetDir);
+    } catch { /* git indisponível neste attempt — artifacts parciais */ }
+  }
+  writeAttemptArtifacts(planDir, attempt, { changedFiles: changed.files, diffPatch });
+
+  // tokens da tentativa acumulam sempre — o gasto já ocorreu (D3)
+  recordAttemptTokens(cb.progress, estimateTokens(agentOutput));
+
+  const outcome = { blocked: false, reason: null, feedback: null, issues: [] };
+
+  // (2) scope guard + re-hash D2 (REQ-4/5/6)
+  if (guards.baseline) {
+    const scope = checkScope({
+      changedFiles: changed.files,
+      rehashViolations: changed.rehashViolations,
+      allowedGlobs: resolved.allowed_files,
+      forbiddenGlobs: resolved.forbidden_files
+    });
+    if (!scope.ok) {
+      guards.scopeViolationCount += 1;
+      const fileList = scope.violations.map((v) => v.path);
+      logger.log(`  ✗ Scope violation (${fileList.length} file(s)): ${fileList.slice(0, 5).join(', ')}`);
+      await emitGuardEvent(targetDir, {
+        eventType: 'scope_violation',
+        message: `scope violation on attempt ${attempt}`,
+        payload: { slug, attempt, violations: scope.violations }
+      });
+      if (guards.scopeViolationCount >= 2) {
+        // reincidência abre o circuito e escala para humano (REQ-6)
+        cb.progress.circuit_state = 'OPEN';
+        cb.progress.status = 'circuit_open';
+        cb.progress.last_error = `scope_violation_repeat: ${fileList.slice(0, 3).join(', ')}`;
+        await cb._save();
+        outcome.blocked = true;
+        outcome.reason = 'scope_violation_repeat';
+        return outcome;
+      }
+      outcome.reason = 'scope_violation';
+      outcome.feedback = buildRollbackFeedback(scope.violations);
+      outcome.issues = [{ message: outcome.feedback }];
+    }
+  }
+
+  // (3) diff limits (REQ-10) — não julga se a tentativa já vai para rollback
+  if (!outcome.feedback) {
+    const limits = checkDiffLimits({
+      changedFiles: changed.files,
+      diffPatch,
+      maxChangedFiles: resolved.governor.max_changed_files ?? null,
+      maxDiffLines: resolved.governor.max_diff_lines ?? null
+    });
+    if (!limits.ok) {
+      const detail = limits.exceeded.map((e) => `${e.limit}: ${e.actual} > ${e.max}`).join('; ');
+      logger.log(`  ✗ Diff limit exceeded — ${detail}`);
+      await emitGuardEvent(targetDir, {
+        eventType: 'diff_limit_exceeded',
+        message: `diff limits exceeded on attempt ${attempt} (${detail})`,
+        payload: { slug, attempt, exceeded: limits.exceeded }
+      });
+      outcome.blocked = true;
+      outcome.reason = 'diff_limit_exceeded';
+    }
+  }
+
+  // (4) human gates (REQ-12, D4) — violação de escopo precede gate: arquivo
+  // fora do escopo merece rollback, não aprovação humana
+  if (!outcome.feedback && !outcome.blocked && guards.baseline) {
+    const detections = detectGates({
+      changedFiles: changed.files,
+      requiredFor: resolved.human_gate.required_for,
+      themePaths: resolved.human_gate.theme_paths,
+      existingGates: loadGates(planDir),
+      runId: cb.progress.budget ? cb.progress.budget.run_id : null
+    });
+    if (detections.length > 0) {
+      const created = [];
+      for (const detection of detections) {
+        const gate = createGate(planDir, {
+          theme: detection.theme,
+          attempt,
+          triggeredBy: detection.triggeredBy,
+          diffSummary: `${detection.triggeredBy.length} file(s): ${detection.triggeredBy.slice(0, 3).join(', ')}`,
+          runId: cb.progress.budget ? cb.progress.budget.run_id : null
+        });
+        created.push(gate);
+        await emitGuardEvent(targetDir, {
+          eventType: 'human_gate_requested',
+          message: `human gate ${gate.id} requested on attempt ${attempt}`,
+          payload: { slug, attempt, gate_id: gate.id, theme: gate.theme, triggered_by: gate.triggered_by }
+        });
+      }
+      enterHumanGate(cb.progress, created.map((g) => g.id));
+      await cb._save();
+      logger.log(`  ✗ Human gate requerido (${created.length}):`);
+      for (const gate of created) {
+        logger.log(`    - ${gate.id} [${gate.theme}] — ${gate.diff_summary}`);
+        logger.log(`      aioson harness:approve . --slug=${slug} --gate=${gate.id}`);
+      }
+      outcome.blocked = true;
+      outcome.reason = 'human_gate_pending';
+    }
+  }
+
+  // (5) criteria checks (REQ-16/17, D7) — pulado se a tentativa já vai para
+  // rollback ou gate (processo encerra)
+  if (!outcome.feedback && !outcome.blocked) {
+    const checks = await runCriteria({ criteria: resolved.criteria, cwd: targetDir });
+    if (checks.length > 0) {
+      writeAttemptArtifacts(planDir, attempt, { checks });
+      const failed = checks.filter((c) => !c.ok);
+      for (const check of failed) {
+        await emitGuardEvent(targetDir, {
+          eventType: 'criteria_check_failed',
+          message: `criterion ${check.id} failed on attempt ${attempt} (exit ${check.exitCode}${check.timedOut ? ', timeout' : ''})`,
+          payload: { slug, attempt, criterion_id: check.id, exit_code: check.exitCode, timed_out: check.timedOut, signature: check.signature }
+        });
+      }
+      const repeats = registerFailureSignatures(cb.progress, failed);
+      if (repeats.length > 0) {
+        // mesma assinatura 2x no run (EC-13) → para e escala para humano
+        cb.progress.circuit_state = 'OPEN';
+        cb.progress.status = 'circuit_open';
+        cb.progress.last_error = `failure_signature_repeat: ${repeats.map((r) => r.criterion_id).join(', ')}`;
+        await cb._save();
+        for (const repeat of repeats) {
+          await emitGuardEvent(targetDir, {
+            eventType: 'failure_signature_repeat',
+            message: `criterion ${repeat.criterion_id} failed twice with the same signature in this run`,
+            payload: { slug, attempt, criterion_id: repeat.criterion_id, signature: repeat.signature }
+          });
+        }
+        logger.log(`  ✗ Mesma falha 2x no run (${repeats.map((r) => r.criterion_id).join(', ')}) — escalando para humano`);
+        outcome.blocked = true;
+        outcome.reason = 'failure_signature_repeat';
+      } else if (failed.length > 0) {
+        logger.log(`  ✗ Criteria checks falharam: ${failed.map((c) => c.id).join(', ')}`);
+        outcome.reason = 'criteria_check_failed';
+        // AC-13: feedback = preview + ponteiro para attempts/{n}/checks/{id}.log
+        // (já persistido integralmente por writeAttemptArtifacts acima — persist-first
+        // satisfeito pelo fluxo existente). Evita dump integral no contexto do agente.
+        outcome.feedback = failed
+          .map((c) => {
+            const safeId = String(c.id || 'check').replace(/[^A-Za-z0-9._-]/g, '_');
+            const logPath = path.join(planDir, 'attempts', String(attempt), 'checks', `${safeId}.log`);
+            const raw = `${c.stdout || ''}${c.stderr ? `\n${c.stderr}` : ''}`.trim() || 'no output';
+            const { preview } = previewArtifact(raw, { maxBytes: 1024, artifactPath: logPath, persist: false });
+            return `Criterion ${c.id} failed (exit ${c.exitCode}${c.timedOut ? ', timeout' : ''}):\n${preview}`;
+          })
+          .join('\n\n');
+        outcome.issues = [{ message: outcome.feedback }];
+      }
+    }
+  }
+
+  // (6) budget/runtime (REQ-7/8, EC-11) — sempre avaliado e persistido
+  const budget = checkBudget(cb.progress, {
+    costCeilingTokens: resolved.governor.cost_ceiling_tokens ?? null,
+    maxRuntimeMinutes: resolved.governor.max_runtime_minutes ?? null
+  });
+  for (const event of budget.events) {
+    logger.log(`  ${event.type === 'budget_warning' ? '⚠' : '✗'} ${event.message}`);
+    await emitGuardEvent(targetDir, {
+      eventType: event.type,
+      message: event.message,
+      payload: { slug, attempt, ...event.payload },
+      tokenCount: cb.progress.budget.tokens_estimated
+    });
+  }
+  await cb._save();
+  if (budget.pause && !outcome.blocked) {
+    logger.log(buildBudgetSummary(cb.progress, { maxIterations: resolved.governor.max_steps }));
+    outcome.blocked = true;
+    outcome.reason = budget.events.find((e) => e.type !== 'budget_warning')?.type || 'budget_exceeded';
+  }
+
+  return outcome;
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -156,19 +364,29 @@ async function runSelfLoop({ args, options = {}, logger }) {
     if (fs.existsSync(autoPath)) contractPath = autoPath;
   }
 
+  // C-01 (QA 2026-06-09): sem --contract e sem --spec, descobre o contrato
+  // ATIVO em disco (mesma heurística do git:guard). O happy path do PRD e a
+  // retomada instruída por harness:approve/budget-guard re-entram sem flags —
+  // um contrato ativo nunca pode ficar silenciosamente fora do loop (REQ-1).
+  if (!contractPath) {
+    try {
+      const active = findActiveContract(targetDir);
+      if (active) contractPath = active.contractPath;
+    } catch { /* best-effort: descoberta nunca derruba o loop */ }
+  }
+
   if (contractPath && fs.existsSync(contractPath)) {
     const progressPath = path.join(path.dirname(contractPath), 'progress.json');
     cb = createCircuitBreaker(contractPath, progressPath);
     await cb.load();
     logger.log(`[Harness] Contract loaded: ${path.relative(targetDir, contractPath)}`);
+  } else {
+    logger.log('[Harness] guardrails inactive — no harness contract loaded');
   }
 
-  // Set max iterations: Contract policy takes precedence over flag
+  // Teto de iterações pela flag; o contrato (governor EFETIVO) sobrescreve no
+  // preflight dos guards, após validação de schema (C-02 / REQ-19).
   let maxIterations = Math.min(Math.max(Number(options['max-iterations'] || 3), 1), 5);
-  if (cb && cb.contract && cb.contract.governor && cb.contract.governor.max_steps > 0) {
-    maxIterations = cb.contract.governor.max_steps;
-    logger.log(`[Harness] Max iterations set by contract: ${maxIterations}`);
-  }
 
   if (!task) {
     logger.error('Error: --task is required');
@@ -178,6 +396,74 @@ async function runSelfLoop({ args, options = {}, logger }) {
   const sessionId = randomUUID();
   const feedbackHistory = [];
 
+  // Loop Guardrails — preflight (REQ-1/2 + D3): valida o schema do contrato,
+  // captura o baseline git e zera o orçamento do run. Sem contrato = sem
+  // guards (retrocompat REQ-11).
+  let guards = null;
+  if (cb) {
+    const schemaResult = validateContract(cb.contract);
+    if (!schemaResult.ok) {
+      logger.log(`── Harness Block ──────────────────────────────────────────`);
+      for (const err of schemaResult.errors) {
+        logger.log(`  ✗ contract schema invalid: ${err.field} — ${err.reason}`);
+      }
+      await emitGuardEvent(targetDir, {
+        eventType: 'contract_invalid',
+        message: 'harness-contract.json failed schema validation',
+        payload: { slug: (cb.contract && cb.contract.feature) || null, errors: schemaResult.errors }
+      });
+      return { ok: false, iterations: 0, verdict: 'BLOCKED', reason: 'contract_schema_invalid', errors: schemaResult.errors };
+    }
+    for (const warning of schemaResult.warnings) {
+      logger.log(`  ⚠ contract: ${warning.field} — ${warning.reason}`);
+    }
+
+    const resolved = resolveContract(cb.contract);
+    const planDir = path.dirname(contractPath);
+
+    // C-02 (REQ-19): o breaker (check/recordError) e o teto de iterações leem
+    // `contract.governor` — injeta o governor EFETIVO (presets do contract_mode
+    // aplicados) para que `builder`/`autopilot` valham fora de budget/diff.
+    cb.contract.governor = resolved.governor;
+    if (resolved.governor && resolved.governor.max_steps > 0) {
+      maxIterations = resolved.governor.max_steps;
+      logger.log(`[Harness] Max iterations set by contract: ${maxIterations}`);
+    }
+
+    // (EC-9) gates pendentes de run anterior são REAPRESENTADOS antes de
+    // qualquer detecção nova; aprovação prévia restaura a retomada (REQ-15)
+    resolveGateState(cb.progress, planDir);
+    const pendingFromBefore = pendingGates(planDir);
+    if (pendingFromBefore.length > 0) {
+      enterHumanGate(cb.progress, pendingFromBefore.map((g) => g.id));
+      await cb._save();
+      logger.log(`── Harness Block ──────────────────────────────────────────`);
+      logger.log(`  ✗ Human gate pendente (${pendingFromBefore.length}):`);
+      for (const gate of pendingFromBefore) {
+        logger.log(`    - ${gate.id} [${gate.theme}] attempt ${gate.attempt} — ${gate.diff_summary || (gate.triggered_by || []).join(', ')}`);
+        logger.log(`      aioson harness:approve . --slug=${resolved.feature} --gate=${gate.id}`);
+        logger.log(`      aioson harness:reject . --slug=${resolved.feature} --gate=${gate.id} --reason="..."`);
+      }
+      return { ok: false, iterations: 0, verdict: 'BLOCKED', reason: 'human_gate_pending', gates: pendingFromBefore.map((g) => g.id) };
+    }
+
+    let baseline = null;
+    try {
+      const captured = captureBaseline(targetDir, planDir, { forbiddenGlobs: resolved.forbidden_files });
+      baseline = captured.baseline;
+      for (const warning of captured.warnings) {
+        logger.log(`  ⚠ baseline: ${warning.path} — ${warning.reason}`);
+      }
+    } catch (err) {
+      logger.log(`  ⚠ scope guard inactive for this run: git baseline unavailable (${String(err.message || err).slice(0, 80)})`);
+    }
+
+    startRunBudget(cb.progress, sessionId);
+    startRunSignatures(cb.progress); // D7: assinaturas de falha são por run
+    await cb._save();
+    guards = { resolved, planDir, baseline, scopeViolationCount: 0 };
+  }
+
   logger.log(`Self-implement loop: @${agent} — "${task.slice(0, 60)}${task.length > 60 ? '...' : ''}"`);
   logger.log(`Max iterations: ${maxIterations}`);
   if (spec) logger.log(`Spec: ${spec}`);
@@ -223,6 +509,30 @@ async function runSelfLoop({ args, options = {}, logger }) {
     logger.log('  Verifying...');
     const verifyResult = await runVerification(targetDir, spec, artifact, criteria);
 
+    // Loop Guardrails — hook pós-attempt (ordem D5). Roda ANTES de aceitar o
+    // sucesso: violação de escopo em tentativa "verde" ainda bloqueia.
+    if (guards) {
+      const guardOutcome = await runPostAttemptGuards({
+        targetDir,
+        guards,
+        cb,
+        logger,
+        attempt: iteration,
+        agentOutput: agentResult.output
+      });
+      if (guardOutcome.blocked) {
+        logger.log(`── Harness Block ──────────────────────────────────────────`);
+        logger.log(`  ✗ Loop paused by guardrail: ${guardOutcome.reason}`);
+        return { ok: false, iterations: iteration, verdict: 'BLOCKED', reason: guardOutcome.reason, feedback: feedbackHistory };
+      }
+      if (guardOutcome.feedback) {
+        const guardVerdict = guardOutcome.reason === 'scope_violation' ? 'SCOPE_VIOLATION' : 'CRITERIA_FAILED';
+        feedbackHistory.push({ iteration, verdict: guardVerdict, issues: guardOutcome.issues });
+        await cb.recordError(guardOutcome.reason);
+        continue;
+      }
+    }
+
     // Record on bus
     if (squad) {
       await bus.post(targetDir, squad, sessionId, {

package/src/commands/workflow-next.js

@@ -32,9 +32,24 @@ const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
 const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
   MICRO: ['product', 'dev', 'qa'],
   SMALL: ['product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'scope-check', 'dev', 'pentester', 'qa']
+  // MEDIUM routes through @pm after discovery-design-doc (mirrors the
+  // project-mode position): Gate C requires implementation-plan-{slug}.md and
+  // @pm is its canonical owner (AC-SDLC-15/16) — without the stage, the
+  // sequence dead-ends at @dev preflight with no agent to produce the plan.
+  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'pm', 'scope-check', 'dev', 'pentester', 'qa']
 };
 
+// Stages eligible for autopilot handoff (auto_handoff: true in project.context.md).
+// Two segments — see .aioson/docs/autopilot-handoff.md:
+//   1. analyst → dev: deterministic pre-dev chain; STOPS before the first @dev entry
+//      (human clears context and starts implementation).
+//   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa triggers
+//      fire) → @validator → STOPS before feature:close (human approves the close).
+const AUTOPILOT_HANDOFF_STAGES = new Set([
+  'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'pm',
+  'dev', 'qa', 'tester', 'pentester', 'validator'
+]);
+
 function normalizeAgentName(input) {
   return String(input || '')
     .trim()
@@ -303,6 +318,16 @@ async function validateStageArtifacts(targetDir, state, stage) {
     return (await anyExists(designDocCandidates)) && (await anyExists(readinessCandidates));
   }
 
+  if (stage === 'pm') {
+    // Feature mode: @pm's canonical artifact is the implementation plan
+    // (Gate C input). Project mode has no single canonical pm artifact —
+    // the handoff contract covers feature MEDIUM (AC-SDLC-16).
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `implementation-plan-${slug}.md`));
+    }
+    return true;
+  }
+
   if (stage === 'orchestrator') {
     return await exists(path.join(base, 'parallel'));
   }
@@ -431,7 +456,9 @@ function isInferableStage(stage) {
   // (it has both a validateStageArtifacts branch and a handoff contract). Without
   // it, MEDIUM sequences — where scope-check sits AFTER discovery-design-doc —
   // could never infer scope-check as completed during stale-state recovery.
-  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'orchestrator'].includes(
+  // pm is inferable from implementation-plan-{slug}.md for the same reason:
+  // it sits before scope-check in the MEDIUM feature sequence.
+  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator'].includes(
     normalizeAgentName(stage)
   );
 }
@@ -1226,6 +1253,20 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     requestedMode
   });
 
+  let autoHandoff = false;
+  if (
+    AUTOPILOT_HANDOFF_STAGES.has(stageName) &&
+    state.mode === 'feature' &&
+    (state.classification === 'SMALL' || state.classification === 'MEDIUM')
+  ) {
+    try {
+      const projectContext = await validateProjectContextFile(targetDir);
+      autoHandoff = Boolean(projectContext && projectContext.data && projectContext.data.auto_handoff === true);
+    } catch {
+      autoHandoff = false;
+    }
+  }
+
   const instructionPath = await resolveExistingInstructionPath(targetDir, agent, locale);
   const dependencies = await resolveStageDependencies(targetDir, state, stageName, agent);
   let prompt = buildAgentPrompt(agent, tool, {
@@ -1235,6 +1276,7 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     autonomyMode: effectiveMode,
     capabilitySummary: buildAgentCapabilitySummary(agentManifest, tool),
     dependsOn: dependencies,
+    autoHandoff,
     activationContext: buildStageActivationContext(state, stageName, dependencies, scopeCheckMode)
   });
 
@@ -1636,6 +1678,7 @@ async function runWorkflowNext({ args, options, logger, t }) {
 }
 
 module.exports = {
+  AUTOPILOT_HANDOFF_STAGES,
   STATE_RELATIVE_PATH,
   CONFIG_RELATIVE_PATH,
   EVENTS_RELATIVE_PATH,

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