@jaimevalasek/aioson 1.21.8 → 1.22.0

package/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
+All notable changes to this project will be documented in this file.
+
+## [1.22.0] - 2026-06-10
+
+### Added
+- **Loop guardrails for self-implementation harnesses.** `self:loop` now runs from an active contract with schema validation, active-contract discovery, scope enforcement, budget ceilings, attempt artifacts, criteria verification, failure-signature escalation, and human approval gates.
+- **Harness gate/status commands.** Added `harness:status` and human gate approval/rejection flows so paused loop work can be inspected, resumed, or explicitly blocked without losing context.
+- **Contract-aware git guard integration.** `git:guard` now merges declared `forbidden_files` from the active harness contract while preserving safe human commit behavior for lockfiles unless the contract explicitly forbids them.
+
+### Changed
+- **Dev/QA prompts now understand loop guardrails.** Workspace and template agent prompts were updated so implementation, QA, correction loops, and handoffs consume the new guarded harness model consistently.
+- **Loop-guardrails feature artifacts are now durable.** PRD, requirements, readiness, design, scope-check, Sheldon enrichment, dossier, corrections plan, and progress artifacts were recorded under `.aioson/context/` and `.aioson/plans/`.
+
+### Tests
+- Added regression coverage for contract schema validation, glob matching, scope guard behavior, budget enforcement, criteria execution, human gates, active-contract discovery, git guard contract merging, and self-loop guardrails.
+
 ## [1.21.8] - 2026-06-08
-
-### Added
+
+### Added
 - **`feature:export` — copy a feature's artefacts to a clean output directory.** Non-destructive sibling of `feature:archive`: instead of *moving* artefacts into `.aioson/context/done/{slug}/`, it *copies* the full surface (root `*-{slug}.{md,yaml,yml,json}` minus global files, the per-slug `dossier/`/`plans/`/`briefings/` directories, and `context/done/{slug}/` when archived) into an arbitrary `--out` (default `<target>/{slug}-export`), leaving the source tree untouched. Flags: `--flatten` (collapse to one level), `--no-index` (skip the generated `INDEX.md` manifest), `--dry-run`, `--json`. Reuses the archive's slug-collision guard via the new exported `collectFeatureArtifacts` helper, so a sibling slug (`checkout-v2`) never leaks into a `checkout` export. No `features.md` status guard — works on in-progress features too. Turns AIOSON's markdown output into a portable deliverable. Docs: `docs/pt/5-referencia/feature-export.md` + `docs/en/5-reference/cli-reference.md`.
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.8",
+  "version": "1.22.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agents.js

@@ -29,15 +29,16 @@ function buildAgentPrompt(agent, tool, options = {}) {
   const safeTool = String(tool || 'codex').toLowerCase();
   const instructionPath = options.instructionPath || agent.path;
   const targetDir = options.targetDir ? String(options.targetDir) : '.';
-  const interactionLanguage = String(options.interactionLanguage || 'en');
-  const autonomyMode = String(options.autonomyMode || '').trim();
-  const capabilitySummary = String(options.capabilitySummary || '').trim();
-  const activationContext = String(options.activationContext || '').trim();
-  const dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : agent.dependsOn;
-  const dependencyText =
-    dependsOn.length > 0
-      ? `Check required context files first: ${dependsOn.join(', ')}.`
-      : 'No prerequisite context files are required.';
+  const interactionLanguage = String(options.interactionLanguage || 'en');
+  const autonomyMode = String(options.autonomyMode || '').trim();
+  const autoHandoff = options.autoHandoff === true;
+  const capabilitySummary = String(options.capabilitySummary || '').trim();
+  const activationContext = String(options.activationContext || '').trim();
+  const dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : agent.dependsOn;
+  const dependencyText =
+    dependsOn.length > 0
+      ? `Check required context files first: ${dependsOn.join(', ')}.`
+      : 'No prerequisite context files are required.';
   const activationBlock = activationContext
     ? [
       '',
@@ -66,19 +67,19 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
     '',
-    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.`,
+    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies, never past the `@dev` handoff.' : ''}`,
   ].join('\n');
 
-  if (safeTool === 'claude') {
-    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nWrite output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  if (safeTool === 'opencode') {
-    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-}
+  if (safeTool === 'claude') {
+    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nWrite output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  if (safeTool === 'opencode') {
+    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+}
 
 module.exports = {
   normalizeAgentName,

package/src/cli.js

@@ -399,6 +399,12 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'harness-validate',
   'harness:apply-validation',
   'harness-apply-validation',
+  'harness:approve',
+  'harness-approve',
+  'harness:reject',
+  'harness-reject',
+  'harness:status',
+  'harness-status',
   'brief-gen',
   'verify:gate',
   'verify-gate',
@@ -1256,6 +1262,15 @@ async function main() {
       result = await runHarnessValidate({ args, options, logger: commandLogger, t });
     } else if (command === 'harness:apply-validation' || command === 'harness-apply-validation') {
       result = await runHarnessApplyValidation({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:approve' || command === 'harness-approve') {
+      const { runHarnessApprove } = require('./commands/harness-gate');
+      result = await runHarnessApprove({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:reject' || command === 'harness-reject') {
+      const { runHarnessReject } = require('./commands/harness-gate');
+      result = await runHarnessReject({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:status' || command === 'harness-status') {
+      const { runHarnessStatus } = require('./commands/harness-status');
+      result = await runHarnessStatus({ args, options, logger: commandLogger, t });
     } else if (command === 'verify:gate' || command === 'verify-gate') {
       result = await runVerifyGate({ args, options, logger: commandLogger, t });
 

package/src/commands/feature-close.js

@@ -333,6 +333,46 @@ async function runFeatureClose({ args, options = {}, logger }) {
     const contractContent = await readFileSafe(contractPath);
     const progressContent = await readFileSafe(progressPath);
 
+    // REQ-13 (loop-guardrails): tema `publish` é gate de COMANDO — intercepta
+    // o feature:close quando o contrato ativo o exige e não há gate publish
+    // aprovado. Nunca detectado por diff. `--force` NÃO bypassa: a aprovação
+    // humana é o propósito do gate (decisão registrada no spec da feature).
+    if (contractContent) {
+      try {
+        const contract = JSON.parse(contractContent);
+        const requiredFor = contract && contract.human_gate && Array.isArray(contract.human_gate.required_for)
+          ? contract.human_gate.required_for
+          : [];
+        if (requiredFor.includes('publish')) {
+          const { hasApprovedPublishGate, pendingGates, createGate } = require('../harness/human-gate');
+          const { emitGuardEvent } = require('../harness/guard-events');
+          if (!hasApprovedPublishGate(planDir)) {
+            let gate = pendingGates(planDir).find((g) => g.theme === 'publish');
+            if (!gate) {
+              gate = createGate(planDir, {
+                theme: 'publish',
+                attempt: 0,
+                triggeredBy: [],
+                diffSummary: `feature:close ${slug}`,
+                runId: null
+              });
+              await emitGuardEvent(targetDir, {
+                eventType: 'human_gate_requested',
+                message: `publish gate ${gate.id} requested by feature:close`,
+                payload: { slug, gate_id: gate.id, theme: 'publish' }
+              });
+            }
+            const errMsg = `[Publish Gate BLOCKED] Feature "${slug}" requires human approval before closing (human_gate.required_for includes "publish"). Approve with: aioson harness:approve . --slug=${slug} --gate=${gate.id}`;
+            if (options.json) {
+              return { ok: false, reason: 'publish_gate_pending', feature: slug, gate: gate.id, error: errMsg };
+            }
+            logger.log(errMsg);
+            return { ok: false };
+          }
+        }
+      } catch { /* contrato ilegível — o done gate abaixo lida com o estado */ }
+    }
+
     if (contractContent && progressContent) {
       const force = options.force === true;
       let progress = null;

package/src/commands/gate-check.js

@@ -36,7 +36,10 @@ const GATE_PREREQUISITES = {
 const GATE_REQUIRED_ARTIFACTS = {
   A: (slug) => [`requirements-${slug}.md`],
   B: (slug) => ['architecture.md'],
-  C: (slug) => [`implementation-plan-${slug}.md`],
+  // implementation-plan-{slug}.md is a MEDIUM-only artifact (@pm owns it,
+  // AC-SDLC-15/16). SMALL/MICRO sequences never route through @pm, so
+  // requiring it unconditionally dead-ends Gate C for those features.
+  C: (slug, classification) => (classification === 'MEDIUM' ? [`implementation-plan-${slug}.md`] : []),
   D: (slug) => [] // Gate D validated by QA sign-off in spec
 };
 
@@ -75,7 +78,7 @@ async function checkGate(targetDir, slug, gateLetter) {
   }
 
   // Check required artifacts
-  const requiredFiles = GATE_REQUIRED_ARTIFACTS[gateLetter](slug);
+  const requiredFiles = GATE_REQUIRED_ARTIFACTS[gateLetter](slug, classification);
   for (const fileName of requiredFiles) {
     const filePath = path.join(dir, fileName);
     const exists = await fileExists(filePath);
@@ -150,7 +153,9 @@ async function checkGate(targetDir, slug, gateLetter) {
     const fixAgents = {
       A: `activate @analyst to produce requirements-${slug}.md, then run: aioson gate:approve . --feature=${slug} --gate=A`,
       B: `activate @architect to produce architecture.md, then run: aioson gate:approve . --feature=${slug} --gate=B`,
-      C: `activate @pm to produce and approve implementation-plan-${slug}.md, then run: aioson gate:approve . --feature=${slug} --gate=C`,
+      C: classification === 'MEDIUM'
+        ? `activate @pm to produce and approve implementation-plan-${slug}.md, then run: aioson gate:approve . --feature=${slug} --gate=C`
+        : `approve Gates A and B first, then run: aioson gate:approve . --feature=${slug} --gate=C`,
       D: `activate @qa for final verification; if QA passes, run: aioson gate:approve . --feature=${slug} --gate=D`
     };
     recommendation = `BLOCKED — ${fixAgents[gateLetter] || 'resolve missing items'}`;

package/src/commands/git-guard.js

@@ -12,12 +12,64 @@
  */
 
 const path = require('node:path');
+const fs = require('node:fs');
 const {
   inspectStagedChanges,
   installPreCommitHook,
   uninstallPreCommitHook
 } = require('../lib/git-commit-guard');
 
+/**
+ * REQ-20 (loop-guardrails, should-have): mescla `forbidden_files` do contrato
+ * ATIVO (progress `in_progress`/`human_gate` mais recente) na verificação do
+ * guard em tempo de execução — camada 2 do scope guard no pre-commit.
+ * Best-effort: nunca quebra o guard; contrato inválido é ignorado (o preflight
+ * do self:loop já bloqueia o loop nesse caso). Paths `.aioson/**` ficam fora
+ * (estado do framework precisa ser commitável).
+ *
+ * C-03 (QA 2026-06-09): nesta camada aplicam-se apenas os globs DECLARADOS no
+ * contrato. Os defaults não-removíveis (lockfiles, node_modules, .env*, ...)
+ * existem para conter o LOOP do agente; no pre-commit pegariam mudanças
+ * humanas legítimas (ex.: package-lock.json após `npm install`). Segredos
+ * (.env*, *.pem, *.key, secrets/**) continuam bloqueados pela policy baseline
+ * do próprio git-guard.
+ */
+const { findActiveContract } = require('../harness/active-contract');
+
+function applyActiveContractPolicy(targetDir, result) {
+  const active = findActiveContract(targetDir);
+  if (!active) return null;
+  const { validateContract } = require('../harness/contract-schema');
+  const { matchGlob, matchAny } = require('../harness/glob-match');
+  const contract = JSON.parse(fs.readFileSync(active.contractPath, 'utf8'));
+  if (!validateContract(contract).ok) return null;
+  const declaredForbidden = Array.isArray(contract.forbidden_files) ? contract.forbidden_files : [];
+  if (!declaredForbidden.length) return { slug: active.slug, findings: 0 };
+
+  let added = 0;
+  for (const file of result.files) {
+    if (matchGlob('.aioson/**', file.path)) continue;
+    const matched = matchAny(declaredForbidden, file.path);
+    if (!matched) continue;
+    const finding = {
+      type: 'path',
+      severity: 'error',
+      id: 'contract_forbidden_file',
+      path: file.path,
+      reason: `matches forbidden glob "${matched}" from active harness contract "${active.slug}"`,
+      line: null
+    };
+    file.findings.push(finding);
+    result.errors.push(finding);
+    added += 1;
+  }
+  if (added > 0) {
+    result.ok = false;
+    result.summary.errorCount = result.errors.length;
+  }
+  return { slug: active.slug, findings: added };
+}
+
 function formatFinding(prefix, finding) {
   const line = finding.line ? `:${finding.line}` : '';
   return `${prefix} ${finding.path}${line} — ${finding.reason} [${finding.id}]`;
@@ -111,9 +163,15 @@ async function runGitGuard({ args, options = {}, logger }) {
     return failure;
   }
 
+  let contractPolicy = null;
+  try {
+    contractPolicy = applyActiveContractPolicy(targetDir, result);
+  } catch { /* best-effort: contrato ilegível nunca quebra o guard */ }
+
   const output = {
     ok: result.ok,
     projectDir: targetDir,
+    contractPolicy,
     gitRoot: result.gitRoot,
     strict: result.strict,
     policy: result.policy,

package/src/commands/harness-gate.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * aioson harness:approve / harness:reject — decisão humana de gates do
+ * self:loop (loop-guardrails REQ-14/15).
+ *
+ * - Exigem --slug e --gate; reject exige --reason.
+ * - Decisão persiste em `.aioson/plans/{slug}/gates/{id}.json`
+ *   (decided_at/decided_by/reason) e emite `human_gate_decision`.
+ * - Gate já decidido = no-op idempotente com aviso (REQ-14).
+ * - Gate inexistente = erro explícito sem efeito colateral (EC-8).
+ * - Sem pendências restantes → progress.status volta a `in_progress`;
+ *   re-executar `self:loop` retoma do ponto persistido (REQ-15).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { decideGate, resolveGateState, pendingGates } = require('../harness/human-gate');
+const { emitGuardEvent } = require('../harness/guard-events');
+
+function gitUserName(targetDir) {
+  try {
+    return execFileSync('git', ['config', 'user.name'], {
+      cwd: targetDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function runGateDecision(decision, { args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const slug = String(options.slug || '').trim();
+  const gateId = String(options.gate || '').trim();
+  const reason = options.reason ? String(options.reason).trim() : null;
+  const decidedBy = options.by ? String(options.by).trim() : gitUserName(targetDir);
+
+  if (!slug) {
+    logger.error('Error: --slug is required');
+    return { ok: false, error: 'missing_slug' };
+  }
+  if (!gateId) {
+    logger.error('Error: --gate is required (gate id, e.g. payment_logic_change-1)');
+    return { ok: false, error: 'missing_gate' };
+  }
+
+  const planDir = path.join(targetDir, '.aioson', 'plans', slug);
+  if (!fs.existsSync(path.join(planDir, 'harness-contract.json'))) {
+    logger.error(`Contract not found for slug: ${slug}`);
+    return { ok: false, error: 'contract_not_found' };
+  }
+
+  const result = decideGate(planDir, gateId, { decision, by: decidedBy, reason });
+
+  if (!result.ok) {
+    const messages = {
+      gate_not_found: `Gate not found: ${gateId} — nothing to ${decision === 'approved' ? 'approve' : 'reject'} (no side effects)`,
+      reason_required_on_reject: 'Error: --reason is required when rejecting a gate',
+      gate_corrupted: `Gate file is corrupted: ${gateId}`,
+      invalid_decision: `Invalid decision: ${decision}`
+    };
+    logger.error(messages[result.error] || `Error: ${result.error}`);
+    return { ok: false, error: result.error, gateId };
+  }
+
+  if (result.idempotent) {
+    logger.log(`• Gate ${gateId} already decided (${result.gate.status} at ${result.gate.decided_at}) — no-op`);
+    return { ok: true, idempotent: true, gate: result.gate };
+  }
+
+  // reconcilia progress.json: remove decidido de pending_gates; sem pendências
+  // restantes → status volta a in_progress (retomada idempotente / auditoria)
+  const progressPath = path.join(planDir, 'progress.json');
+  let remaining = [];
+  try {
+    if (fs.existsSync(progressPath)) {
+      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf8'));
+      resolveGateState(progress, planDir);
+      fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2), 'utf8');
+      remaining = progress.pending_gates || [];
+    } else {
+      remaining = pendingGates(planDir).map((g) => g.id);
+    }
+  } catch { /* progress corrompido — decisão do gate já persistiu */ }
+
+  await emitGuardEvent(targetDir, {
+    eventType: 'human_gate_decision',
+    message: `gate ${gateId} ${decision} by ${decidedBy || 'unknown'}`,
+    payload: { slug, gate_id: gateId, theme: result.gate.theme, decision, decided_by: decidedBy, reason }
+  });
+
+  const mark = decision === 'approved' ? '✓' : '✗';
+  logger.log(`${mark} Gate ${gateId} ${decision}${decidedBy ? ` by ${decidedBy}` : ''}${reason ? ` — ${reason}` : ''}`);
+  if (remaining.length > 0) {
+    logger.log(`  Pending gates remaining: ${remaining.join(', ')}`);
+  } else if (decision === 'approved') {
+    logger.log(`  No pending gates — re-run self:loop to resume from the persisted state.`);
+  } else {
+    logger.log(`  Run ended. A new self:loop starts a fresh run (rejected gate is kept as audit).`);
+  }
+
+  return { ok: true, gate: result.gate, pending_gates: remaining };
+}
+
+async function runHarnessApprove(ctx) {
+  return runGateDecision('approved', ctx);
+}
+
+async function runHarnessReject(ctx) {
+  return runGateDecision('rejected', ctx);
+}
+
+module.exports = {
+  runHarnessApprove,
+  runHarnessReject
+};

package/src/commands/harness-status.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * aioson harness:status . --slug=X [--json] — visibilidade do estado do loop
+ * (loop-guardrails REQ-18).
+ *
+ * Agrega: circuito, iteração N/M, budget, checks da última tentativa,
+ * última falha, gates pendentes e a próxima ação. Escopo distinto de
+ * `spec:status` (planos+learnings) — referenciado no rodapé.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { resolveContract, validateContract } = require('../harness/contract-schema');
+const { pendingGates } = require('../harness/human-gate');
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Última tentativa = maior diretório numérico em attempts/. */
+function latestAttempt(planDir) {
+  const dir = path.join(planDir, 'attempts');
+  if (!fs.existsSync(dir)) return null;
+  const numbers = fs.readdirSync(dir)
+    .map((name) => Number(name))
+    .filter((n) => Number.isInteger(n) && n > 0);
+  return numbers.length ? Math.max(...numbers) : null;
+}
+
+/** Conta checks pass/fail da tentativa pelos logs `# exit_code:`. */
+function readChecks(planDir, attempt) {
+  const checksDir = path.join(planDir, 'attempts', String(attempt), 'checks');
+  if (!fs.existsSync(checksDir)) return { total: 0, passed: 0, failed: 0, failed_ids: [] };
+  const summary = { total: 0, passed: 0, failed: 0, failed_ids: [] };
+  for (const file of fs.readdirSync(checksDir)) {
+    if (!file.endsWith('.log')) continue;
+    summary.total += 1;
+    try {
+      const content = fs.readFileSync(path.join(checksDir, file), 'utf8');
+      const match = content.match(/^# exit_code: (.+)$/m);
+      if (match && match[1].trim() === '0') {
+        summary.passed += 1;
+      } else {
+        summary.failed += 1;
+        summary.failed_ids.push(file.replace(/\.log$/, ''));
+      }
+    } catch {
+      summary.failed += 1;
+    }
+  }
+  return summary;
+}
+
+function nextAction(progress, pending, slug) {
+  if (pending.length > 0) {
+    return `aioson harness:approve . --slug=${slug} --gate=${pending[0].id} (ou harness:reject --reason="...")`;
+  }
+  const status = progress?.status || 'unknown';
+  if (status === 'circuit_open' || progress?.circuit_state === 'OPEN') {
+    return 'circuito aberto — revisar last_error e corrigir antes de novo run';
+  }
+  if (status === 'waiting_validation') {
+    return `aioson harness:validate . --slug=${slug}`;
+  }
+  if (progress?.ready_for_done_gate) {
+    return `pronto para o done gate — aioson feature:close . --feature=${slug}`;
+  }
+  return `re-executar self:loop para continuar (iteração persiste em progress.json)`;
+}
+
+async function runHarnessStatus({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const slug = String(options.slug || '').trim();
+
+  if (!slug) {
+    logger.error('Error: --slug is required');
+    return { ok: false, error: 'missing_slug' };
+  }
+
+  const planDir = path.join(targetDir, '.aioson', 'plans', slug);
+  const contract = readJson(path.join(planDir, 'harness-contract.json'));
+  if (!contract) {
+    logger.error(`Contract not found for slug: ${slug}`);
+    return { ok: false, error: 'contract_not_found' };
+  }
+
+  const progress = readJson(path.join(planDir, 'progress.json'));
+  const schema = validateContract(contract);
+  const resolved = schema.ok ? resolveContract(contract) : null;
+  const pending = pendingGates(planDir);
+  const attempt = latestAttempt(planDir);
+  const checks = attempt ? readChecks(planDir, attempt) : { total: 0, passed: 0, failed: 0, failed_ids: [] };
+
+  const maxSteps = resolved ? resolved.governor.max_steps : (contract.governor && contract.governor.max_steps) || null;
+  const ceiling = resolved ? (resolved.governor.cost_ceiling_tokens ?? null) : null;
+  const budget = progress?.budget || null;
+
+  const report = {
+    ok: true,
+    slug,
+    contract_mode: contract.contract_mode || 'BALANCED',
+    contract_schema_ok: schema.ok,
+    circuit_state: progress?.circuit_state || 'CLOSED',
+    status: progress?.status || 'unknown',
+    iterations: progress?.iterations ?? 0,
+    max_steps: maxSteps,
+    budget: budget ? {
+      tokens_estimated: budget.tokens_estimated || 0,
+      cost_ceiling_tokens: ceiling,
+      run_id: budget.run_id || null,
+      run_started_at: budget.run_started_at || null
+    } : null,
+    last_attempt: attempt,
+    checks,
+    last_error: progress?.last_error || null,
+    pending_gates: pending.map((g) => ({ id: g.id, theme: g.theme, attempt: g.attempt, requested_at: g.requested_at })),
+    next_action: nextAction(progress, pending, slug)
+  };
+
+  if (options.json) {
+    logger.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  logger.log(`Harness status — ${slug}`);
+  logger.log(`  Mode: ${report.contract_mode}${schema.ok ? '' : '  (⚠ contract schema invalid)'}`);
+  logger.log(`  Circuit: ${report.circuit_state} | status: ${report.status}`);
+  logger.log(`  Iteration: ${report.iterations}${maxSteps ? `/${maxSteps}` : ''}`);
+  if (budget) {
+    logger.log(`  Budget: ${report.budget.tokens_estimated} tokens estimados${ceiling ? ` / ${ceiling} (${Math.round((report.budget.tokens_estimated / ceiling) * 100)}%)` : ' (sem teto)'}`);
+  }
+  if (attempt) {
+    logger.log(`  Last attempt: ${attempt} — checks ${checks.passed}/${checks.total} pass${checks.failed ? ` (failed: ${checks.failed_ids.join(', ')})` : ''}`);
+  }
+  if (report.last_error) logger.log(`  Last error: ${report.last_error}`);
+  if (pending.length > 0) {
+    logger.log(`  ⛔ Pending gates (${pending.length}):`);
+    for (const gate of pending) {
+      logger.log(`    - ${gate.id} [${gate.theme}] attempt ${gate.attempt}`);
+    }
+  }
+  logger.log(`  Next: ${report.next_action}`);
+  logger.log('');
+  logger.log('  Planos e learnings: aioson spec:status');
+
+  return report;
+}
+
+module.exports = {
+  runHarnessStatus
+};

package/src/commands/harness.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { createCircuitBreaker } = require('../harness/circuit-breaker');
+const { validateContract } = require('../harness/contract-schema');
 
 /**
  * aioson harness:init — Inicializa o contrato e progresso da feature.
@@ -36,8 +37,17 @@ async function runHarnessInit({ args, options = {}, logger, t }) {
     governor: {
       max_steps: 50,
       error_streak_limit: 5,
-      cost_ceiling_tokens: null
+      cost_ceiling_tokens: null,
+      max_runtime_minutes: null,
+      max_changed_files: null,
+      max_diff_lines: null
     },
+    // Scope guard (loop-guardrails): allowed_files ausente = sem allowlist;
+    // forbidden_files é SEMPRE mesclado com os defaults embutidos (.env*, *.pem,
+    // *.key, secrets/**, .git/**, node_modules/**, lockfiles) — não-removíveis.
+    forbidden_files: [],
+    // human_gate ausente = nenhum gate (retrocompat). Exemplo:
+    // "human_gate": { "required_for": ["payment_logic_change", "publish"] }
     criteria: [
       {
         id: "C1",
@@ -48,6 +58,13 @@ async function runHarnessInit({ args, options = {}, logger, t }) {
     ]
   };
 
+  const schemaResult = validateContract(contract);
+  if (!schemaResult.ok) {
+    const first = schemaResult.errors[0];
+    logger.error(`Contract schema invalid: ${first.field} — ${first.reason}`);
+    return { ok: false, error: 'contract_schema_invalid', errors: schemaResult.errors };
+  }
+
   const cb = createCircuitBreaker(contractPath, progressPath);
   fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2), 'utf8');
   await cb.load();