@jaimevalasek/aioson 1.33.1 → 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/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') {