@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/lib/retro/verification-reports.js

@@ -0,0 +1,230 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { validateVerificationReport } = require('../../verification/schema');
+
+function isFileSafe(filePath) {
+  try {
+    return fs.lstatSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function listFilesSafe(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function collectReportFiles(featureDirs) {
+  const seen = new Set();
+  const files = [];
+
+  for (const featureDir of featureDirs || []) {
+    const latest = path.join(featureDir, 'verification-report.md');
+    if (isFileSafe(latest)) {
+      seen.add(latest);
+      files.push(latest);
+    }
+
+    const runsDir = path.join(featureDir, 'verification-runs');
+    for (const entry of listFilesSafe(runsDir)) {
+      if (!entry.isFile()) continue;
+      if (!/-report\.md$/i.test(entry.name)) continue;
+      const full = path.join(runsDir, entry.name);
+      if (seen.has(full)) continue;
+      seen.add(full);
+      files.push(full);
+    }
+  }
+
+  files.sort();
+  return files;
+}
+
+function extractMachineReport(content) {
+  const text = String(content || '');
+  const heading = /^##\s+Machine Report\s*$/im.exec(text);
+  if (!heading) return { ok: false, reason: 'missing_machine_report' };
+  const afterHeading = text.slice(heading.index + heading[0].length);
+  const block = afterHeading.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!block) return { ok: false, reason: 'missing_machine_report_json' };
+  try {
+    return { ok: true, report: JSON.parse(block[1]) };
+  } catch {
+    return { ok: false, reason: 'invalid_machine_report_json' };
+  }
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function reportIdentity(report) {
+  return crypto.createHash('sha1').update(stableStringify(report)).digest('hex');
+}
+
+function isLatestReportPath(filePath) {
+  return path.basename(filePath) === 'verification-report.md';
+}
+
+function shouldSkipPromotedDuplicate(seenReports, identity, filePath) {
+  const seen = seenReports.get(identity);
+  if (!seen) {
+    seenReports.set(identity, {
+      paths: [filePath],
+      skippedPromotedDuplicate: false
+    });
+    return false;
+  }
+
+  const involvesLatest = isLatestReportPath(filePath) || seen.paths.some(isLatestReportPath);
+  seen.paths.push(filePath);
+  if (involvesLatest && !seen.skippedPromotedDuplicate) {
+    seen.skippedPromotedDuplicate = true;
+    return true;
+  }
+  return false;
+}
+
+function timestampFromPath(filePath) {
+  const name = path.basename(filePath);
+  const match = name.match(/(\d{8}T\d{6}Z)/);
+  if (!match) return null;
+  return match[1].replace(
+    /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/,
+    '$1-$2-$3T$4:$5:$6Z'
+  );
+}
+
+function severityFromVerification(severity) {
+  const value = String(severity || '').toLowerCase();
+  if (value === 'blocking') return 'high';
+  if (value === 'warning') return 'medium';
+  if (value === 'info') return 'info';
+  return 'unknown';
+}
+
+function statusFromVerification(status) {
+  const value = String(status || '').toUpperCase();
+  if (value === 'CONFIRMS' || value === 'NOT_APPLICABLE') return 'fixed';
+  if (value === 'DOES_NOT_CONFIRM' || value === 'PARTIAL' || value === 'NOT_VERIFIED') return 'open';
+  return 'unknown';
+}
+
+function fileRefFromFinding(finding) {
+  if (!finding || !finding.file) return null;
+  return finding.line ? `${finding.file}:${finding.line}` : String(finding.file);
+}
+
+function titleFromFinding(report, finding) {
+  const parts = [
+    finding.kind || 'verification',
+    finding.status || report.verdict || 'UNKNOWN'
+  ];
+  if (finding.claim_id) parts.push(`claim ${finding.claim_id}`);
+  return parts.join(' ');
+}
+
+function isRetroRelevantFinding(finding) {
+  const status = String((finding && finding.status) || '').toUpperCase();
+  return status === 'DOES_NOT_CONFIRM' || status === 'PARTIAL' || status === 'NOT_VERIFIED';
+}
+
+function reportFindings({ report, slug, sourcePath, sourceDate, makeFinding }) {
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  return findings.filter(isRetroRelevantFinding).map((finding, index) => makeFinding({
+    source_type: 'verification_report',
+    feature_slug: slug,
+    finding_id: finding.id ? String(finding.id).slice(0, 80) : `VR-${index + 1}`,
+    severity: severityFromVerification(finding.severity),
+    title: titleFromFinding(report, finding),
+    file_ref: fileRefFromFinding(finding),
+    date: sourceDate,
+    status: statusFromVerification(finding.status),
+    source_path: sourcePath,
+    signature: null
+  }));
+}
+
+function readVerificationReports({ rootDir, slug, locations, makeFinding, relPath }) {
+  const warnings = [];
+  const findings = [];
+  const files = collectReportFiles(locations.featureDirs);
+  const countedFiles = [];
+  const seenReports = new Map();
+  let count = 0;
+
+  for (const full of files) {
+    const sourcePath = relPath(rootDir, full);
+    const text = readTextSafe(full);
+    if (text === null) {
+      warnings.push(`verification_report ilegível: ${sourcePath}`);
+      continue;
+    }
+
+    const parsed = extractMachineReport(text);
+    if (!parsed.ok) {
+      warnings.push(`verification_report ignorado (${parsed.reason}): ${sourcePath}`);
+      continue;
+    }
+
+    const errors = validateVerificationReport(parsed.report, {
+      slug,
+      requestedPolicy: parsed.report.policy || 'standard'
+    });
+    if (errors.length > 0) {
+      const compact = errors.map((error) => `${error.field}:${error.reason}`).join(', ');
+      warnings.push(`verification_report inválido (${compact}): ${sourcePath}`);
+      continue;
+    }
+
+    const identity = reportIdentity(parsed.report);
+    if (shouldSkipPromotedDuplicate(seenReports, identity, full)) continue;
+    countedFiles.push(full);
+    count += 1;
+    findings.push(...reportFindings({
+      report: parsed.report,
+      slug,
+      sourcePath,
+      sourceDate: timestampFromPath(full),
+      makeFinding
+    }));
+  }
+
+  return { findings, warnings, count, files: countedFiles };
+}
+
+module.exports = {
+  readVerificationReports,
+  _internal: {
+    collectReportFiles,
+    extractMachineReport,
+    reportIdentity,
+    shouldSkipPromotedDuplicate,
+    severityFromVerification,
+    statusFromVerification,
+    titleFromFinding,
+    isRetroRelevantFinding
+  }
+};

package/src/parser.js

@@ -38,6 +38,12 @@ function parseArgv(argv) {
         'flatten', 'no-index',
         // harness:validate — pure boolean; `--no-diff .` must not swallow the path.
         'no-diff',
+        // audit:code / harness:check — pure booleans; `--changed .` / `--strict .`
+        // must not swallow the trailing path positional.
+        'changed', 'strict',
+        // verify:artifact — pure booleans; `--advisory .` / `--no-build .` must
+        // not swallow the path positional.
+        'advisory', 'no-build',
         // `--resume` alone means "resume last"; `--resume=<id>` carries a value
         // and is handled by the `=` branch above. Without this entry, `--resume`
         // followed by `--tool=claude` would swallow the next token as its value.

package/src/preflight-engine.js

@@ -257,11 +257,11 @@ async function scanArtifacts(targetDir, slug) {
     : [path.join(dir, 'readiness.md')];
 
   const results = {
-    project_context: await check('project.context', path.join(dir, 'project.context.md')),
-    prd: slug ? await check('prd', path.join(dir, `prd-${slug}.md`)) : { exists: false },
-    sheldon_enrichment: slug ? await check('sheldon', path.join(dir, `sheldon-enrichment-${slug}.md`)) : { exists: false },
-    sheldon_validation: slug ? await check('sheldon-validation', path.join(dir, `sheldon-validation-${slug}.md`)) : { exists: false },
-    requirements: slug ? await check('requirements', path.join(dir, `requirements-${slug}.md`)) : { exists: false },
+    project_context: await check('project.context', path.join(dir, 'project.context.md')),
+    prd: slug ? await check('prd', path.join(dir, `prd-${slug}.md`)) : { exists: false },
+    sheldon_enrichment: slug ? await check('sheldon', path.join(dir, `sheldon-enrichment-${slug}.md`)) : { exists: false },
+    sheldon_validation: slug ? await check('sheldon-validation', path.join(dir, `sheldon-validation-${slug}.md`)) : { exists: false },
+    requirements: slug ? await check('requirements', path.join(dir, `requirements-${slug}.md`)) : { exists: false },
     spec: slug ? await check('spec', path.join(dir, `spec-${slug}.md`)) : await check('spec', path.join(dir, 'spec.md')),
     architecture: await check('architecture', path.join(dir, 'architecture.md')),
     design_doc: await checkFirst('design-doc', designDocCandidates),
@@ -480,11 +480,11 @@ function buildContextPackage(agent, slug, classification, artifacts, devState, m
     const downstreamAgents = ['discovery-design-doc', 'pm', 'orchestrator', 'dev', 'deyvin', 'qa'];
     const shouldCarryFullFeatureContext = downstreamAgents.includes(agent);
 
-    if (shouldCarryFullFeatureContext && artifacts.prd.exists) pkg.push(artifacts.prd.path);
-    if (shouldCarryFullFeatureContext && artifacts.sheldon_enrichment.exists) pkg.push(artifacts.sheldon_enrichment.path);
-    if (shouldCarryFullFeatureContext && artifacts.sheldon_validation && artifacts.sheldon_validation.exists) {
-      pkg.push(artifacts.sheldon_validation.path);
-    }
+    if (shouldCarryFullFeatureContext && artifacts.prd.exists) pkg.push(artifacts.prd.path);
+    if (shouldCarryFullFeatureContext && artifacts.sheldon_enrichment.exists) pkg.push(artifacts.sheldon_enrichment.path);
+    if (shouldCarryFullFeatureContext && artifacts.sheldon_validation && artifacts.sheldon_validation.exists) {
+      pkg.push(artifacts.sheldon_validation.path);
+    }
     if ((shouldCarryFullFeatureContext || ['analyst', 'architect'].includes(agent)) && artifacts.requirements.exists) {
       pkg.push(artifacts.requirements.path);
     }
@@ -685,10 +685,10 @@ function evaluateReadiness(artifacts, phaseGates, classification, agent, devStat
     if (!artifacts.spec.exists) blockers.push('spec file missing');
     if (classification && classification !== 'MICRO') {
       if (!designDoc.exists) {
-        blockers.push('design-doc.md missing — @discovery-design-doc must run before implementation');
+        blockers.push('design-doc.md missing — @architect (merged mode) or @sheldon must produce it before implementation');
       }
       if (!readiness.exists) {
-        blockers.push('readiness.md missing — @discovery-design-doc must run before implementation');
+        blockers.push('readiness.md missing — @architect (merged mode) or @sheldon must produce it before implementation');
       }
     }
     if (classification === 'MEDIUM') {

package/src/runtime-store.js

@@ -1567,15 +1567,19 @@ function startRun(db, options) {
     finished_at: status === 'completed' || status === 'failed' ? now : null
   });
 
-  appendRunEvent(db, {
-    runKey,
-    eventType: String(options.eventType || 'start'),
-    phase: options.phase || 'run',
-    status,
-    message: String(options.message || options.title || 'Agent started'),
-    payload: options.payload,
-    createdAt: now
-  });
+  appendRunEvent(db, {
+    runKey,
+    eventType: String(options.eventType || 'start'),
+    phase: options.phase || 'run',
+    status,
+    toolName: options.toolName,
+    message: String(options.message || options.title || 'Agent started'),
+    payload: options.payload,
+    verdict: options.verdict,
+    tokenCount: options.tokenCount,
+    progressPct: options.progressPct,
+    createdAt: now
+  });
 
   return runKey;
 }

package/src/verification/evidence-bundle.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { resolveInsideRoot } = require('./path-policy');
+const { createCounter, redactText, redactJson, totalRedactions } = require('./redaction');
+
+const ARTIFACT_PREVIEW_CHARS = 700;
+const ARTIFACT_PREVIEW_TOTAL_CHARS = 8000;
+const ARTIFACT_SUMMARY_LIMIT = 60;
+
+function runGit(rootDir, args) {
+  try {
+    return {
+      ok: true,
+      output: execFileSync('git', args, {
+        cwd: rootDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+      }).trim()
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      output: '',
+      error: error.message
+    };
+  }
+}
+
+async function fileExists(rootDir, relPath) {
+  const safe = resolveInsideRoot(rootDir, relPath);
+  if (!safe.ok) return false;
+  try {
+    const stat = await fs.stat(safe.path);
+    return stat.isFile() || stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function fileStat(rootDir, relPath) {
+  const safe = resolveInsideRoot(rootDir, relPath);
+  if (!safe.ok) return { ok: false, reason: safe.reason };
+  try {
+    const stat = await fs.stat(safe.path);
+    return { ok: true, path: safe.path, stat };
+  } catch {
+    return { ok: false, reason: 'not_found' };
+  }
+}
+
+function evidencePathsFromLedger(ledger) {
+  if (!ledger || !Array.isArray(ledger.claims)) return [];
+  const paths = [];
+  for (const claim of ledger.claims) {
+    if (!claim || !Array.isArray(claim.evidence)) continue;
+    for (const evidence of claim.evidence) {
+      if (evidence && evidence.path) paths.push(evidence.path);
+    }
+  }
+  return [...new Set(paths)];
+}
+
+async function knownChecks(rootDir, slug, ledger, policy = 'standard') {
+  const checks = [];
+  const addCheck = (candidate) => {
+    if (!candidate || !candidate.command) return;
+    const existing = checks.find((check) => check.command === candidate.command);
+    if (!existing) {
+      checks.push(candidate);
+      return;
+    }
+    existing.required = Boolean(existing.required || candidate.required);
+    existing.source = existing.source === candidate.source
+      ? existing.source
+      : `${existing.source},${candidate.source}`;
+    existing.last_status = candidate.last_status || existing.last_status || null;
+  };
+
+  if (await fileExists(rootDir, 'package.json')) {
+    addCheck({ command: 'npm test', source: 'package.json', required: false });
+  }
+  if (await fileExists(rootDir, 'scripts/check-js.js')) {
+    addCheck({ command: 'node scripts/check-js.js', source: 'scripts/check-js.js', required: false });
+  }
+  if (await fileExists(rootDir, `.aioson/context/prd-${slug}.md`)) {
+    const strictFlag = policy === 'strict' ? ' --strict' : '';
+    addCheck({ command: `aioson prototype:check . --feature=${slug}${strictFlag}`, source: 'prototype_contract', required: false });
+  }
+  if (await fileExists(rootDir, `.aioson/plans/${slug}/harness-contract.json`)) {
+    addCheck({ command: `aioson harness:check . --slug=${slug}`, source: 'harness_contract', required: false });
+  }
+  if (ledger && Array.isArray(ledger.verification_commands)) {
+    for (const item of ledger.verification_commands) {
+      if (item && item.command) {
+        addCheck({
+          command: item.command,
+          source: 'ledger',
+          required: Boolean(item.required),
+          last_status: item.last_status || null
+        });
+      }
+    }
+  }
+  return checks;
+}
+
+function commandPlan(commands) {
+  return (commands || []).map((command, index) => ({
+    order: index + 1,
+    command: command.command,
+    required: Boolean(command.required),
+    source: command.source || 'unknown',
+    last_status: command.last_status || null,
+    run_by: 'developer_or_clean_auditor',
+    expectation: command.required ? 'must be run or explicitly justified' : 'run when relevant to touched surface'
+  }));
+}
+
+function dirtyWorktree(statusOutput) {
+  return Boolean(String(statusOutput || '').trim());
+}
+
+function artifactCanPreview(relPath) {
+  return /\.(md|txt|json|js|ts|tsx|jsx|html|css|yaml|yml)$/i.test(String(relPath || ''));
+}
+
+async function artifactSummaries(rootDir, artifacts, redactionCounter) {
+  const summaries = [];
+  let usedPreviewChars = 0;
+
+  for (const artifact of (artifacts || []).slice(0, ARTIFACT_SUMMARY_LIMIT)) {
+    const relPath = artifact.path;
+    const stat = await fileStat(rootDir, relPath);
+    const summary = {
+      type: artifact.type,
+      role: artifact.role,
+      path: relPath,
+      exists: stat.ok,
+      size_bytes: stat.ok ? stat.stat.size : null
+    };
+
+    if (!stat.ok) {
+      summary.omitted_reason = stat.reason;
+      summaries.push(summary);
+      continue;
+    }
+    if (!stat.stat.isFile()) {
+      summary.omitted_reason = 'not_file';
+      summaries.push(summary);
+      continue;
+    }
+    if (!artifactCanPreview(relPath)) {
+      summary.omitted_reason = 'unsupported_preview_type';
+      summaries.push(summary);
+      continue;
+    }
+    if (usedPreviewChars >= ARTIFACT_PREVIEW_TOTAL_CHARS) {
+      summary.omitted_reason = 'preview_budget_exhausted';
+      summaries.push(summary);
+      continue;
+    }
+
+    const remaining = ARTIFACT_PREVIEW_TOTAL_CHARS - usedPreviewChars;
+    const limit = Math.min(ARTIFACT_PREVIEW_CHARS, remaining);
+    const handle = await fs.open(stat.path, 'r');
+    try {
+      const buffer = Buffer.alloc(limit);
+      const { bytesRead } = await handle.read(buffer, 0, limit, 0);
+      const preview = buffer.subarray(0, bytesRead).toString('utf8');
+      usedPreviewChars += preview.length;
+      summary.preview = redactText(preview, redactionCounter);
+      summary.preview_truncated = stat.stat.size > bytesRead;
+    } finally {
+      await handle.close();
+    }
+    summaries.push(summary);
+  }
+
+  if ((artifacts || []).length > ARTIFACT_SUMMARY_LIMIT) {
+    summaries.push({
+      type: 'budget_notice',
+      role: 'artifact_summary',
+      path: null,
+      exists: false,
+      omitted_reason: `artifact_summary_limit_${ARTIFACT_SUMMARY_LIMIT}`,
+      omitted_count: artifacts.length - ARTIFACT_SUMMARY_LIMIT
+    });
+  }
+
+  return summaries;
+}
+
+async function buildEvidenceBundle(rootDir, slug, ledger, sourceArtifacts, policy) {
+  const redactionCounter = createCounter();
+  const branch = runGit(rootDir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const status = runGit(rootDir, ['status', '--short']);
+  const diffStat = runGit(rootDir, ['diff', '--stat']);
+  const artifactPaths = (sourceArtifacts || []).map((artifact) => artifact.path);
+  const evidencePaths = evidencePathsFromLedger(ledger);
+  const touchedPaths = [...new Set([...artifactPaths, ...evidencePaths])].filter(Boolean).slice(0, 25);
+  const recentCommits = touchedPaths.length > 0
+    ? runGit(rootDir, ['log', '--oneline', '-n', '5', '--', ...touchedPaths])
+    : { ok: true, output: '' };
+
+  const verificationCommands = redactJson(await knownChecks(rootDir, slug, ledger, policy), redactionCounter);
+  const sanitizedLedgerClaims = redactJson(ledger && Array.isArray(ledger.claims) ? ledger.claims : [], redactionCounter);
+  const sanitizedKnownGaps = redactJson(ledger && Array.isArray(ledger.known_gaps) ? ledger.known_gaps : [], redactionCounter);
+  const summaries = await artifactSummaries(rootDir, sourceArtifacts || [], redactionCounter);
+  const git = {
+    branch: branch.ok ? redactText(branch.output, redactionCounter) : null,
+    branch_error: branch.ok ? null : branch.error,
+    status: status.ok ? redactText(status.output, redactionCounter) : null,
+    dirty_worktree: status.ok ? dirtyWorktree(status.output) : null,
+    status_error: status.ok ? null : status.error,
+    diff_stat: diffStat.ok ? redactText(diffStat.output, redactionCounter) : null,
+    diff_stat_error: diffStat.ok ? null : diffStat.error,
+    recent_commits: recentCommits.ok ? redactText(recentCommits.output, redactionCounter) : null,
+    recent_commits_error: recentCommits.ok ? null : recentCommits.error
+  };
+
+  return {
+    feature_slug: slug,
+    policy,
+    git,
+    source_artifacts: sourceArtifacts || [],
+    artifact_summaries: summaries,
+    ledger_claims: sanitizedLedgerClaims,
+    known_gaps: sanitizedKnownGaps,
+    verification_commands: verificationCommands,
+    command_plan: commandPlan(verificationCommands),
+    redactions: {
+      ...redactionCounter,
+      total: totalRedactions(redactionCounter)
+    },
+    preview_budget: {
+      artifact_preview_chars: ARTIFACT_PREVIEW_CHARS,
+      artifact_preview_total_chars: ARTIFACT_PREVIEW_TOTAL_CHARS,
+      artifact_summary_limit: ARTIFACT_SUMMARY_LIMIT
+    },
+    generated_at: new Date().toISOString(),
+    project_root: path.resolve(rootDir)
+  };
+}
+
+module.exports = {
+  buildEvidenceBundle
+};