@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/harness/detect-runtime-feature.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Deterministically detect whether a feature ships a runtime surface, using
+ * ONLY signals the framework can locate reliably:
+ *
+ *   - a prototype-manifest (`.aioson/briefings/{slug}/prototype-manifest.md`)
+ *     ⇒ a clickable prototype whose Core interactions must work on the real
+ *     stack (the flow-deck failure class);
+ *   - a migration / Prisma path among `progress.completed_steps` ⇒ a DB feature
+ *     whose migrations must actually apply.
+ *
+ * The Play `manifest.json` `has_api` flag lives in the TARGET app and is not
+ * reliably locatable from the framework, so that trigger stays with the LLM
+ * @validator (harness-contract.md §2c). A `false` result here means "no reliable
+ * runtime signal", NOT "proven non-runtime" — callers treat it conservatively.
+ */
+
+// Path segments / extensions that reliably indicate database migration work.
+const MIGRATION_HINTS = [
+  /(?:^|[\\/])migrations?(?:[\\/]|$)/i,
+  /(?:^|[\\/])prisma(?:[\\/]|$)/i,
+  /\.prisma$/i,
+  /(?:^|[\\/])migrate(?:[\\/]|$)/i
+];
+
+function looksLikeMigration(step) {
+  const value = String(step || '');
+  return MIGRATION_HINTS.some((re) => re.test(value));
+}
+
+/**
+ * The set of paths git considers changed in the working tree: unstaged,
+ * staged, and untracked-but-not-ignored. Read-only and best-effort — a
+ * non-git project (or any git failure) yields `[]`, so callers degrade to
+ * prototype/progress-based detection. Lives here (not only in the gate) so
+ * the standalone `aioson harness:check` detects the same migration surface
+ * the workflow finalize / feature:close gate does.
+ */
+function gitChangedFiles(targetDir) {
+  const files = new Set();
+  const commands = [
+    ['diff', '--name-only'],
+    ['diff', '--name-only', '--cached'],
+    ['ls-files', '--others', '--exclude-standard']
+  ];
+  for (const args of commands) {
+    try {
+      const output = execFileSync('git', args, {
+        cwd: targetDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      });
+      for (const line of output.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed) files.add(trimmed);
+      }
+    } catch {
+      // Non-git projects still get prototype/progress based detection.
+    }
+  }
+  return [...files];
+}
+
+function detectRuntimeFeature(targetDir, slug, options = {}) {
+  const signals = [];
+
+  if (slug) {
+    try {
+      const protoManifest = path.join(
+        targetDir, '.aioson', 'briefings', String(slug), 'prototype-manifest.md'
+      );
+      if (fs.existsSync(protoManifest)) signals.push('prototype-manifest');
+    } catch {
+      /* ignore — detection is best-effort */
+    }
+  }
+
+  const completedSteps = Array.isArray(options.completedSteps) ? options.completedSteps : [];
+  const changedFiles = Array.isArray(options.changedFiles) ? options.changedFiles : [];
+  if ([...completedSteps, ...changedFiles].some(looksLikeMigration)) signals.push('migrations');
+
+  return { isRuntimeFeature: signals.length > 0, signals };
+}
+
+module.exports = { detectRuntimeFeature, looksLikeMigration, gitChangedFiles };

package/src/harness/static-criteria.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * Static-pattern criteria (SG-* — Static Gate) — the build-independent half of
+ * the harness contract.
+ *
+ * Where an RG-* criterion EXECUTES a command (a working build, migrations, a
+ * booted app — expensive, run once at the last gate per A5), an SG-* criterion
+ * proves a claim by READING the changed files: a required pattern is present
+ * (the code was actually written / wired) and a forbidden pattern is absent (no
+ * placeholder, stub or anti-pattern snuck in). Pure fs + RegExp +
+ * `node --check`/`JSON.parse` — no shell, no build — so it costs ~milliseconds
+ * and runs at EVERY gate (@dev-done, @qa-done; advisory in per-phase
+ * `harness:check`), cross-platform by construction.
+ *
+ * Two build-free pattern checks over the declared files:
+ *   must_match      OR-across-files  — each pattern must appear in >= 1 file
+ *   must_not_match  absent-in-all    — no pattern may appear in ANY file
+ * plus a post-write parse-check (the `parseable` gate) to catch a truncated or
+ * corrupted write before it reaches a human.
+ *
+ * An invalid regex degrades to a literal substring test instead of throwing — a
+ * contract typo never crashes the gate, it just matches literally.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/** A criterion is static when it carries a non-empty must_match or must_not_match. */
+function isStaticCriterion(criterion) {
+  if (!criterion || typeof criterion !== 'object') return false;
+  return (
+    (Array.isArray(criterion.must_match) && criterion.must_match.length > 0) ||
+    (Array.isArray(criterion.must_not_match) && criterion.must_not_match.length > 0)
+  );
+}
+
+/**
+ * Compile a pattern to a tester: a real RegExp when the source is valid, else a
+ * literal-substring test (a contract typo matches literally, never throws).
+ */
+function patternTester(pattern) {
+  const src = String(pattern);
+  try {
+    const re = new RegExp(src);
+    return (text) => re.test(text);
+  } catch {
+    return (text) => text.includes(src);
+  }
+}
+
+/**
+ * Parse-check a file by extension. Returns { checked, ok, reason }.
+ * `checked: false` means no stdlib parser applies to this extension (skipped,
+ * like the harness skips .ts/.md) — never a failure.
+ */
+function parseCheckFile(absPath) {
+  const ext = path.extname(absPath).toLowerCase();
+  if (ext === '.json') {
+    let content;
+    try {
+      content = fs.readFileSync(absPath, 'utf8');
+    } catch (err) {
+      return { checked: true, ok: false, reason: `cannot read file (${err.code || err.message})` };
+    }
+    try {
+      JSON.parse(content);
+      return { checked: true, ok: true, reason: null };
+    } catch (err) {
+      return { checked: true, ok: false, reason: `invalid JSON (${err.message})` };
+    }
+  }
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+    // `node --check` is the syntax parser shipped with the runtime AIOSON runs
+    // on — guaranteed present, cross-platform, no extra dependency.
+    const res = spawnSync(process.execPath, ['--check', absPath], { encoding: 'utf8', timeout: 10000 });
+    if (res.status === 0) return { checked: true, ok: true, reason: null };
+    const detail = String(res.stderr || res.stdout || '')
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => l) || `exit ${res.status}`;
+    return { checked: true, ok: false, reason: `syntax error (${detail})` };
+  }
+  // No stdlib parser for this extension (.ts/.tsx/.md/...): skip, like the harness.
+  return { checked: false, ok: true, reason: null };
+}
+
+/**
+ * Evaluate one static criterion against the working tree.
+ *
+ * @param {object} criterion — a criteria[] entry with must_match/must_not_match/files
+ * @param {string} cwd — project root the relative file paths resolve against
+ * @returns {{ id, kind:'static', ok, files, missing_files, must_match_misses,
+ *             must_not_match_hits, parse_failures, detail }}
+ */
+function evaluateStaticCriterion(criterion, cwd) {
+  const id = criterion.id;
+  const files = Array.isArray(criterion.files) ? criterion.files.slice() : [];
+  const mustMatch = Array.isArray(criterion.must_match) ? criterion.must_match : [];
+  const mustNotMatch = Array.isArray(criterion.must_not_match) ? criterion.must_not_match : [];
+
+  const resolved = files.map((rel) => ({ rel, abs: path.resolve(cwd, rel) }));
+  const missingFiles = resolved.filter((f) => !fs.existsSync(f.abs)).map((f) => f.rel);
+
+  // Read each existing file once, and parse-check it for truncation/corruption.
+  const contents = new Map();
+  const parseFailures = [];
+  for (const f of resolved) {
+    if (!fs.existsSync(f.abs)) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(f.abs, 'utf8');
+    } catch {
+      // Unreadable file is reported by the parse-check below.
+    }
+    contents.set(f.rel, text);
+    const pc = parseCheckFile(f.abs);
+    if (pc.checked && !pc.ok) parseFailures.push(`${f.rel}: ${pc.reason}`);
+  }
+
+  // must_match — OR across files: each pattern must appear in >= 1 file.
+  const mustMatchMisses = [];
+  for (const pat of mustMatch) {
+    const test = patternTester(pat);
+    const hit = [...contents.values()].some((text) => test(text));
+    if (!hit) mustMatchMisses.push(String(pat));
+  }
+
+  // must_not_match — absent in all: no pattern may appear in ANY file.
+  const mustNotMatchHits = [];
+  for (const pat of mustNotMatch) {
+    const test = patternTester(pat);
+    for (const [rel, text] of contents) {
+      if (test(text)) mustNotMatchHits.push({ pattern: String(pat), file: rel });
+    }
+  }
+
+  const reasons = [];
+  if (missingFiles.length) reasons.push(`missing files: ${missingFiles.join(', ')}`);
+  if (parseFailures.length) reasons.push(`parse: ${parseFailures.join('; ')}`);
+  if (mustMatchMisses.length) reasons.push(`must_match not found: ${mustMatchMisses.map((p) => `/${p}/`).join(', ')}`);
+  if (mustNotMatchHits.length) {
+    reasons.push(`must_not_match present: ${mustNotMatchHits.map((h) => `/${h.pattern}/ in ${h.file}`).join(', ')}`);
+  }
+
+  const ok =
+    missingFiles.length === 0 &&
+    parseFailures.length === 0 &&
+    mustMatchMisses.length === 0 &&
+    mustNotMatchHits.length === 0;
+
+  return {
+    id,
+    kind: 'static',
+    ok,
+    files,
+    missing_files: missingFiles,
+    must_match_misses: mustMatchMisses,
+    must_not_match_hits: mustNotMatchHits,
+    parse_failures: parseFailures,
+    detail: ok ? null : reasons.join(' | ')
+  };
+}
+
+/**
+ * Evaluate every static criterion in a contract's criteria[]. Runtime criteria
+ * (those with a `verification` command) are ignored here.
+ *
+ * @param {object} params
+ * @param {Array} params.criteria — criteria[] from the contract
+ * @param {string} params.cwd — project root
+ * @returns {{ checks: Array, ok: boolean, total: number, failed: number }}
+ */
+function evaluateStaticCriteria({ criteria = [], cwd } = {}) {
+  const root = cwd || process.cwd();
+  const checks = [];
+  for (const criterion of Array.isArray(criteria) ? criteria : []) {
+    if (!isStaticCriterion(criterion)) continue;
+    checks.push(evaluateStaticCriterion(criterion, root));
+  }
+  const failed = checks.filter((c) => !c.ok).length;
+  return { checks, ok: failed === 0, total: checks.length, failed };
+}
+
+module.exports = {
+  isStaticCriterion,
+  patternTester,
+  parseCheckFile,
+  evaluateStaticCriterion,
+  evaluateStaticCriteria
+};

package/src/i18n/messages/en.js

@@ -13,10 +13,10 @@ module.exports = {
     help_setup:
       'aioson setup [path] [--defaults] [--framework=<name>] [--lang=<bcp47-tag>] [--project-name=<name>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=en]',
     help_update: 'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=en]',
-    help_info: 'aioson info [path] [--json] [--locale=en]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=en]',
-    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=en]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=en]',
+    help_info: 'aioson info [path] [--json] [--locale=en]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=en]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=en]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=en]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=en]',
@@ -133,6 +133,8 @@ module.exports = {
       'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=en]',
     help_review_cycle:
       'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=en]',
+    help_review_feature:
+      'aioson review:feature [path] [--feature=<slug>] [--scope=<target>] [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json] [--locale=en]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=en]',
     help_parallel_doctor:
@@ -169,6 +171,8 @@ module.exports = {
       'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=en]',
     help_harness_preview:
       'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=en]',
+    help_verification_plan:
+      'aioson verification:plan [path] [--feature=<slug>] [--trigger=per-phase|end-of-feature|sensitive-surface] [--host=claude|codex|opencode] [--classification=MICRO|SMALL|MEDIUM] [--sensitive] [--json] [--locale=en]',
     harnessRetro: {
       need_target: 'harness:retro requires --feature=<slug> or --last=<N>.',
       invalid_slug: 'Invalid slug: {slug} (must match ^[a-z0-9][a-z0-9-]*$).',

package/src/i18n/messages/es.js

@@ -14,10 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nombre>] [--lang=<bcp47-tag>] [--project-name=<nombre>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=es]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=es]',
-    help_info: 'aioson info [path] [--json] [--locale=es]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=es]',
-    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=es]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=es]',
+    help_info: 'aioson info [path] [--json] [--locale=es]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=es]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=es]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=es]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=es]',
@@ -123,6 +123,8 @@ module.exports = {
       'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=es]',
     help_review_cycle:
       'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=es]',
+    help_review_feature:
+      'aioson review:feature [path] [--feature=<slug>] [--scope=<target>] [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json] [--locale=es]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=es]',
     help_parallel_doctor:
@@ -155,6 +157,8 @@ module.exports = {
       'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=es]',
     help_harness_preview:
       'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=es]',
+    help_verification_plan:
+      'aioson verification:plan [path] [--feature=<slug>] [--trigger=per-phase|end-of-feature|sensitive-surface] [--host=claude|codex|opencode] [--classification=MICRO|SMALL|MEDIUM] [--sensitive] [--json] [--locale=es]',
     harnessRetro: {
       need_target: 'harness:retro requiere --feature=<slug> o --last=<N>.',
       invalid_slug: 'Slug inválido: {slug} (debe cumplir ^[a-z0-9][a-z0-9-]*$).',

package/src/i18n/messages/fr.js

@@ -14,10 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nom>] [--lang=<bcp47-tag>] [--project-name=<nom>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=fr]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=fr]',
-    help_info: 'aioson info [path] [--json] [--locale=fr]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=fr]',
-    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=fr]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=fr]',
+    help_info: 'aioson info [path] [--json] [--locale=fr]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=fr]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=fr]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=fr]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
@@ -123,6 +123,8 @@ module.exports = {
       'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=fr]',
     help_review_cycle:
       'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=fr]',
+    help_review_feature:
+      'aioson review:feature [path] [--feature=<slug>] [--scope=<target>] [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json] [--locale=fr]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=fr]',
     help_parallel_doctor:
@@ -155,6 +157,8 @@ module.exports = {
       'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=fr]',
     help_harness_preview:
       'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=fr]',
+    help_verification_plan:
+      'aioson verification:plan [path] [--feature=<slug>] [--trigger=per-phase|end-of-feature|sensitive-surface] [--host=claude|codex|opencode] [--classification=MICRO|SMALL|MEDIUM] [--sensitive] [--json] [--locale=fr]',
     harnessRetro: {
       need_target: 'harness:retro requiert --feature=<slug> ou --last=<N>.',
       invalid_slug: 'Slug invalide : {slug} (doit correspondre à ^[a-z0-9][a-z0-9-]*$).',

package/src/i18n/messages/pt-BR.js

@@ -14,10 +14,10 @@ module.exports = {
       'aioson setup [path] [--defaults] [--framework=<nome>] [--lang=<bcp47-tag>] [--project-name=<nome>] [--force] [--dry-run] [--tool=codex|claude|opencode] [--locale=pt-BR]',
     help_update:
       'aioson update [path] [--dry-run] [--lang=<bcp47-tag>] [--locale=pt-BR]',
-    help_info: 'aioson info [path] [--json] [--locale=pt-BR]',
-    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=pt-BR]',
-    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=pt-BR]',
-    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=pt-BR]',
+    help_info: 'aioson info [path] [--json] [--locale=pt-BR]',
+    help_doctor: 'aioson doctor [path] [--fix] [--dry-run] [--json] [--locale=pt-BR]',
+    help_hygiene_scan: 'aioson hygiene:scan [path] [--json] [--locale=pt-BR]',
+    help_i18n_add: 'aioson i18n:add <locale> [--force] [--dry-run] [--locale=pt-BR]',
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
@@ -135,6 +135,8 @@ module.exports = {
       'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
     help_review_cycle:
       'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=pt-BR]',
+    help_review_feature:
+      'aioson review:feature [path] [--feature=<slug>] [--scope=<target>] [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json] [--locale=pt-BR]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=pt-BR]',
     help_parallel_doctor:
@@ -171,6 +173,8 @@ module.exports = {
       'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=pt-BR]',
     help_harness_preview:
       'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=pt-BR]',
+    help_verification_plan:
+      'aioson verification:plan [path] [--feature=<slug>] [--trigger=per-phase|end-of-feature|sensitive-surface] [--host=claude|codex|opencode] [--classification=MICRO|SMALL|MEDIUM] [--sensitive] [--json] [--locale=pt-BR]',
     harnessRetro: {
       need_target: 'harness:retro requer --feature=<slug> ou --last=<N>.',
       invalid_slug: 'Slug inválido: {slug} (deve casar ^[a-z0-9][a-z0-9-]*$).',

package/src/install-wizard.js

@@ -3,17 +3,17 @@
 const readline = require('node:readline');
 const { getCliVersionSync } = require('./version');
 
-const TOOLS = [
-  { id: 'claude',    label: 'Claude Code',    desc: 'Slash commands, CLAUDE.md, .claude/' },
-  { id: 'codex',    label: 'Codex (OpenAI)', desc: 'AGENTS.md protocol' },
-  { id: 'opencode', label: 'OpenCode',       desc: 'OPENCODE.md protocol' }
-];
+const TOOLS = [
+  { id: 'claude',    label: 'Claude Code',    desc: 'Slash commands, CLAUDE.md, .claude/' },
+  { id: 'codex',    label: 'Codex (OpenAI)', desc: 'AGENTS.md protocol' },
+  { id: 'opencode', label: 'OpenCode',       desc: 'OPENCODE.md protocol' }
+];
 
 const USES = [
   {
     id: 'development',
     label: 'Development',
-    desc: 'Agent workflow: setup → analyst → scope-check → architect → dev → qa',
+    desc: 'Agent workflow: setup → analyst → scope-check → architect → dev → qa',
     locked: true
   },
   {
@@ -111,7 +111,7 @@ function renderScreen1(cursor, selected, warn, stdout) {
     const tool    = TOOLS[i];
     const pointer = i === cursor ? '►' : ' ';
     const check   = selected.has(tool.id) ? '✓' : ' ';
-    stdout.write(`  ${pointer} [${check}] ${tool.label.padEnd(20)} ${tool.desc}\n`);
+    stdout.write(`  ${pointer} [${check}] ${tool.label.padEnd(20)} ${tool.desc}\n`);
   }
   if (warn) stdout.write('\n  ⚠  Select at least one tool to continue.\n');
   stdout.write('\n');
@@ -161,7 +161,7 @@ function renderScreen4(cursor, stdout) {
 }
 
 function renderConfirm(tools, uses, design, locale, existingProfile, t, stdout) {
-  const TOOL_NAMES = { claude: 'Claude Code', codex: 'Codex', opencode: 'OpenCode' };
+  const TOOL_NAMES = { claude: 'Claude Code', codex: 'Codex', opencode: 'OpenCode' };
   const toolNames  = tools.map(id => TOOL_NAMES[id] || id).join(', ');
   const modeLabel  = uses.includes('squads') ? 'Development + Squads' : 'Development';
   // design can be string (single/id/all) or string[] (multiple)

package/src/installer.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { MANAGED_FILES } = require('./constants');
-const { getCliVersion } = require('./version');
+const { getCliVersion, getGitBuildInfoSync } = require('./version');
 const { exists, ensureDir, copyFileWithDir, nowStamp, toRelativeSafe } = require('./utils');
 const { ensureProjectRuntime } = require('./execution-gateway');
 const { shouldIncludeForProfile } = require('./install-profile');
@@ -34,10 +34,10 @@ const GITIGNORE_POLICY_LINES = [
   '# AIOSON — keep shared project memory and tool contracts',
   '!AGENTS.md',
   '!CLAUDE.md',
-  '!OPENCODE.md',
-  '!.claude/',
-  '!.claude/**',
-  '!.aioson/',
+  '!OPENCODE.md',
+  '!.claude/',
+  '!.claude/**',
+  '!.aioson/',
   '!.aioson/**',
   '# AIOSON — managed framework files (do not commit)',
   '.aioson/config.md',
@@ -238,10 +238,17 @@ async function writeInstallMetadata(targetDir, action, frameworkDetection, insta
   }
 
   const version = await getCliVersion();
+  // Stamp the exact framework commit when installing/updating from a git checkout
+  // (e.g. an `npm link`ed dev framework). With a plain npm install this is null —
+  // template_version alone identifies it. Lets a project record precisely which
+  // commit it was last updated from.
+  const gitInfo = getGitBuildInfoSync();
   const data = {
     ...existing,
     managed_by: 'aioson',
     template_version: version,
+    template_git_sha: gitInfo ? gitInfo.sha : null,
+    template_git_date: gitInfo ? gitInfo.date : null,
     last_action: action,
     last_action_at: new Date().toISOString(),
     framework_detected: frameworkDetection || existing.framework_detected || null,
@@ -343,7 +350,7 @@ async function installTemplate(targetDir, options = {}) {
     const dest = path.join(targetDir, rel);
     const destExists = await exists(dest);
 
-    // Gateway pointer files (CLAUDE.md, AGENTS.md, OPENCODE.md)
+    // Gateway pointer files (CLAUDE.md, AGENTS.md, OPENCODE.md)
     // get block-merged so that an existing project-authored file keeps its content
     // and only the AIOSON-managed block is created or refreshed in place.
     if (isGatewayPointerPath(rel)) {

package/src/lib/retro/retro-render.js

@@ -9,7 +9,16 @@
  * fixo (pt-BR, conforme §3.1); `--locale` afeta só as mensagens de stdout.
  */
 
-const SOURCE_ORDER = ['qa_reports', 'corrections', 'dossier_trail', 'execution_events', 'attempts', 'failure_signatures', 'devlogs'];
+const SOURCE_ORDER = [
+  'qa_reports',
+  'verification_reports',
+  'corrections',
+  'dossier_trail',
+  'execution_events',
+  'attempts',
+  'failure_signatures',
+  'devlogs'
+];
 
 // Defesa em profundidade (SF-01): o dossiê vira contexto do @sheldon. Texto livre
 // minerado (títulos) é apresentado como DADO inline, nunca como estrutura Markdown

package/src/lib/retro/retro-sources.js

@@ -13,9 +13,10 @@
  * módulo NUNCA escreve no filesystem.
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { readVerificationReports } = require('./verification-reports');
 
 const FINDING_ID_RE = /\b([A-Z]{1,2}-\d{1,2})\b/;
 const TRAIL_ENTRY_RE = /^\*\*([^*]+)\*\*\s*\|\s*@?([\w.-]+)\s*\|\s*_([^_]+)_\s*$/;
@@ -445,11 +446,16 @@ function resolveLocations(targetDir, ctxDir, slug) {
     path.join(doneRoot, 'plans')
   ].filter(dirExists);
 
-  const dossierCandidates = [
-    path.join(ctxDir, 'features', slug, 'dossier.md'),
-    path.join(doneRoot, 'features', slug, 'dossier.md'),
-    path.join(doneRoot, 'dossier.md')
-  ];
+  const dossierCandidates = [
+    path.join(ctxDir, 'features', slug, 'dossier.md'),
+    path.join(doneRoot, 'features', slug, 'dossier.md'),
+    path.join(doneRoot, 'dossier.md')
+  ];
+  const featureDirs = [
+    path.join(ctxDir, 'features', slug),
+    path.join(doneRoot, 'features', slug),
+    doneRoot
+  ].filter(dirExists);
   // SF-02: lstat (não statSync) para NÃO seguir symlink — consistente com os
   // demais readers, que pulam symlinks via Dirent.isFile(). Um dossier.md que
   // seja um symlink apontando para fora do workspace é ignorado, não seguido.
@@ -457,8 +463,8 @@ function resolveLocations(targetDir, ctxDir, slug) {
     try { return fs.lstatSync(p).isFile(); } catch { return false; }
   });
 
-  return { qaDirs, planDirs, dossierFiles, doneRoot };
-}
+  return { qaDirs, planDirs, dossierFiles, doneRoot, featureDirs };
+}
 
 /**
  * Minera todas as fontes de UMA feature. Best-effort: nunca lança.
@@ -478,14 +484,15 @@ function collectFeatureSources(targetDir, slug) {
   const corr = readCorrections({ rootDir, slug, locations });
   const trail = readDossierTrail({ rootDir, slug, locations });
   const events = readExecutionEvents({ rootDir, targetDir, slug });
-  const attempts = readAttempts({ rootDir, slug, locations });
-  const sigs = readFailureSignatures({ rootDir, slug, locations });
-  const devlogs = readDevlogs({ rootDir, targetDir, slug });
-
-  for (const r of [qa, corr, trail, events, attempts, sigs, devlogs]) {
-    findings.push(...r.findings);
-    warnings.push(...r.warnings);
-  }
+  const attempts = readAttempts({ rootDir, slug, locations });
+  const sigs = readFailureSignatures({ rootDir, slug, locations });
+  const devlogs = readDevlogs({ rootDir, targetDir, slug });
+  const verification = readVerificationReports({ rootDir, slug, locations, makeFinding, relPath });
+
+  for (const r of [qa, corr, trail, events, attempts, sigs, devlogs, verification]) {
+    findings.push(...r.findings);
+    warnings.push(...r.warnings);
+  }
   cycles.push(...trail.cycles);
 
   const counts = {
@@ -493,10 +500,11 @@ function collectFeatureSources(targetDir, slug) {
     corrections: corr.count,
     dossier_trail: trail.count,
     execution_events: events.count,
-    attempts: attempts.count,
-    failure_signatures: sigs.count,
-    devlogs: devlogs.count
-  };
+    attempts: attempts.count,
+    failure_signatures: sigs.count,
+    devlogs: devlogs.count,
+    verification_reports: verification.count
+  };
 
   const cost = {
     execution_events: events.count,
@@ -508,10 +516,11 @@ function collectFeatureSources(targetDir, slug) {
   };
 
   const minedPaths = [];
-  for (const d of locations.qaDirs) minedPaths.push(relPath(rootDir, d));
-  for (const d of locations.planDirs) minedPaths.push(relPath(rootDir, d));
-  for (const f of locations.dossierFiles) minedPaths.push(relPath(rootDir, f));
-  minedPaths.sort();
+  for (const d of locations.qaDirs) minedPaths.push(relPath(rootDir, d));
+  for (const d of locations.planDirs) minedPaths.push(relPath(rootDir, d));
+  for (const f of locations.dossierFiles) minedPaths.push(relPath(rootDir, f));
+  for (const f of verification.files) minedPaths.push(relPath(rootDir, f));
+  minedPaths.sort();
 
   return { slug, findings, cycles, counts, cost, minedPaths, warnings };
 }
@@ -526,7 +535,16 @@ function collectSources(targetDir, slugs) {
   const cycles = [];
   const warnings = [];
   const minedPaths = [];
-  const counts = { qa_reports: 0, corrections: 0, dossier_trail: 0, execution_events: 0, attempts: 0, failure_signatures: 0, devlogs: 0 };
+  const counts = {
+    qa_reports: 0,
+    verification_reports: 0,
+    corrections: 0,
+    dossier_trail: 0,
+    execution_events: 0,
+    attempts: 0,
+    failure_signatures: 0,
+    devlogs: 0
+  };
   const cost = { execution_events: 0, corrections: 0, fail_pass_cycles: 0, corrections_bytes: 0, token_count_available: false, token_total: null };
   const costByFeature = {};