@jaimevalasek/aioson 1.36.0 → 1.37.1

package/src/parser.js

@@ -30,6 +30,9 @@ function parseArgv(argv) {
         'help', 'version', 'no-launch', 'attach', 'tmux',
         'allow-warnings', 'install-hook', 'uninstall-hook', 'remove-hook',
         'agent-safe', 'agentic',
+        // workflow:execute — pure booleans; `--seed .` / `--step .` must not
+        // swallow the path positional as their value.
+        'seed', 'seed-only', 'step',
         'selective',
         'status', 'suggest', 'apply',
         'runtime-only', 'template-only', 'inception', 'locales',
@@ -44,6 +47,9 @@ function parseArgv(argv) {
         // verify:artifact — pure booleans; `--advisory .` / `--no-build .` must
         // not swallow the path positional.
         'advisory', 'no-build',
+        // briefing:apply-feedback — pure booleans; `--confirm .` / `--declined .`
+        // / `--allow-stale .` must not swallow the path positional.
+        'confirm', 'declined', 'allow-stale',
         // `--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/runtime-store.js

@@ -176,7 +176,7 @@ async function openRuntimeDb(targetDir, options = {}) {
       FOREIGN KEY (run_key) REFERENCES agent_runs(run_key) ON DELETE CASCADE
     );
 
-    CREATE TABLE IF NOT EXISTS execution_events (
+    CREATE TABLE IF NOT EXISTS execution_events (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       task_key TEXT,
       run_key TEXT,
@@ -199,7 +199,51 @@ async function openRuntimeDb(targetDir, options = {}) {
       created_at TEXT NOT NULL,
       FOREIGN KEY (task_key) REFERENCES tasks(task_key) ON DELETE SET NULL,
       FOREIGN KEY (run_key) REFERENCES agent_runs(run_key) ON DELETE CASCADE
-    );
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_execution_runs (
+      telemetry_run_id TEXT PRIMARY KEY,
+      dispatcher_run_id TEXT NOT NULL,
+      attempt_id TEXT NOT NULL,
+      feature TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      host TEXT NOT NULL,
+      model TEXT NOT NULL,
+      model_requested TEXT,
+      model_resolved TEXT,
+      reasoning_effort TEXT,
+      model_resolution_strategy TEXT,
+      catalog_source TEXT,
+      state TEXT NOT NULL DEFAULT 'queued',
+      pid INTEGER,
+      process_fingerprint TEXT,
+      report_path TEXT,
+      report_digest TEXT,
+      reason TEXT,
+      truncated_bytes INTEGER NOT NULL DEFAULT 0,
+      dropped_events INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      finished_at TEXT,
+      UNIQUE(feature, agent, dispatcher_run_id, attempt_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_execution_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      telemetry_run_id TEXT NOT NULL,
+      sequence_no INTEGER NOT NULL,
+      schema_version INTEGER NOT NULL DEFAULT 1,
+      event_type TEXT NOT NULL,
+      stream TEXT,
+      safe_summary TEXT NOT NULL DEFAULT '',
+      payload_json TEXT,
+      bytes INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      UNIQUE(telemetry_run_id, sequence_no),
+      FOREIGN KEY (telemetry_run_id) REFERENCES agent_execution_runs(telemetry_run_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_execution_events_cursor ON agent_execution_events(telemetry_run_id, sequence_no);
+    CREATE INDEX IF NOT EXISTS idx_agent_execution_runs_feature_updated ON agent_execution_runs(feature, updated_at DESC);
 
     CREATE TABLE IF NOT EXISTS artifacts (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -650,8 +694,14 @@ function normalizeTaskStatus(value, fallback) {
   return VALID_TASK_STATUSES.has(candidate) ? candidate : fallback;
 }
 
-function ensureLegacyColumns(db) {
-  const taskColumns = db.prepare('PRAGMA table_info(tasks)').all();
+function ensureLegacyColumns(db) {
+  const executionRunColumns = db.prepare('PRAGMA table_info(agent_execution_runs)').all();
+  const executionRunColumnNames = new Set(executionRunColumns.map((column) => column.name));
+  for (const column of ['model_requested', 'model_resolved', 'reasoning_effort', 'model_resolution_strategy', 'catalog_source']) {
+    if (!executionRunColumnNames.has(column)) db.exec(`ALTER TABLE agent_execution_runs ADD COLUMN ${column} TEXT`);
+  }
+
+  const taskColumns = db.prepare('PRAGMA table_info(tasks)').all();
   const taskColumnNames = new Set(taskColumns.map((column) => column.name));
 
   if (!taskColumnNames.has('task_kind')) {
@@ -2619,9 +2669,115 @@ function insertEvolutionLog(db, opts) {
   return id;
 }
 
-function listEvolutionLog(db, limit = 20) {
+function listEvolutionLog(db, limit = 20) {
   return db.prepare('SELECT * FROM evolution_log ORDER BY applied_at DESC LIMIT ?').all(limit);
-}
+}
+
+const EXECUTION_TERMINAL_STATES = new Set(['passed', 'failed', 'cancelled']);
+const EXECUTION_TRANSITIONS = {
+  queued: new Set(['running', 'waiting_report', 'paused', 'failed', 'cancelled']),
+  running: new Set(['waiting_report', 'paused', 'failed', 'cancelled']),
+  waiting_report: new Set(['passed', 'failed', 'correcting', 'paused']),
+  correcting: new Set(['running', 'paused', 'failed', 'cancelled']),
+  paused: new Set(['running', 'cancelled'])
+};
+
+function executionCorrelation(input) {
+  return {
+    feature: String(input.feature), agent: String(input.agent),
+    dispatcherRunId: String(input.dispatcher_run_id || input.run_id),
+    attemptId: String(input.attempt_id)
+  };
+}
+
+function findExecutionRun(db, input) {
+  const c = executionCorrelation(input);
+  return db.prepare(`SELECT * FROM agent_execution_runs WHERE feature=? AND agent=? AND dispatcher_run_id=? AND attempt_id=?`)
+    .get(c.feature, c.agent, c.dispatcherRunId, c.attemptId) || null;
+}
+
+function createExecutionRun(db, input) {
+  const c = executionCorrelation(input); const now = nowIso();
+  const id = input.telemetry_run_id || `aex-${slugify(c.feature)}-${require('node:crypto').randomUUID()}`;
+  const modelResolved = String(input.model_resolved || input.model);
+  const modelRequested = String(input.model_requested || input.model || '');
+  db.prepare(`INSERT OR IGNORE INTO agent_execution_runs
+    (telemetry_run_id,dispatcher_run_id,attempt_id,feature,agent,host,model,model_requested,model_resolved,reasoning_effort,model_resolution_strategy,catalog_source,state,created_at,updated_at)
+    VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(id,c.dispatcherRunId,c.attemptId,c.feature,c.agent,String(input.host),modelResolved,modelRequested,modelResolved,input.reasoning_effort?String(input.reasoning_effort):null,input.model_resolution_strategy?String(input.model_resolution_strategy):null,input.catalog_source?String(input.catalog_source):null,'queued',now,now);
+  const run = findExecutionRun(db,input);
+  appendExecutionEvent(db,run.telemetry_run_id,{type:'run_created',safe_summary:'Execution queued'});
+  return run;
+}
+
+function appendExecutionEvent(db, runOrCorrelation, event) {
+  const run = typeof runOrCorrelation === 'string'
+    ? db.prepare('SELECT * FROM agent_execution_runs WHERE telemetry_run_id=?').get(runOrCorrelation)
+    : findExecutionRun(db,runOrCorrelation);
+  if (!run) throw new Error('execution_run_not_found');
+  const allowed = new Set(['run_created','process_started','state_changed','output','retry','fallback','timeout','report_attached','output_truncated','recovered','diagnostic']);
+  if (!allowed.has(event.type)) throw new Error('execution_event_type_invalid');
+  const sanitize=(value,depth=0)=>{if(depth>4)return'[TRUNCATED]';if(typeof value==='string')return value.replace(/(authorization\s*[:=]\s*(?:bearer\s+)?|api[_-]?key\s*[:=]\s*|token\s*[:=]\s*|password\s*[:=]\s*)[^\s,;]+/gi,'$1[REDACTED]').slice(0,2000);if(Array.isArray(value))return value.slice(0,25).map(v=>sanitize(v,depth+1));if(value&&typeof value==='object'){const out={};for(const key of Object.keys(value).slice(0,25))out[String(key).slice(0,100)]=sanitize(value[key],depth+1);return out}return value};
+  const safeSummary=sanitize(String(event.safe_summary||''));const safePayload=event.payload?sanitize(event.payload):null;
+  const tx=db.transaction(()=>{const seq=db.prepare('SELECT COALESCE(MAX(sequence_no),0)+1 n FROM agent_execution_events WHERE telemetry_run_id=?').get(run.telemetry_run_id).n;
+    db.prepare(`INSERT INTO agent_execution_events(telemetry_run_id,sequence_no,event_type,stream,safe_summary,payload_json,bytes,created_at) VALUES(?,?,?,?,?,?,?,?)`)
+      .run(run.telemetry_run_id,seq,event.type,event.stream||null,safeSummary,safePayload?JSON.stringify(safePayload).slice(0,16384):null,Math.min(Math.max(Number(event.bytes||0),0),16384),nowIso());return seq;});
+  return tx();
+}
+
+function attachExecutionProcess(db, correlation, process) {
+  const run=findExecutionRun(db,correlation); if(!run)throw new Error('execution_run_not_found');
+  if(run.pid && run.pid!==process.pid)throw new Error('execution_process_conflict');
+  db.prepare('UPDATE agent_execution_runs SET pid=?,process_fingerprint=?,state=?,updated_at=? WHERE telemetry_run_id=?')
+    .run(Number(process.pid),String(process.fingerprint||''),'running',nowIso(),run.telemetry_run_id);
+  appendExecutionEvent(db,run.telemetry_run_id,{type:'process_started',safe_summary:`Process ${process.pid} started`});
+  return db.prepare('SELECT * FROM agent_execution_runs WHERE telemetry_run_id=?').get(run.telemetry_run_id);
+}
+
+function transitionExecutionRun(db, correlation, next, reason=null) {
+  const run=findExecutionRun(db,correlation); if(!run)throw new Error('execution_run_not_found');
+  if(run.state===next)return run;if(EXECUTION_TERMINAL_STATES.has(run.state)||!EXECUTION_TRANSITIONS[run.state]?.has(next))throw new Error('execution_state_transition_invalid');
+  const safeReason=String(reason||'').replace(/(token|password|api[_-]?key)\s*[:=]\s*\S+/gi,'$1=[REDACTED]').slice(0,500)||null;
+  const now=nowIso();db.prepare('UPDATE agent_execution_runs SET state=?,reason=?,updated_at=?,finished_at=? WHERE telemetry_run_id=? AND state=?')
+    .run(next,safeReason,now,EXECUTION_TERMINAL_STATES.has(next)?now:null,run.telemetry_run_id,run.state);
+  appendExecutionEvent(db,run.telemetry_run_id,{type:'state_changed',safe_summary:`${run.state} -> ${next}`,payload:{state:next,reason}});
+  return db.prepare('SELECT * FROM agent_execution_runs WHERE telemetry_run_id=?').get(run.telemetry_run_id);
+}
+
+function attachExecutionReport(db, correlation, report) {
+  const run=findExecutionRun(db,correlation);if(!run)throw new Error('execution_run_not_found');
+  if(report.attempt_id!==run.attempt_id||report.run_id!==run.dispatcher_run_id)throw new Error('execution_report_binding_invalid');
+  db.prepare('UPDATE agent_execution_runs SET report_path=?,report_digest=?,updated_at=? WHERE telemetry_run_id=?')
+    .run(String(report.path||''),String(report.digest||''),nowIso(),run.telemetry_run_id);
+  appendExecutionEvent(db,run.telemetry_run_id,{type:'report_attached',safe_summary:'Bound report attached'});return findExecutionRun(db,correlation);
+}
+
+function getExecutionSnapshot(db, filters={}) {
+  const where=[],args=[];for(const [column,key] of [['feature','feature'],['agent','agent'],['state','state']])if(filters[key]){where.push(`${column}=?`);args.push(String(filters[key]));}
+  const limit=Math.min(Math.max(Number(filters.limit)||50,1),200);
+  return db.prepare(`SELECT * FROM agent_execution_runs ${where.length?'WHERE '+where.join(' AND '):''} ORDER BY updated_at DESC LIMIT ?`).all(...args,limit);
+}
+
+function listExecutionEvents(db, runId, options={}) {
+  const after=Math.max(Number(options.after)||0,0),limit=Math.min(Math.max(Number(options.limit)||100,1),500);
+  const rows=db.prepare('SELECT * FROM agent_execution_events WHERE telemetry_run_id=? AND sequence_no>? ORDER BY sequence_no LIMIT ?').all(runId,after,limit+1);
+  const hasMore=rows.length>limit,events=hasMore?rows.slice(0,limit):rows;
+  return {events,next_cursor:events.at(-1)?.sequence_no||after,has_more:hasMore};
+}
+
+function reconcileExecutionRun(db, correlation, probe=()=>false) {
+  const run=findExecutionRun(db,correlation);if(!run)throw new Error('execution_run_not_found');
+  if(EXECUTION_TERMINAL_STATES.has(run.state)||run.state==='paused')return run;
+  if(!run.pid)return transitionExecutionRun(db,correlation,'paused','spawn_identity_missing');
+  const observed=probe({pid:run.pid,fingerprint:run.process_fingerprint,created_at:run.created_at});
+  const alive=observed===true?false:Boolean(observed?.alive&&observed?.fingerprint&&observed.fingerprint===run.process_fingerprint);
+  if(alive)return transitionExecutionRun(db,correlation,'paused','detached_process');
+  return transitionExecutionRun(db,correlation,'paused','process_not_alive');
+}
+
+function pruneExecutionTelemetry(db, options={}) {
+  const days=Math.max(Number(options.retentionDays)||14,1),cutoff=new Date(Date.now()-days*86400000).toISOString(),batch=Math.min(Math.max(Number(options.batch)||100,1),1000);
+  return db.prepare(`DELETE FROM agent_execution_runs WHERE telemetry_run_id IN (SELECT telemetry_run_id FROM agent_execution_runs WHERE updated_at < ? AND state IN ('passed','failed','cancelled','paused') ORDER BY updated_at LIMIT ?)` ).run(cutoff,batch).changes;
+}
 
 module.exports = {
   resolveRuntimePaths,
@@ -2725,5 +2881,8 @@ module.exports = {
   listDynamicTools,
   // Evolution Log CRUD
   insertEvolutionLog,
-  listEvolutionLog
-};
+  listEvolutionLog
+  ,createExecutionRun, findExecutionRun, attachExecutionProcess, transitionExecutionRun,
+  appendExecutionEvent, attachExecutionReport, getExecutionSnapshot, listExecutionEvents,
+  reconcileExecutionRun, pruneExecutionTelemetry
+};

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

@@ -4,9 +4,13 @@
 
 > Activated as `@briefing-refiner`. Execute these instructions immediately when invoked.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @briefing-refiner` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
-Refine an existing `@briefing` artifact before `@product` generates a PRD. Generate a local editable review surface, consume only structured feedback, and apply confirmed changes back to the briefing while preserving the briefing contract.
+Refine an existing `@briefing` artifact before `@product` generates a PRD. You do the intelligent audit; the CLI owns the review surface. Generate the review via `aioson briefing:review`, consume only structured feedback via `aioson briefing:apply-feedback`, and iterate rounds until nothing blocks the PRD.
 
 ## Required input
 
@@ -39,39 +43,67 @@ aioson context:select . --agent=briefing-refiner --mode=planning --task="<refine
 
 Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned rule/doc looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean.
 
-## Operating modes
+## The refinement loop
 
-### Generate review
+The whole agent runs this loop until the briefing is clean:
 
-Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists or when the user explicitly asks to regenerate the review.
+1. **Generate review** (below) — audit → findings → `aioson briefing:review`.
+2. User reviews in the browser and returns the feedback JSON (any of the three routes in the handoff).
+3. **Apply feedback** (below) — dry-run → confirm → apply. The CLI archives the consumed feedback/findings for that round.
+4. **Decide the next iteration:**
+   - Blockers remain (`next_action: resolve_blockers`), or the applied changes materially changed the briefing text → **regenerate the review** (fresh audit of the UPDATED text, new findings file, next round) and go back to step 2.
+   - No blockers and no substantive open questions → exit the loop: tell the user to run `aioson briefing:approve . --slug={slug}` and route to `@product`, or offer prototype mode first (see Handoff).
 
-1. Parse `briefings.md`.
-2. Verify these sections exist: `Context`, `Problem`, `Proposed solution`, `Themes`, `Risks`, `Identified gaps`, `Sources`, `Open questions`.
-3. Audit for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
-4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in `refinement-report.md`.
-5. Write:
-   - `.aioson/briefings/{slug}/review.html`
-   - `.aioson/briefings/{slug}/refinement-feedback.json`
-   - `.aioson/briefings/{slug}/refinement-report.md`
-6. Tell the user to open `review.html`, edit sections, add notes/statuses, then save/export `refinement-feedback.json`.
-
-### Apply pending feedback
+Never exit the loop by hand-editing `briefings.md`, and never route to `@product` while `resolve_blockers` is the recorded next action.
 
-Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists and contains unapplied changes.
-
-1. Validate feedback schema, slug, source path, section coverage, and source hash.
-2. Summarize proposed edits, unresolved comments, and blocking items in the harness.
-3. Ask for explicit confirmation before editing `briefings.md`.
-4. If confirmed, apply only structured JSON feedback. Never infer changes from the HTML DOM.
-5. Preserve all mandatory sections.
-6. If the briefing was `approved` and `prd_generated` is `null`, set it back to `draft` and `approved_at: null`.
-7. Write/update `refinement-report.md`.
+### Generate review
 
-### Decline or blocked feedback
+Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists (the apply step archives consumed feedback, so file present = pending) or when the user explicitly asks to regenerate the review.
+
+1. Read `briefings.md` for the slug.
+2. Audit it for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
+3. Write the audit as `.aioson/briefings/{slug}/refinement-findings.json` — a JSON array of findings:
+   ```json
+   [{ "section_id": "problem", "category": "gap", "severity": "high", "blocking": true,
+      "text": "<what is wrong, specific>", "recommendation": "<what to do about it>" }]
+   ```
+   - `category`: `ambiguity` | `redundancy` | `gap` | `risk` | `pending-decision` | `scope-suggestion`
+   - `severity`: `low` | `medium` | `high`; `blocking: true` only when the PRD cannot be written without resolving it.
+   - `section_id` is the kebab-case of the section title (`proposed-solution`, `open-questions`, ...). Write finding text in the interaction language.
+   - **Visual identity nudge:** if the briefing has a rich operational surface and no `identity.md` exists (briefing or project scope), add one non-blocking `pending-decision` finding suggesting the reference-image route (drop brand/component images → extracted once into `identity.md`) — decided in review or in prototype mode, never forced.
+4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in a finding.
+5. Generate the surface deterministically:
+   ```bash
+   aioson briefing:review . --slug={slug} --locale=<interaction_language> --json
+   ```
+   The CLI parses sections, validates your findings (fix and re-run on `invalid_findings`), renders `review.html` + `refinement-feedback.json` + `refinement-report.md`, and keeps the round counter. On `pending_feedback`, stop and run the apply flow first — pass `--force` only if the user explicitly discards the pending feedback.
+6. Hand off per **Handoff** (browser instructions + the three return routes).
+
+Do NOT hand-write `review.html` when the CLI is available — the gate rejects hand-rolled surfaces. Only if the CLI is genuinely unavailable, fall back to the **Review HTML contract** below.
 
-If the user declines application, leave `briefings.md` unchanged and record skipped changes in `refinement-report.md`.
+### Apply pending feedback
 
-If feedback contains unresolved blocking items, do not hand off as ready for `@product`. The next action is to resolve blockers or rerun refinement.
+Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists (file present = not yet applied).
+
+1. If the user pasted the exported JSON in the chat, write it verbatim to `.aioson/briefings/{slug}/refinement-feedback.json` first.
+2. **Incorporate answers into section text.** Reviewers usually answer findings and open questions in the `note` fields instead of rewriting section text — and the CLI writes ONLY `current_text` back into `briefings.md`; notes alone never reach the briefing. Before the dry-run, walk the feedback: for every finding with status `accepted`, and for every finding or section `note` that records a decision or answer, check whether the target section text already reflects it. Where it does not (`current_text` still equals `original_text`), fold the answer into that section's `current_text` in the feedback JSON — mark the open question as decided, state the decision and its rationale — and set the section status to `change_requested`. Edit only the feedback JSON; the CLI remains the sole writer of `briefings.md`. If a note is ambiguous, ask the user instead of guessing.
+3. Dry-run — validation + summary, never writes:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --json
+   ```
+   Present the summary (changed sections, blocked sections, finding decisions, pending blocking findings) in the interaction language, listing every incorporation made in step 2 so the user sees exactly what will land in the briefing. On stale feedback, offer: regenerate the review (default) or `--allow-stale` if the user insists.
+4. Ask for explicit confirmation before touching `briefings.md`.
+5. If confirmed:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --confirm --json
+   ```
+   The CLI applies only structured JSON (never the HTML DOM), preserves mandatory sections, reverts `approved` → `draft` when applicable, archives the consumed feedback/findings for the round, and records `next_action`.
+6. If declined:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --declined --json
+   ```
+   `briefings.md` stays unchanged; skipped changes are recorded in `refinement-report.md`, and the declined feedback is archived (`refinement-feedback.declined-round{N}.json`) so the next round regenerates cleanly. Findings are kept — the briefing text did not change.
+7. Continue **The refinement loop** at step 4. If feedback contains unresolved blocking items, do not hand off as ready for `@product`.
 
 ### Generate prototype (optional visual refinement)
 
@@ -87,20 +119,20 @@ Use this when the user asks to see the solution visually, or when a rich-surface
 
 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 contract (CLI fallback only)
+
+`aioson briefing:review` renders this contract; reproduce it by hand ONLY when the CLI is unavailable. `review.html` must be static, local, and self-contained:
 
-`review.html` must be static, local, and self-contained:
+- no server, no external scripts/styles/fonts/services
+- dense implementation-review layout in the interaction language
+- editable plain text sections + section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
+- findings rendered per section with status (`pending`/`accepted`/`rejected`/`deferred`), note field, and working category filters
+- notes/comments by section; summary of what will be done, what is uncertain, and what blocks PRD
+- localStorage autosave of the draft + restore on reopen
+- export/download/copy JSON fallback always available; File System Access API only as progressive enhancement, degrading to download on SecurityError (sandboxed previews)
+- feedback JSON in the canonical v1.1 schema with the source hash embedded
 
-- no server
-- no external scripts or services
-- dense implementation-review layout
-- editable plain text sections
-- section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
-- notes/comments by section
-- summary of what will be done, what is uncertain, and what blocks PRD
-- filters for ambiguity, redundancy, gap, risk, pending decision, and scope suggestion
-- export/download/copy JSON fallback always available
-- File System Access API only as progressive enhancement after explicit user action
+Self-check either path with: `aioson verify:artifact . --kind=review --slug={slug} --advisory 2>/dev/null || true`
 
 ## Hard constraints
 
@@ -108,21 +140,22 @@ The prototype never edits `briefings.md` and never becomes canonical feedback; s
 - 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 hand-write `review.html` or hand-apply feedback to `briefings.md` while the CLI commands are available.
 - 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.
-- Do not create a dedicated briefing refinement CLI command in V1.
 
 ## Output contract
 
 Review generation writes:
 
 ```text
-.aioson/briefings/{slug}/review.html
-.aioson/briefings/{slug}/refinement-feedback.json
+.aioson/briefings/{slug}/refinement-findings.json   # your audit (input to the CLI)
+.aioson/briefings/{slug}/review.html                # rendered by briefing:review
+.aioson/briefings/{slug}/refinement-feedback.json   # canonical v1.1, rendered by briefing:review
 .aioson/briefings/{slug}/refinement-report.md
-.aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
+.aioson/briefings/{slug}/expansion-scout.md         # only when expansion scout is triggered
 ```
 
 Prototype generation (optional) writes:
@@ -138,22 +171,29 @@ Confirmed application updates:
 ```text
 .aioson/briefings/{slug}/briefings.md
 .aioson/briefings/{slug}/refinement-report.md
+.aioson/briefings/{slug}/refinement-feedback.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-findings.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-feedback.declined-round{N}.json  # archived by the CLI on decline
 .aioson/briefings/config.md
 ```
 
 ## Handoff
 
-- If review was generated: user opens `review.html`, saves/exports feedback, then reactivates `@briefing-refiner`.
+- **After generating a review**, tell the user (in the interaction language):
+  1. Open `review.html` in a **real browser** (double-click the file). Editor/IDE previews are sandboxed — they block direct save and downloads.
+  2. Edits autosave locally in the browser; closing the tab loses nothing. Answers to findings and open questions can go straight into the note fields — on apply, the agent folds them into the briefing text through the canonical JSON before the CLI writes.
+  3. Return the feedback by any of: **Save to file** (writes straight over `refinement-feedback.json`), **Download JSON** (then move it over `refinement-feedback.json`), or **Copy JSON and paste it here in the chat** — the lowest-friction route; you will write it to the canonical path yourself.
+  4. Reactivate `@briefing-refiner` to apply.
 - 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 blockers remain: resolve them via the next review round (the loop), not by hand.
 - 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
 
-At session end, write artifacts first, then run best-effort observability in this order:
+At session end, write artifacts first, then run best-effort observability in this order (the `--slug` lets `agent:done` auto-fire the review done-gate):
 
 ```bash
 aioson pulse:update . --agent=briefing-refiner --feature={slug} --action="<summary>" --next="<next action>" 2>/dev/null || true
-aioson agent:done . --agent=briefing-refiner --summary="<one-line summary>" 2>/dev/null || true
+aioson agent:done . --agent=briefing-refiner --slug={slug} --summary="<one-line summary>" 2>/dev/null || true
 ```

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

@@ -4,6 +4,10 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @briefing` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Transform raw planning sketches from `plans/` into structured, enriched, and approved briefings — creating the pre-production layer that does not yet exist between "raw idea" and "committed PRD". You do not implement code, produce PRDs, or run any part of the pipeline. You produce `.aioson/briefings/{slug}/briefings.md`.
 

package/template/.aioson/agents/dev.md

@@ -13,6 +13,10 @@ aioson context:brief . --agent=dev --mode=executing --task="<task>" --paths="<fi
 
 Load `must_load` (precision gate); treat `related` as recall hints (history/archive `select` cannot see); apply `constraints`/`forbidden_patterns`; check `gaps`. **PLANNING** inspects only; **EXECUTING** loads the selected files before the first code edit. Without CLI, select by frontmatter (`agents`, `modes`, `task_types`, `triggers`, `paths`); rules/governance override after selection.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @dev` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
 
@@ -89,6 +93,7 @@ Load the primary package first. Then load phase-triggered files from the plan, r
 - `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
 - `ui-spec-{slug}.md` (project mode: `ui-spec.md`) — UI components, frontend routes, states, copy placement, visual QA.
 - `.aioson/briefings/{slug}/prototype.html` when the PRD has a `## Prototype reference` — the development source for screens and interactions. Load `.aioson/docs/prototype-contract.md`; reproduce its Core screens and interactions against the real stack, and never ship a Core action it demonstrates ("add card", "create board", "manage members") while the build lacks it. It is mock-only — copy the behavior, not the mock persistence.
+- `identity.md` when building UI and `design_skill: interface-design` — resolve `.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`. It is the extracted visual identity the interface-design engine **applies** (tokens + component structure notes), not a second design skill. Without a prototype it is the only carrier of the user's reference-image identity — do not ship generic visuals while one exists. See `.aioson/docs/reference-identity.md`.
 - PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
 - `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
 
@@ -144,7 +149,7 @@ Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
 
 ## Phase loop (auto-continue)
 
-@dev runs a phased plan as a loop and **auto-continues by default — no "continue?" between phases** (`phase_loop.auto_continue`). After each phase's `harness:check`, run `aioson verification:plan . --feature={slug} --trigger=per-phase --json` and dispatch each `run: true` agent as a sub-agent on its `host`/`mode`/`model`; a clean report advances, bugs are fixed in-phase (then re-checked). Compact between phases. The full runtime smoke runs once at end-of-feature, never per phase. Full protocol: `.aioson/docs/dev/phase-loop.md`.
+@dev runs a phased plan as **one continuous drive to the end of the feature, not one phase per turn.** Auto-continue is imperative (`phase_loop.auto_continue`): when a phase's gate is clean, go straight into the next phase — never stop to ask "continue?", never summarize-and-end, and **never self-issue `/compact`**. Per phase: `harness:check`, then `aioson verification:plan . --feature={slug} --trigger=per-phase --json`; dispatch each `run: true` entry through `aioson agent:execution:dispatch`, never by an assumed prompt-only subagent. `unsupported_capability` pauses honestly. A clean schema-valid report advances; bugs are fixed in-phase up to `max_fix_retries_per_phase`. `aioson dev:state:write` between phases is a resumable safety net. Full runtime smoke runs once at end-of-feature. Full protocol: `.aioson/docs/dev/phase-loop.md`.
 
 ## Context size detection
 
@@ -308,7 +313,9 @@ Check `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|test
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md` and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
+**Run-mode token (activation args, highest precedence):** a standalone `--auto` in your activation arguments arms autopilot from here on even with no flag/scheme — run `aioson workflow:execute . --feature={slug} --seed --tool=claude`, then follow this section. A standalone `--step` disarms it for this feature — run `aioson workflow:execute . --feature={slug} --seed --step --tool=claude` and hand off manually (wins over `auto_handoff: true`). Strip the token from the task text.
+
+When `auto_handoff: true` is set in `project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** is present — a scheme left by a different/closed feature does NOT count; a scheme for this feature with `agentic_policy.enabled: false` is the `--step` disarm and wins over the flag: hand off manually) and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
 
 1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
 2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).

package/template/.aioson/agents/deyvin.md

@@ -2,6 +2,10 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @deyvin` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Act as AIOSON's continuity-first pair programming agent. Your codename is **Deyvin**. Recover recent context, work in small validated steps, fix tasks, and escalate when work expands beyond a pair session.
 

package/template/.aioson/agents/discover.md

@@ -2,6 +2,10 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @discover` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Read the project's key files, code, and artifacts to build a **semantic knowledge cache** in `.aioson/context/bootstrap/`. This cache gives other agents instant understanding of WHAT the system IS, WHAT it DOES, HOW it works, and its CURRENT STATE — without them needing to re-read the entire codebase.
 

package/template/.aioson/agents/neo.md

@@ -2,6 +2,10 @@
 
 > ⚡ **ACTIVATED** — You are now operating as @neo, the system router. Execute the instructions in this file immediately.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @neo` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Be the single entry point for AIOSON sessions. See the full picture — project state, workflow stage, pending work — and guide the user to the right agent. Never implement, never produce artifacts. Your only job: orient and route.
 

package/template/.aioson/agents/orache.md

@@ -9,6 +9,10 @@
 ## Language boundary
 Use the project's `interaction_language` for all user-facing communication. If `interaction_language` is absent, fall back to `conversation_language`. If neither is available, match the user's message language.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @orache` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
 Investigate a domain deeply before a squad is created. Discover the real

package/template/.aioson/agents/orchestrator.md

@@ -3,6 +3,10 @@
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @orchestrator` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Own the MEDIUM spec phase as the **maestro**: fan out to focused sub-agents (the analyst/architect/pm/ui work), then consolidate, verify, correct, and redo their output into one gated spec package for `@dev` — the horizontal counterpart to `@sheldon`'s lean lane (SMALL). Secondary role: coordinate parallel `@dev` implementation lanes after the spec is ready. MEDIUM only — never activate for MICRO or SMALL.
 
@@ -412,6 +416,18 @@ Action: /dev or /qa
 ```
 > Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
+## Autopilot handoff (auto_handoff)
+
+When `auto_handoff: true` is set in `project.context.md` (or the seeded scheme with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** is present; `agentic_policy.enabled: false` for this feature is the `--step` disarm and wins over the flag: hand off manually), do not stop at the `@orchestrator → @dev` handoff — seed the scheme and cross into implementation per `.aioson/docs/autopilot-handoff.md`:
+
+1. Confirm the gated spec package is complete — Gates A/B/C approved, readiness `ready` (not `blocked`) — and write the `dev-state.md` cold-start packet. A blocked gate/readiness or an open scope decision is a manual stop.
+2. Seed the run's agentic contract (idempotent — a no-op if `@product` already seeded it):
+   `aioson workflow:execute . --feature={slug} --seed --tool=claude` — check the result; a `different_active_feature` failure means another feature still holds `workflow.state.json`: surface it and stop with the manual handoff.
+3. Advance the state machine: `aioson workflow:next . --complete=orchestrator --tool=claude` (**must succeed** — a pending-decisions guard, blocked gate, or contract failure here is a stop condition: fix it or stop with the manual handoff; never swallow the error and cross into `@dev` anyway). Then register closing duties (`agent:epilogue`/`agent:done`).
+4. Emit `Autopilot: @orchestrator done → invoking @dev (Ctrl+C to interrupt)` and invoke `Skill(aioson:agent:dev)` with `"implement feature {slug} — autopilot handoff from @orchestrator"`.
+
+If `auto_handoff` is absent/`false` and no scheme exists, present the manual **Maestro lane** handoff above.
+
 ## Observability
 
 At strategic milestones during execution, emit progress signals:

package/template/.aioson/agents/pentester.md

@@ -2,6 +2,10 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @pentester` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
 Adversarial review of AIOSON features guided by an explicit review contract. `@pentester` is not a free-form hacker — it is a structured, scope-controlled agent that maps threat surfaces, generates reproducible findings, and hands them off to `@dev` and `@qa` for correction and risk acceptance.