@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/verification-policy.js

@@ -0,0 +1,398 @@
+'use strict';
+
+// Verification sub-agent policy (.aioson/config/verification.json).
+//
+// Piece 1 of the "smart harness, fewer agents doing more" redesign. This is the
+// reader the @dev phase-loop (auto-continue) and the post-dev review cycle
+// consult to decide WHICH verification sub-agent runs, WHEN, and on WHICH model
+// — resolved per host harness.
+//
+// Two dispatch modes per agent, keyed by the host harness (claude|codex|opencode):
+//   - native:   in-harness sub-agent. On Claude Code the Task tool runs a Claude
+//               model tier (e.g. sonnet-4.6); codex/opencode run their own
+//               configured model. You CANNOT run a codex/gpt model as a native
+//               Claude Code sub-agent — that is what `external` is for.
+//   - external: spawn a different vendor CLI as a read-only auditor
+//               (`aioson verify:implementation --tool=...`). The only way to bring
+//               a cross-vendor model in while hosted elsewhere — see `cross_check`.
+//
+// The file is auto-generated from template/.aioson/config/verification.json by the
+// installer (isConfigMergePath additive merge) and is hand-editable: user values
+// survive `aioson update`, only `version` is template-owned. A missing or
+// malformed file degrades to buildDefaultVerificationConfig() — never throws.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { exists } = require('./utils');
+
+const VERIFICATION_CONFIG_RELATIVE_PATH = '.aioson/config/verification.json';
+const KNOWN_HOSTS = ['claude', 'codex', 'opencode'];
+const DISPATCH_MODES = ['native', 'external'];
+const VERIFICATION_AGENTS = ['qa', 'tester', 'pentester', 'validator'];
+const TRIGGERS = ['per-phase', 'end-of-feature', 'sensitive-surface'];
+const DEFAULT_HOST = 'claude';
+const DEFAULT_MODEL = 'configured-default';
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+function defaultTriggers(agentId) {
+  switch (agentId) {
+    case 'qa': return ['per-phase', 'end-of-feature'];
+    case 'pentester': return ['sensitive-surface', 'end-of-feature'];
+    default: return ['end-of-feature'];
+  }
+}
+
+function defaultReport(agentId) {
+  switch (agentId) {
+    case 'qa': return 'qa-report-{slug}.md';
+    case 'tester': return 'test-report-{slug}.md';
+    case 'pentester': return 'security-findings-{slug}.json';
+    case 'validator': return 'validator-report-{slug}.json';
+    default: return `${agentId}-report-{slug}.md`;
+  }
+}
+
+function buildDefaultAgent(agentId) {
+  // pentester/validator default to the strongest tier; qa/tester to a cheaper
+  // tier — the per-phase verifier should be cheap, the security/contract
+  // verdicts should not be.
+  const claudeModel = (agentId === 'pentester' || agentId === 'validator') ? 'opus-4.8' : 'sonnet-4.6';
+  const agent = {
+    enabled: (agentId === 'qa' || agentId === 'validator') ? true : 'auto',
+    triggers: defaultTriggers(agentId),
+    dispatch: {
+      claude: { mode: 'native', model: claudeModel },
+      codex: { mode: 'native', model: DEFAULT_MODEL },
+      opencode: { mode: 'native', model: DEFAULT_MODEL }
+    },
+    report: defaultReport(agentId)
+  };
+  if (agentId === 'validator') {
+    agent.cross_check = { enabled: false, mode: 'external', tool: 'codex', model: DEFAULT_MODEL };
+  }
+  return agent;
+}
+
+function buildDefaultVerificationConfig() {
+  const agents = {};
+  for (const id of VERIFICATION_AGENTS) agents[id] = buildDefaultAgent(id);
+  return {
+    version: '1.0',
+    host: 'auto',
+    agents,
+    budget: {
+      max_subagents_per_phase: 1,
+      skip_on_micro: true,
+      full_smoke: 'end-of-feature-only'
+    },
+    phase_loop: {
+      auto_continue: true,
+      compact_between_phases: true,
+      max_fix_retries_per_phase: 2
+    },
+    // Deterministic build-free code-quality scan (`aioson audit:code`) wired into
+    // the tracked workflow:next dev/qa done-gate. `tracked_gate`: 'advisory'
+    // records + emits but never blocks (default — audit:code is a heuristic
+    // opinion, not the feature's declared contract); 'block' makes a HIGH finding
+    // in scope a hard gate; 'off' skips. `scope`: 'changed' = the git diff (fast),
+    // 'full' = the whole tree.
+    audit_code: {
+      tracked_gate: 'advisory',
+      scope: 'changed'
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+// Collapse an arbitrary value to a known host, falling back when unrecognized.
+function normalizeHost(host, fallback = DEFAULT_HOST) {
+  const safe = String(host || '').trim().toLowerCase();
+  return KNOWN_HOSTS.includes(safe) ? safe : fallback;
+}
+
+// The top-level `host` setting additionally allows the literal 'auto'.
+function normalizeHostSetting(host) {
+  const safe = String(host || 'auto').trim().toLowerCase();
+  if (safe === 'auto') return 'auto';
+  return KNOWN_HOSTS.includes(safe) ? safe : 'auto';
+}
+
+function normalizeEnabled(value, fallback = 'auto') {
+  if (value === true || value === false) return value;
+  if (String(value).trim().toLowerCase() === 'auto') return 'auto';
+  return fallback;
+}
+
+function normalizeDispatchMode(mode, fallback = 'native') {
+  const safe = String(mode || '').trim().toLowerCase();
+  return DISPATCH_MODES.includes(safe) ? safe : fallback;
+}
+
+function normalizeModel(model, fallback = DEFAULT_MODEL) {
+  return typeof model === 'string' && model.trim() ? model.trim() : fallback;
+}
+
+function normalizeDispatchEntry(entry, fallbackEntry) {
+  const safe = entry && typeof entry === 'object' ? entry : {};
+  return {
+    mode: normalizeDispatchMode(safe.mode, fallbackEntry.mode),
+    model: normalizeModel(safe.model, fallbackEntry.model)
+  };
+}
+
+function normalizeTriggers(triggers, fallback) {
+  if (!Array.isArray(triggers)) return [...fallback];
+  const cleaned = triggers
+    .map((t) => String(t || '').trim().toLowerCase())
+    .filter((t) => TRIGGERS.includes(t));
+  return cleaned.length ? Array.from(new Set(cleaned)) : [...fallback];
+}
+
+function normalizeAgent(parsed, agentId) {
+  const def = buildDefaultAgent(agentId);
+  const raw = parsed && typeof parsed === 'object' ? parsed : {};
+  const rawDispatch = raw.dispatch && typeof raw.dispatch === 'object' ? raw.dispatch : {};
+  const dispatch = {};
+  for (const host of KNOWN_HOSTS) {
+    dispatch[host] = normalizeDispatchEntry(rawDispatch[host], def.dispatch[host]);
+  }
+  const agent = {
+    enabled: normalizeEnabled(raw.enabled, def.enabled),
+    triggers: normalizeTriggers(raw.triggers, def.triggers),
+    dispatch,
+    report: normalizeModel(raw.report, def.report)
+  };
+  if (def.cross_check) {
+    const rawCc = raw.cross_check && typeof raw.cross_check === 'object' ? raw.cross_check : {};
+    agent.cross_check = {
+      enabled: typeof rawCc.enabled === 'boolean' ? rawCc.enabled : def.cross_check.enabled,
+      mode: normalizeDispatchMode(rawCc.mode, def.cross_check.mode),
+      tool: normalizeHost(rawCc.tool, def.cross_check.tool),
+      model: normalizeModel(rawCc.model, def.cross_check.model)
+    };
+  }
+  return agent;
+}
+
+function normalizeBudget(parsed) {
+  const def = buildDefaultVerificationConfig().budget;
+  const raw = parsed && typeof parsed === 'object' ? parsed : {};
+  return {
+    max_subagents_per_phase: Number.isInteger(raw.max_subagents_per_phase) && raw.max_subagents_per_phase >= 0
+      ? raw.max_subagents_per_phase
+      : def.max_subagents_per_phase,
+    skip_on_micro: typeof raw.skip_on_micro === 'boolean' ? raw.skip_on_micro : def.skip_on_micro,
+    full_smoke: normalizeModel(raw.full_smoke, def.full_smoke)
+  };
+}
+
+function normalizePhaseLoop(parsed) {
+  const def = buildDefaultVerificationConfig().phase_loop;
+  const raw = parsed && typeof parsed === 'object' ? parsed : {};
+  return {
+    auto_continue: typeof raw.auto_continue === 'boolean' ? raw.auto_continue : def.auto_continue,
+    compact_between_phases: typeof raw.compact_between_phases === 'boolean'
+      ? raw.compact_between_phases
+      : def.compact_between_phases,
+    max_fix_retries_per_phase: Number.isInteger(raw.max_fix_retries_per_phase) && raw.max_fix_retries_per_phase >= 0
+      ? raw.max_fix_retries_per_phase
+      : def.max_fix_retries_per_phase
+  };
+}
+
+function normalizeAuditCode(parsed) {
+  const def = buildDefaultVerificationConfig().audit_code;
+  const raw = parsed && typeof parsed === 'object' ? parsed : {};
+  const gate = String(raw.tracked_gate || '').trim().toLowerCase();
+  const scope = String(raw.scope || '').trim().toLowerCase();
+  return {
+    tracked_gate: ['block', 'advisory', 'off'].includes(gate) ? gate : def.tracked_gate,
+    scope: ['changed', 'full'].includes(scope) ? scope : def.scope
+  };
+}
+
+function normalizeVerificationConfig(parsed) {
+  const def = buildDefaultVerificationConfig();
+  const raw = parsed && typeof parsed === 'object' ? parsed : {};
+  const rawAgents = raw.agents && typeof raw.agents === 'object' ? raw.agents : {};
+  const agents = {};
+  // Always materialize the four known agents (defaults fill any gaps)...
+  for (const id of VERIFICATION_AGENTS) agents[id] = normalizeAgent(rawAgents[id], id);
+  // ...and preserve any user-defined extra agents (best-effort, generic shape).
+  for (const id of Object.keys(rawAgents)) {
+    if (!VERIFICATION_AGENTS.includes(id)) agents[id] = normalizeAgent(rawAgents[id], id);
+  }
+  return {
+    version: typeof raw.version === 'string' ? raw.version : def.version,
+    host: normalizeHostSetting(raw.host),
+    agents,
+    budget: normalizeBudget(raw.budget),
+    phase_loop: normalizePhaseLoop(raw.phase_loop),
+    audit_code: normalizeAuditCode(raw.audit_code)
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+async function readVerificationConfig(targetDir) {
+  const configPath = path.join(targetDir, VERIFICATION_CONFIG_RELATIVE_PATH);
+  if (!(await exists(configPath))) return buildDefaultVerificationConfig();
+  try {
+    const rawText = await fs.readFile(configPath, 'utf8');
+    return normalizeVerificationConfig(JSON.parse(rawText));
+  } catch {
+    return buildDefaultVerificationConfig();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Resolution / getters
+// ---------------------------------------------------------------------------
+
+// Precedence: explicit arg > config.host (when not 'auto') > env > default.
+function resolveHost(config, explicitHost = null, env = process.env) {
+  const explicit = String(explicitHost || '').trim().toLowerCase();
+  if (KNOWN_HOSTS.includes(explicit)) return explicit;
+
+  const configured = config && typeof config.host === 'string' ? config.host.trim().toLowerCase() : 'auto';
+  if (KNOWN_HOSTS.includes(configured)) return configured;
+
+  const envTool = String((env && (env.AIOSON_RUNNER_TOOL || env.AIOSON_TOOL)) || '').trim().toLowerCase();
+  if (KNOWN_HOSTS.includes(envTool)) return envTool;
+
+  return DEFAULT_HOST;
+}
+
+function getAgentConfig(config, agentId) {
+  const id = String(agentId || '').trim();
+  if (config && config.agents && typeof config.agents === 'object' && config.agents[id]) {
+    return config.agents[id];
+  }
+  if (VERIFICATION_AGENTS.includes(id)) return buildDefaultAgent(id);
+  return null;
+}
+
+// Resolve the {mode, model, host} a verification sub-agent should run on for the
+// active host harness. Falls back to the default-host entry, then to built-ins.
+function getAgentDispatch(config, agentId, host = null) {
+  const agent = getAgentConfig(config, agentId);
+  if (!agent) return null;
+  const resolvedHost = resolveHost(config, host);
+  const dispatch = agent.dispatch && typeof agent.dispatch === 'object' ? agent.dispatch : {};
+  const entry = dispatch[resolvedHost] || dispatch[DEFAULT_HOST];
+  if (entry && typeof entry === 'object') {
+    return { host: resolvedHost, mode: normalizeDispatchMode(entry.mode), model: normalizeModel(entry.model) };
+  }
+  const def = buildDefaultAgent(agentId);
+  const defEntry = def.dispatch[resolvedHost] || def.dispatch[DEFAULT_HOST];
+  return { host: resolvedHost, mode: defEntry.mode, model: defEntry.model };
+}
+
+// Resolve enabled:true|false|'auto' to a concrete boolean given run context.
+// 'auto' lets the framework decide: pentester only on a sensitive surface,
+// tester on anything above MICRO, everything else on.
+function resolveAgentEnabled(config, agentId, context = {}) {
+  const agent = getAgentConfig(config, agentId);
+  if (!agent) return false;
+  if (agent.enabled === true) return true;
+  if (agent.enabled === false) return false;
+  const classification = String(context.classification || '').trim().toUpperCase();
+  const sensitiveSurface = Boolean(context.sensitiveSurface);
+  switch (String(agentId).trim()) {
+    case 'pentester': return sensitiveSurface;
+    case 'tester': return classification !== 'MICRO';
+    default: return true;
+  }
+}
+
+function getAgentTriggers(config, agentId) {
+  const agent = getAgentConfig(config, agentId);
+  return agent && Array.isArray(agent.triggers) ? [...agent.triggers] : [];
+}
+
+function agentHasTrigger(config, agentId, trigger) {
+  return getAgentTriggers(config, agentId).includes(String(trigger || '').trim().toLowerCase());
+}
+
+function getAgentReportTemplate(config, agentId) {
+  const agent = getAgentConfig(config, agentId);
+  return agent && typeof agent.report === 'string' ? agent.report : '';
+}
+
+function resolveAgentReportPath(config, agentId, slug) {
+  return getAgentReportTemplate(config, agentId).replace(/\{slug\}/g, String(slug || '').trim());
+}
+
+function getCrossCheck(config, agentId) {
+  const agent = getAgentConfig(config, agentId);
+  if (!agent || !agent.cross_check || typeof agent.cross_check !== 'object') return null;
+  const cc = agent.cross_check;
+  return {
+    enabled: Boolean(cc.enabled),
+    mode: normalizeDispatchMode(cc.mode, 'external'),
+    tool: normalizeHost(cc.tool, 'codex'),
+    model: normalizeModel(cc.model)
+  };
+}
+
+function getBudget(config) {
+  return normalizeBudget(config && config.budget);
+}
+
+// Phase-loop behavior: whether @dev auto-continues across phases, compacts
+// between them, and how many in-phase fix retries are allowed before stopping.
+function getPhaseLoop(config) {
+  return normalizePhaseLoop(config && config.phase_loop);
+}
+
+// audit:code tracked-gate policy: 'block' | 'advisory' | 'off' + 'changed' | 'full'.
+function getAuditCodePolicy(config) {
+  return normalizeAuditCode(config && config.audit_code);
+}
+
+// Composed decision: should `agentId` run for `context.trigger` right now?
+// Combines trigger membership + enabled resolution + the skip-on-micro budget
+// guard (per-phase verification is suppressed on MICRO to save tokens).
+function shouldRunForTrigger(config, agentId, context = {}) {
+  const trigger = String(context.trigger || '').trim().toLowerCase();
+  if (!agentHasTrigger(config, agentId, trigger)) return false;
+  if (!resolveAgentEnabled(config, agentId, context)) return false;
+  const classification = String(context.classification || '').trim().toUpperCase();
+  if (getBudget(config).skip_on_micro && classification === 'MICRO' && trigger === 'per-phase') return false;
+  return true;
+}
+
+module.exports = {
+  VERIFICATION_CONFIG_RELATIVE_PATH,
+  KNOWN_HOSTS,
+  DISPATCH_MODES,
+  VERIFICATION_AGENTS,
+  TRIGGERS,
+  DEFAULT_HOST,
+  DEFAULT_MODEL,
+  buildDefaultVerificationConfig,
+  buildDefaultAgent,
+  normalizeVerificationConfig,
+  readVerificationConfig,
+  resolveHost,
+  getAgentConfig,
+  getAgentDispatch,
+  resolveAgentEnabled,
+  getAgentTriggers,
+  agentHasTrigger,
+  getAgentReportTemplate,
+  resolveAgentReportPath,
+  getCrossCheck,
+  getBudget,
+  getPhaseLoop,
+  getAuditCodePolicy,
+  shouldRunForTrigger
+};

package/src/version.js

@@ -3,11 +3,14 @@
 const fs = require('node:fs');
 const fsPromises = require('node:fs/promises');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 
-const PACKAGE_JSON_PATH = path.join(__dirname, '..', 'package.json');
+const ROOT_DIR = path.join(__dirname, '..');
+const PACKAGE_JSON_PATH = path.join(ROOT_DIR, 'package.json');
 const DEFAULT_VERSION = '0.0.0';
 
 let cachedVersion = null;
+let cachedGitInfo; // undefined = not computed yet; null = no git build info
 
 function parseVersionFromPackageJson(text) {
   try {
@@ -43,8 +46,56 @@ async function getCliVersion() {
   }
 }
 
+function runGitSync(args) {
+  return execFileSync('git', ['-C', ROOT_DIR, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  }).trim();
+}
+
+/**
+ * Short git build info for the package's OWN checkout (e.g. an `npm link`ed dev
+ * install). Lets `aioson --version` and the per-project install stamp report the
+ * exact commit a linked framework is running, so you don't need a semver bump
+ * per commit to know what's installed. Returns null when the package is not a
+ * git checkout (a normal npm install) or git is unavailable. Best-effort.
+ */
+function getGitBuildInfoSync() {
+  if (cachedGitInfo !== undefined) return cachedGitInfo;
+  try {
+    const sha = runGitSync(['rev-parse', '--short', 'HEAD']);
+    if (!sha) {
+      cachedGitInfo = null;
+      return cachedGitInfo;
+    }
+    let date = null;
+    try {
+      date = runGitSync(['show', '-s', '--format=%cs', 'HEAD']) || null;
+    } catch {
+      /* date is optional */
+    }
+    cachedGitInfo = { sha, date };
+  } catch {
+    cachedGitInfo = null;
+  }
+  return cachedGitInfo;
+}
+
+/**
+ * Display label: the semver, plus `(sha, date)` when running from a git checkout.
+ * e.g. "1.35.0 (<sha>, <date>)" linked, or "1.35.0" from an npm install.
+ */
+function getCliVersionLabelSync() {
+  const version = getCliVersionSync();
+  const git = getGitBuildInfoSync();
+  if (!git) return version;
+  return git.date ? `${version} (${git.sha}, ${git.date})` : `${version} (${git.sha})`;
+}
+
 module.exports = {
   getCliVersion,
   getCliVersionSync,
+  getGitBuildInfoSync,
+  getCliVersionLabelSync,
   parseVersionFromPackageJson
 };

package/template/.aioson/agents/analyst.md

@@ -9,7 +9,7 @@ Evaluate this immediately after reading this file and before loading any other c
 If the user only activates `@analyst` without naming a feature, PRD, or concrete analysis task:
 
 1. When the CLI is available, run `aioson workflow:status .` and `aioson context:select . --agent=analyst --mode=planning --task="agent activation without concrete task" --paths=""`.
-2. Load only: `.aioson/context/project.context.md` and a filename listing of `.aioson/context/prd*.md` / `requirements-*.md` (names only — no contents).
+2. Load only: `.aioson/context/project.context.md` and a filename listing of `.aioson/context/prd*.md` / `requirements-*.md` (names only — no contents).
 3. Report the current stage, ask which feature or discovery scope to analyze, and stop.
 
 Do NOT load on activation: PRD/requirements contents, `discovery.md`, `spec*.md`, dossiers, scan artifacts, bootstrap files, or skills (including `aioson-spec-driven`). Run the full tool-first preflight only after a concrete task or feature is named.
@@ -75,7 +75,7 @@ If the CLI is not available, compare modification dates manually:
 
 ## Mode detection
 
-Resolve the active feature first: run `aioson feature:current . 2>/dev/null` (single source of truth — pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug pins feature mode to that `{slug}`; this disambiguates when several `prd-{slug}.md` files coexist. If it returns `ambiguous: true` (`--json`), ask which feature before loading. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`. Then check:
+Resolve the active feature first: run `aioson feature:current . 2>/dev/null` (single source of truth — pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug pins feature mode to that `{slug}`; this disambiguates when several `prd-{slug}.md` files coexist. If it returns `ambiguous: true` (`--json`), ask which feature before loading. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`. Then check:
 
 **Feature mode** — a `prd-{slug}.md` file exists in `.aioson/context/`:
 - Read `prd-{slug}.md` to understand the feature scope.
@@ -144,7 +144,7 @@ Run after Sheldon enrichment context check. Check the frontmatter of the PRD bei
 
 ## Context integrity
 
-Read `.aioson/context/project.context.md` before starting discovery.
+Read `.aioson/context/project.context.md` before starting discovery.
 
 Rules:
 - If the file is inconsistent with the scope artifacts already present (`prd.md`, `prd-{slug}.md`, `discovery.md`, `spec.md`, `features.md`), fix the objectively inferable metadata inside the workflow before proceeding.
@@ -154,7 +154,7 @@ Rules:
 
 ## Brownfield pre-flight
 
-Check `framework_installed` in `.aioson/context/project.context.md` before starting any phase.
+Check `framework_installed` in `.aioson/context/project.context.md` before starting any phase.
 
 **If `framework_installed=true` AND `.aioson/context/discovery.md` exists:**
 - Skip Phases 1–3 below.
@@ -292,6 +292,9 @@ For each new or modified entity, produce field-level detail (same format as Phas
 ### Output contract — feature mode
 
 **`requirements-{slug}.md`** — implementation spec for the feature:
+
+> When `prd-{slug}.md` has a `## Prototype reference`, load `.aioson/docs/prototype-contract.md` and turn the prototype's Core screens and interactions into explicit acceptance criteria (e.g. "add card persists and re-renders", "board has a management surface"). This is how the prototype reaches @validator — as binary criteria, not a file it reads. After writing `requirements-{slug}.md`, run `aioson prototype:check . --feature={slug}` and resolve any `fail`/`warn` before handoff — it deterministically verifies every Core interaction in the prototype manifest is echoed by an acceptance criterion.
+
 1. Feature summary (1–2 lines from prd-{slug}.md)
 2. Requirement IDs (`REQ-{slug}-01...`) with source references
 3. Acceptance criteria IDs (`AC-{slug}-01...`) mapped to requirement IDs
@@ -379,7 +382,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 
 ## Dev handoff producer
 
-Before the final `agent:epilogue`/`agent:done` call, when the next agent in the workflow is `@dev`, produce `.aioson/context/dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
+Before the final `agent:epilogue`/`agent:done` call, when the next agent in the workflow is `@dev`, produce `.aioson/context/dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
 
 ```bash
 aioson dev:state:write . --feature={slug} --phase=1 \
@@ -389,7 +392,7 @@ aioson dev:state:write . --feature={slug} --phase=1 \
 
 `--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `readiness`, `ui-spec`, `dossier`, `simple-plan`), max 4 entries total; missing files emit a warning and are skipped. Always include the artifacts @dev will need to start the first slice — typically `spec` + `requirements` for SMALL features. Idempotent: re-running with the same args does not duplicate state.
 
-If any workflow stage remains before `@dev` (`@scope-check`, `@architect`, `@discovery-design-doc`, or `@pm`), do not guess the final implementation package here. The last pre-dev stage writes the final `.aioson/context/dev-state.md`; `@analyst` only produces it for direct-to-dev shortcuts.
+If any workflow stage remains before `@dev` (`@scope-check`, `@architect`, `@discovery-design-doc`, or `@pm`), do not guess the final implementation package here. The last pre-dev stage writes the final `.aioson/context/dev-state.md`; `@analyst` only produces it for direct-to-dev shortcuts.
 
 **Handoff message:**
 ```

package/template/.aioson/agents/architect.md

@@ -4,8 +4,8 @@
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
-
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
 
 - **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
@@ -45,7 +45,7 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 ## Activation guard
 
-If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
 
 ## Required input
 
@@ -131,10 +131,39 @@ aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
 ```
 Architecture defined: .aioson/context/architecture.md
 Gate B: {approved|blocked}
-Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
+Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev). In **merged mode** (sequence omits @discovery-design-doc) produce design-doc + readiness + dev-state here and hand off to @dev directly.
 Action: aioson workflow:next . --complete=architect --tool=<tool>
 ```
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+
+## Architect merged mode (absorbs @discovery-design-doc)
+
+Activate this mode whenever the active sequence omits `@discovery-design-doc` — which is now the **default for
+MEDIUM** (ddd was demoted to an opt-in detour), as well as the lean lane and the "full-merged" preset. In that
+case `@discovery-design-doc` does not run as its own stage, so produce design-doc + readiness + dev-state here so
+`@dev`'s SMALL/MEDIUM preflight is satisfied. Leave this OFF only when the active sequence explicitly includes
+`@discovery-design-doc` (an opt-in detour / older config) — then ddd owns these artifacts and producing them here
+would collide.
+
+In merged mode you additionally produce what `@discovery-design-doc` would have, so `@dev`'s SMALL/MEDIUM
+preflight (which requires the design-doc + readiness pair) is satisfied:
+
+1. **Design-doc** — `.aioson/context/design-doc-{slug}.md` (project mode: `design-doc.md`): scope/approach
+   decisions, exact implementation paths (create/modify/reuse/retire), and componentization/split notes.
+2. **Readiness** — `.aioson/context/readiness-{slug}.md` (project mode: `readiness.md`): the readiness verdict
+   (`ready`/`ready_with_warnings`/`blocked`), exact downstream agent, artifacts consumed, blockers, assumptions.
+   **Keep this gate** — it is the cheap, valuable checkpoint; do not drop it just because the agent merged.
+3. **Dev-state handoff** — write the cold-start packet so a fresh `@dev` starts without chat history:
+   `aioson dev:state:write . --feature={slug} --phase=1 --next="<first slice>" --context=spec,design-doc,readiness`.
+
+Then hand off to `@dev` (not `@discovery-design-doc`). Keep the artifacts proportional to classification — the
+merge removes a hop, it does not license heavier documents.
+
+> Note: at `@architect` completion the tracked workflow only gates `architecture.md` + Gate B structurally — the
+> design-doc + readiness you produce in merged mode are enforced by `@dev`'s SMALL/MEDIUM preflight (it halts at
+> activation if either is absent), not by a separate handoff contract. Produce both, or `@dev` stops. (The
+> full-merged preset keeps `@analyst`, so `spec-{slug}.md` and Gate C are satisfied normally — unlike the lean
+> lane, where `@sheldon` must write the spec itself.)
 
 ## Autopilot handoff
 

package/template/.aioson/agents/briefing-refiner.md

@@ -73,6 +73,20 @@ If the user declines application, leave `briefings.md` unchanged and record skip
 
 If feedback contains unresolved blocking items, do not hand off as ready for `@product`. The next action is to resolve blockers or rerun refinement.
 
+### Generate prototype (optional visual refinement)
+
+Use this when the user asks to see the solution visually, or when a rich-surface briefing (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management surfaces, repeated-use CRUD) would benefit from validating screens and interactions before the PRD. It is optional and user-invoked — never block the briefing path on it.
+
+1. Resolve the briefing slug and read `briefings.md` plus the operational surface map (`solution-options.md` / `expansion-scout.md`, falling back to the surface map in `.aioson/docs/feature-expansion-taxonomy.md`).
+2. Resolve the visual route from `design_skill` in `.aioson/context/project.context.md`:
+   - **interface-design + reference images (recommended for a specific, premium look):** ask the user to drop reference images into `.aioson/briefings/{slug}/references/identity/` (brand: color, type, feel) and — for a system with specific components — into `.aioson/briefings/{slug}/references/structure/` (a board, a table, a screen). Then load `.aioson/skills/process/reference-identity-extract/SKILL.md`, extract them once into `.aioson/briefings/{slug}/identity.md`, and self-gate: `aioson verify:artifact . --kind=identity --file=.aioson/briefings/{slug}/identity.md --advisory 2>/dev/null || true`. The prototype's look comes from `identity.md`; its `## Component structure notes` feed the surface map. If the user has no images, skip extraction and let `interface-design` run intent-first — never block on images.
+   - **a fixed preset:** if `design_skill` names an installed preset, use it. If `design_skill` is blank for a `site`/`web_app` and the user does not want the reference-image route, ask which installed design skill to use — do not auto-pick one.
+3. Load `.aioson/skills/process/prototype-forge/SKILL.md` and follow its build contract.
+4. Write `.aioson/briefings/{slug}/prototype.html` and `.aioson/briefings/{slug}/prototype-manifest.md`.
+5. Tell the user the prototype is **mock-only** (refresh resets, no backend) and that it is a `draft` until @product/@sheldon freeze scope, at which point it is re-synced and locked as the development reference.
+
+The prototype never edits `briefings.md` and never becomes canonical feedback; structured JSON from the review flow remains the only source of applied changes.
+
 ## Review HTML contract
 
 `review.html` must be static, local, and self-contained:
@@ -94,6 +108,7 @@ If feedback contains unresolved blocking items, do not hand off as ready for `@p
 - Never approve a briefing automatically.
 - Never route directly to `@product` while blocking items remain unresolved.
 - Never treat edited HTML or DOM state as canonical feedback.
+- Never treat `prototype.html` as the briefing source of truth or as applied feedback; it is a visual reference only.
 - Never write refinement JSON into `.aioson/context/`.
 - Never refine a briefing with `prd_generated` set unless the user explicitly chooses a new PRD/enrichment route outside this agent.
 - Never drop mandatory briefing sections.
@@ -110,6 +125,14 @@ Review generation writes:
 .aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
 ```
 
+Prototype generation (optional) writes:
+
+```text
+.aioson/briefings/{slug}/identity.md          # only when reference images were extracted
+.aioson/briefings/{slug}/prototype.html
+.aioson/briefings/{slug}/prototype-manifest.md
+```
+
 Confirmed application updates:
 
 ```text
@@ -123,6 +146,8 @@ Confirmed application updates:
 - If review was generated: user opens `review.html`, saves/exports feedback, then reactivates `@briefing-refiner`.
 - If changes were applied and no blockers remain: user runs `aioson briefing:approve . --slug={slug}`, then activates `@product`.
 - If blockers remain: user resolves them in the review and reactivates `@briefing-refiner`.
+- If a prototype was generated: user opens `prototype.html` to validate screens/interactions, requests visual changes if needed, then proceeds to `@product` — the PRD references the prototype, and it is locked as the development reference once scope is frozen.
+- **Rich-surface recommendation (non-blocking):** if the briefing has a rich operational surface (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management, repeated-use CRUD) and no prototype exists yet, recommend running `@briefing-refiner` prototype mode before `@product` — it surfaces missing management screens and broken interactions before the PRD. The deterministic trigger is `aioson classify . --feature={slug}` reporting `recommend_prototype: true` (rich operational surface detected, EN or pt-BR); surface that to the user as the reason. Recommend only; never block the route to `@product`.
 
 ## Observability