@jaimevalasek/aioson 1.21.8 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.8",
+  "version": "1.23.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. The chain stops before the first `@dev` activation (human clears context and starts implementation) and continues through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`); it NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
   ].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

@@ -268,6 +268,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'workflow-next',
   'workflow:status',
   'workflow-status',
+  'harness:retro',
+  'harness-retro',
+  'harness:preview',
+  'harness-preview',
   'agent:next',
   'agent-next',
   'parallel:init',
@@ -399,6 +403,16 @@ 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',
+  'harness:retro',
+  'harness-retro',
+  'harness:preview',
+  'harness-preview',
   'brief-gen',
   'verify:gate',
   'verify-gate',
@@ -811,6 +825,8 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_qa_run');
   logHelpLine(t, logger, 'cli.help_qa_scan');
   logHelpLine(t, logger, 'cli.help_qa_report');
+  logHelpLine(t, logger, 'cli.help_harness_retro');
+  logHelpLine(t, logger, 'cli.help_harness_preview');
   logHelpLine(t, logger, 'cli.help_web_map');
   logHelpLine(t, logger, 'cli.help_web_scrape');
   logHelpLine(t, logger, 'cli.help_scan_project');
@@ -1256,6 +1272,21 @@ 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 === 'harness:retro' || command === 'harness-retro') {
+      const { runHarnessRetro } = require('./commands/harness-retro');
+      result = await runHarnessRetro({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:preview' || command === 'harness-preview') {
+      const { runHarnessPreview } = require('./commands/harness-preview');
+      result = await runHarnessPreview({ 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-preview.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * `aioson harness:preview <file> [--max-bytes=8192] [--json]` (requirements §5.2).
+ *
+ * Wrapper fino e read-only de `previewArtifact` sobre um arquivo já persistido
+ * (ex.: `npm test > test.log`). Devolve preview + ponteiro para o agente de teste
+ * consumir sem despejar o log integral no contexto. Tema 2 (should-have).
+ *
+ * Exit codes: 0 sucesso; 12 input inválido (arquivo ausente/ilegível).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { previewArtifact, DEFAULT_MAX_BYTES } = require('../harness/preview-artifact');
+
+const EXIT_OK = 0;
+const EXIT_INPUT = 12;
+
+function tr(t, key, params, fallback) {
+  if (typeof t !== 'function') return fallback;
+  const msg = t(key, params);
+  return msg && msg !== key ? msg : fallback;
+}
+
+async function runHarnessPreview({ args, options = {}, logger, t } = {}) {
+  const log = logger || { log() {}, error() {} };
+  const file = args && args[0];
+
+  if (!file || typeof file !== 'string') {
+    log.error(tr(t, 'cli.harnessPreview.file_required', null, 'harness:preview requires a <file> path argument.'));
+    process.exitCode = EXIT_INPUT;
+    return { ok: false, exitCode: EXIT_INPUT, error: 'file_required' };
+  }
+
+  // SF-02 (decisão de design, não bug): leitor read-only operador-local. Lê
+  // qualquer path legível por design — o caso de uso é previewar logs de teste
+  // (ex.: `npm test > test.log`) que podem viver fora do cwd. Sem cruzamento de
+  // fronteira de confiança (o operador já tem acesso ao FS); por isso não há
+  // contenção de workspace aqui. Mantém-se intencionalmente irrestrito.
+  const abs = path.resolve(process.cwd(), file);
+  let content;
+  try {
+    content = fs.readFileSync(abs, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      log.error(tr(t, 'cli.harnessPreview.not_found', { path: file }, `File not found: ${file}`));
+      process.exitCode = EXIT_INPUT;
+      return { ok: false, exitCode: EXIT_INPUT, error: 'not_found' };
+    }
+    log.error(tr(t, 'cli.harnessPreview.read_error', { path: file, error: err.message }, `Could not read file: ${file} (${err.message})`));
+    process.exitCode = EXIT_INPUT;
+    return { ok: false, exitCode: EXIT_INPUT, error: 'read_error' };
+  }
+
+  let maxBytes = Number(options['max-bytes'] ?? options.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) maxBytes = DEFAULT_MAX_BYTES;
+
+  // Modo leitura: o arquivo já está persistido — não reescrever (persist:false).
+  const result = previewArtifact(content, { maxBytes, artifactPath: abs, persist: false });
+  log.log(result.preview);
+
+  return {
+    ok: true,
+    exitCode: EXIT_OK,
+    file: file.replaceAll('\\', '/'),
+    totalBytes: result.totalBytes,
+    truncated: result.truncated,
+    preview: result.preview
+  };
+}
+
+module.exports = { runHarnessPreview };