@jaimevalasek/aioson 1.33.1 → 1.37.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-]*$).',
@@ -408,6 +412,7 @@ module.exports = {
   update: {
     not_installed: 'No AIOSON installation found in {targetDir}.',
     done_at: 'Update completed at: {targetDir}',
+    template_version: 'Template version applied: {version}',
     files_updated: 'Files updated: {count}',
     backups_created: 'Backups created: {count}',
     profile_renamed: 'i Profile `beginner` renamed to `creator` in project.context.md to better describe the user. Behavior unchanged. Edit the file to switch to `developer` if desired.',
@@ -487,7 +492,7 @@ module.exports = {
     features_dir_present: 'Features directory present (.aioson/context/features/)',
     features_dir_present_hint: 'Create .aioson/context/features/ to host per-feature dossiers (doctor --fix will create it).',
     auto_handoff_declared: 'Autopilot handoff flag declared (auto_handoff in project.context.md)',
-    auto_handoff_declared_hint: 'The autopilot-handoff protocol is installed but auto_handoff is not set in project.context.md frontmatter — autopilot stays inactive. Set auto_handoff: true to enable it, or auto_handoff: false to silence this warning.',
+    auto_handoff_declared_hint: 'The autopilot-handoff protocol is installed and auto_handoff is not set — @product asks the run mode on screen at each feature kickoff (Autopilot / Step by step / Always). Set auto_handoff: true to always autopilot and skip the question, or false to always go step-by-step.',
     claude_commands_present: 'Claude slash commands present ({missing} missing of {required})',
     claude_commands_present_hint: 'Missing: {paths}. Run `aioson doctor . --fix` to restore them from the template.',
     version_drift: 'CLI version matches project.context.md (context: {context}, CLI: {cli})',

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-]*$).',
@@ -276,6 +280,7 @@ module.exports = {
   update: {
     not_installed: 'No se encontro instalacion de AIOSON en {targetDir}.',
     done_at: 'Actualizacion completada en: {targetDir}',
+    template_version: 'Version de template aplicada: {version}',
     files_updated: 'Archivos actualizados: {count}',
     backups_created: 'Backups creados: {count}',
     profile_renamed: 'i Perfil `beginner` renombrado a `creator` en project.context.md para describir mejor al usuario. Comportamiento sin cambios. Edita el archivo para cambiar a `developer` si lo prefieres.',
@@ -361,7 +366,7 @@ module.exports = {
     features_dir_present: 'Directorio de features presente (.aioson/context/features/)',
     features_dir_present_hint: 'Cree .aioson/context/features/ para hospedar dossiers por feature (doctor --fix lo crea).',
     auto_handoff_declared: 'Flag de autopilot handoff declarada (auto_handoff en project.context.md)',
-    auto_handoff_declared_hint: 'El protocolo autopilot-handoff esta instalado pero auto_handoff no esta definido en el frontmatter de project.context.md — el autopilot queda inactivo. Defina auto_handoff: true para activarlo, o auto_handoff: false para silenciar este aviso.',
+    auto_handoff_declared_hint: 'El protocolo autopilot-handoff esta instalado y auto_handoff no esta definido — @product pregunta el modo en pantalla al inicio de cada feature (Autopilot / Paso a paso / Siempre). Defina auto_handoff: true para siempre autopilot y omitir la pregunta, o false para siempre paso a paso.',
     claude_commands_present: 'Slash commands de Claude presentes ({missing} ausentes de {required})',
     claude_commands_present_hint: 'Ausentes: {paths}. Ejecute `aioson doctor . --fix` para restaurarlos.',
     version_drift: 'Version del CLI coincide con project.context.md (contexto: {context}, CLI: {cli})',

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-]*$).',
@@ -275,6 +279,7 @@ module.exports = {
   update: {
     not_installed: 'Aucune installation AIOSON trouvee dans {targetDir}.',
     done_at: 'Mise a jour terminee dans : {targetDir}',
+    template_version: 'Version du template appliquee : {version}',
     files_updated: 'Fichiers mis a jour : {count}',
     backups_created: 'Sauvegardes creees : {count}',
     profile_renamed: 'i Profil `beginner` renomme en `creator` dans project.context.md pour mieux decrire l utilisateur. Comportement inchange. Modifiez le fichier pour passer a `developer` si vous le souhaitez.',
@@ -360,7 +365,7 @@ module.exports = {
     features_dir_present: 'Repertoire features present (.aioson/context/features/)',
     features_dir_present_hint: 'Creez .aioson/context/features/ pour heberger les dossiers par feature (doctor --fix le cree).',
     auto_handoff_declared: 'Flag autopilot handoff declare (auto_handoff dans project.context.md)',
-    auto_handoff_declared_hint: 'Le protocole autopilot-handoff est installe mais auto_handoff n\'est pas defini dans le frontmatter de project.context.md — l\'autopilot reste inactif. Definissez auto_handoff: true pour l\'activer, ou auto_handoff: false pour faire taire cet avertissement.',
+    auto_handoff_declared_hint: 'Le protocole autopilot-handoff est installe et auto_handoff n\'est pas defini — @product demande le mode a l\'ecran au debut de chaque feature (Autopilot / Pas a pas / Toujours). Definissez auto_handoff: true pour toujours autopilot et sauter la question, ou false pour toujours pas a pas.',
     claude_commands_present: 'Slash commands de Claude presents ({missing} absents sur {required})',
     claude_commands_present_hint: 'Absents : {paths}. Executez `aioson doctor . --fix` pour les restaurer.',
     version_drift: 'Version du CLI conforme a project.context.md (contexte : {context}, CLI : {cli})',

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-]*$).',
@@ -375,6 +379,7 @@ module.exports = {
   update: {
     not_installed: 'Nenhuma instalacao do AIOSON encontrada em {targetDir}.',
     done_at: 'Atualizacao concluida em: {targetDir}',
+    template_version: 'Versao do template aplicada: {version}',
     files_updated: 'Arquivos atualizados: {count}',
     backups_created: 'Backups criados: {count}',
     profile_renamed: 'i Perfil `beginner` renomeado para `creator` em project.context.md para descrever melhor o usuario. Comportamento inalterado. Edite o arquivo para mudar para `developer` se preferir.',
@@ -461,7 +466,7 @@ module.exports = {
     features_dir_present: 'Diretorio de features presente (.aioson/context/features/)',
     features_dir_present_hint: 'Crie .aioson/context/features/ para hospedar dossies por feature (doctor --fix cria automaticamente).',
     auto_handoff_declared: 'Flag de autopilot handoff declarada (auto_handoff no project.context.md)',
-    auto_handoff_declared_hint: 'O protocolo autopilot-handoff esta instalado mas auto_handoff nao esta definido no frontmatter do project.context.md — o autopilot fica inativo. Defina auto_handoff: true para ativar, ou auto_handoff: false para silenciar este aviso.',
+    auto_handoff_declared_hint: 'O protocolo autopilot-handoff esta instalado e auto_handoff nao esta definido — o @product pergunta o modo na tela no inicio de cada feature (Autopilot / Passo a passo / Sempre). Defina auto_handoff: true para sempre autopilot e pular a pergunta, ou false para sempre passo a passo.',
     claude_commands_present: 'Slash commands do Claude presentes ({missing} ausentes de {required})',
     claude_commands_present_hint: 'Ausentes: {paths}. Rode `aioson doctor . --fix` para restaurar a partir do template.',
     version_drift: 'Versao do CLI bate com project.context.md (contexto: {context}, CLI: {cli})',

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/briefing-refiner/apply-feedback.js

@@ -39,7 +39,10 @@ function summarizeSkippedChanges(feedback) {
   return [...sectionChanges, ...decisionChanges];
 }
 
-async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale = false } = {}) {
+// Declining never writes to briefings.md, so a stale source hash is irrelevant
+// to safety — validating it would only dead-end the user whose briefing moved
+// on. Hence allowStale defaults to TRUE here (and only here).
+async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale = true } = {}) {
   const briefingPath = resolveBriefingPath(projectDir, slug, 'briefings.md');
   const currentMarkdown = await fs.readFile(briefingPath, 'utf8');
   const currentSourceHash = hashText(currentMarkdown);
@@ -57,10 +60,12 @@ async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale =
     source_hash: feedback.source_hash,
     applied_hash: currentSourceHash,
     status: 'declined',
+    round: feedback.round || 1,
     applied_changes: [],
     skipped_changes: skippedChanges,
     unresolved_comments: unresolvedComments,
     blocking_items: feedback.blocking_items || [],
+    findings: feedback.findings || [],
     next_action: 'rerun_review'
   });
 
@@ -104,15 +109,22 @@ async function applyConfirmedFeedback(projectDir, slug, feedback, { confirmed =
   if (returnedToDraft) {
     returnApprovedBriefingToDraft(registry, slug);
   }
+  // A blocking finding the user left pending blocks the PRD the same way an
+  // explicit blocking item does — even if the export step never mirrored it
+  // into blocking_items (hand-written feedback).
+  const pendingBlockingFindings = (feedback.findings || []).filter(
+    (finding) => finding.blocking && finding.status === 'pending'
+  );
+  const hasBlockers = (feedback.blocking_items || []).length > 0 || pendingBlockingFindings.length > 0;
   markRefinementState(registry, slug, {
-    refinement_status: feedback.blocking_items.length > 0 ? 'blocked' : 'applied',
+    refinement_status: hasBlockers ? 'blocked' : 'applied',
     review_html: `.aioson/briefings/${slug}/review.html`,
     refinement_report: `.aioson/briefings/${slug}/refinement-report.md`
   });
   await writeBriefingRegistry(projectDir, registry);
 
   const unresolvedComments = (feedback.comments || []).filter((comment) => !comment.resolved);
-  const nextAction = feedback.blocking_items.length > 0 ? 'resolve_blockers' : 'approve_briefing';
+  const nextAction = hasBlockers ? 'resolve_blockers' : 'approve_briefing';
   const report = buildRefinementReport({
     briefing_slug: slug,
     source_briefing_path: `.aioson/briefings/${slug}/briefings.md`,
@@ -120,15 +132,17 @@ async function applyConfirmedFeedback(projectDir, slug, feedback, { confirmed =
     source_hash: feedback.source_hash,
     applied_hash: appliedHash,
     status: 'applied',
+    round: feedback.round || 1,
     applied_changes: appliedChanges,
     skipped_changes: [],
     unresolved_comments: unresolvedComments,
     blocking_items: feedback.blocking_items || [],
+    findings: feedback.findings || [],
     next_action: nextAction
   });
   await fs.writeFile(resolveBriefingPath(projectDir, slug, 'refinement-report.md'), report, 'utf8');
 
-  return { ok: true, appliedChanges, nextAction, appliedHash, returnedToDraft };
+  return { ok: true, appliedChanges, nextAction, appliedHash, returnedToDraft, pendingBlockingFindings: pendingBlockingFindings.length };
 }
 
 module.exports = { applyConfirmedFeedback, applyDeclinedFeedback };