@jaimevalasek/aioson 1.36.0 → 1.37.0

package/src/doctor.js

@@ -228,8 +228,10 @@ async function runDoctor(targetDir) {
   }
 
   // Autopilot handoff: protocol doc installed but flag never declared in the
-  // context frontmatter — autopilot stays silently inactive (absent = manual
-  // handoffs). An explicit true/false is a deliberate choice and passes.
+  // context frontmatter. Absent is no longer "silently manual" — @product asks
+  // the run mode on screen at each feature kickoff. Declaring an explicit
+  // true/false sets a project default (skip the kickoff question) and passes;
+  // the advisory just surfaces that a default can be set.
   const autopilotDocExists = await exists(path.join(targetDir, '.aioson/docs/autopilot-handoff.md'));
   if (autopilotDocExists && contextValidation.exists && contextValidation.data) {
     const autoHandoffDeclared = Object.prototype.hasOwnProperty.call(contextValidation.data, 'auto_handoff');

package/src/i18n/messages/en.js

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

package/src/i18n/messages/es.js

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

package/src/i18n/messages/fr.js

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

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

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

package/src/lib/briefing-refiner/apply-feedback.js

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

package/src/lib/briefing-refiner/feedback-schema.js

@@ -7,6 +7,12 @@ const VALID_SECTION_STATUSES = new Set(['unchanged', 'accepted', 'change_request
 const VALID_DECISION_STATUSES = new Set(['accepted', 'change_requested', 'remove', 'blocked', 'note']);
 const VALID_SEVERITIES = new Set(['note', 'suggestion', 'important', 'blocking']);
 const VALID_EXPORT_METHODS = new Set(['file-system-access', 'download', 'copy-paste', 'manual-save']);
+const VALID_FINDING_CATEGORIES = new Set(['ambiguity', 'redundancy', 'gap', 'risk', 'pending-decision', 'scope-suggestion']);
+const VALID_FINDING_SEVERITIES = new Set(['low', 'medium', 'high']);
+const VALID_FINDING_STATUSES = new Set(['pending', 'accepted', 'rejected', 'deferred']);
+// 1.0 = sections/comments/decisions/blocking_items only; 1.1 adds findings[] (the
+// agent's audit surfaced as reviewable items) and the refinement round counter.
+const SUPPORTED_SCHEMA_VERSIONS = new Set(['1.0', '1.1']);
 
 // Normalization only — NOT a security boundary. This strips well-formed tags
 // and normalizes newlines so the text round-trips cleanly into briefings.md.
@@ -34,17 +40,64 @@ function normalizeSection(section) {
   };
 }
 
-function buildInitialFeedback({ slug, sourcePath, sourceHash, sections, exportMethod = 'manual-save', now = new Date() }) {
+function normalizeFinding(finding, index) {
+  return {
+    id: String(finding.id || `F${index + 1}`),
+    section_id: String(finding.section_id || ''),
+    category: VALID_FINDING_CATEGORIES.has(finding.category) ? finding.category : 'gap',
+    severity: VALID_FINDING_SEVERITIES.has(finding.severity) ? finding.severity : 'medium',
+    blocking: Boolean(finding.blocking),
+    text: sanitizeText(finding.text),
+    recommendation: sanitizeText(finding.recommendation || ''),
+    status: VALID_FINDING_STATUSES.has(finding.status) ? finding.status : 'pending',
+    note: sanitizeText(finding.note || '')
+  };
+}
+
+/**
+ * Validate agent-supplied audit findings BEFORE they are baked into the review
+ * surface. Strict where normalizeFinding is lenient: the agent must name a real
+ * section and a valid category, and every finding must carry text.
+ */
+function validateFindingsInput(findings, { sectionIds = [] } = {}) {
+  const errors = [];
+  if (!Array.isArray(findings)) {
+    return { ok: false, errors: ['findings must be an array'] };
+  }
+  const known = new Set(sectionIds);
+  findings.forEach((finding, index) => {
+    const label = finding && finding.id ? String(finding.id) : `#${index + 1}`;
+    if (!finding || typeof finding !== 'object') {
+      errors.push(`finding ${label} must be an object`);
+      return;
+    }
+    if (!String(finding.text || '').trim()) errors.push(`finding ${label} has no text`);
+    if (!VALID_FINDING_CATEGORIES.has(finding.category)) {
+      errors.push(`finding ${label} has invalid category: ${finding.category}`);
+    }
+    if (finding.severity !== undefined && !VALID_FINDING_SEVERITIES.has(finding.severity)) {
+      errors.push(`finding ${label} has invalid severity: ${finding.severity}`);
+    }
+    if (known.size > 0 && !known.has(String(finding.section_id || ''))) {
+      errors.push(`finding ${label} points at unknown section_id: ${finding.section_id}`);
+    }
+  });
+  return { ok: errors.length === 0, errors };
+}
+
+function buildInitialFeedback({ slug, sourcePath, sourceHash, sections, findings = [], round = 1, exportMethod = 'manual-save', now = new Date() }) {
   const timestamp = now.toISOString();
   return {
-    schema_version: '1.0',
+    schema_version: '1.1',
     briefing_slug: slug,
     source_briefing_path: sourcePath,
     source_hash: sourceHash,
     review_generated_at: timestamp,
     last_modified_at: timestamp,
     export_method: exportMethod,
+    round: Number.isInteger(round) && round > 0 ? round : 1,
     sections: sections.map(normalizeSection),
+    findings: findings.map(normalizeFinding),
     comments: [],
     decisions: [],
     blocking_items: []
@@ -66,7 +119,7 @@ function validateFeedback(feedback, { slug, currentSourceHash, allowStale = fals
   if (!feedback || typeof feedback !== 'object') errors.push('feedback must be an object');
   if (errors.length > 0) return { ok: false, stale: false, errors, warnings };
 
-  if (feedback.schema_version !== '1.0') errors.push('schema_version must be 1.0');
+  if (!SUPPORTED_SCHEMA_VERSIONS.has(feedback.schema_version)) errors.push('schema_version must be 1.0 or 1.1');
   if (slug && feedback.briefing_slug !== slug) errors.push('briefing_slug does not match selected slug');
   if (!isPathInsideBriefing(feedback.source_briefing_path, feedback.briefing_slug || slug)) {
     errors.push('source_briefing_path must stay inside the selected briefing directory');
@@ -99,6 +152,17 @@ function validateFeedback(feedback, { slug, currentSourceHash, allowStale = fals
     }
   }
 
+  // findings[] is a 1.1 field; a 1.0 payload legitimately has none.
+  if (feedback.schema_version === '1.1' && !Array.isArray(feedback.findings)) {
+    errors.push('findings must be an array');
+  }
+  if (Array.isArray(feedback.findings)) {
+    for (const finding of feedback.findings) {
+      if (!VALID_FINDING_STATUSES.has(finding.status)) errors.push(`invalid finding status: ${finding.status}`);
+      if (!VALID_FINDING_CATEGORIES.has(finding.category)) errors.push(`invalid finding category: ${finding.category}`);
+    }
+  }
+
   const stale = Boolean(currentSourceHash && feedback.source_hash !== currentSourceHash);
   if (stale) warnings.push('source_hash differs from current briefings.md');
   if (stale && !allowStale) errors.push('feedback is stale');
@@ -116,7 +180,12 @@ function assertFeedbackPath(projectDir, slug, candidatePath) {
 
 module.exports = {
   buildInitialFeedback,
+  normalizeFinding,
   sanitizeText,
   validateFeedback,
-  assertFeedbackPath
+  validateFindingsInput,
+  assertFeedbackPath,
+  VALID_FINDING_CATEGORIES,
+  VALID_FINDING_SEVERITIES,
+  VALID_FINDING_STATUSES
 };

package/src/lib/briefing-refiner/refinement-report.js

@@ -7,6 +7,15 @@ function list(items, formatter) {
 
 function buildRefinementReport(data) {
   const nextAction = data.next_action || 'rerun_review';
+  const findings = Array.isArray(data.findings) ? data.findings : [];
+  const findingsBlock = findings.length > 0
+    ? [
+        '## Findings',
+        '',
+        list(findings, (finding) => `${finding.id} [${finding.category}/${finding.severity}${finding.blocking ? '/blocking' : ''}] (${finding.status}) ${finding.section_id}: ${finding.text}`),
+        ''
+      ]
+    : [];
   return [
     `# Refinement Report — ${data.briefing_slug}`,
     '',
@@ -15,8 +24,10 @@ function buildRefinementReport(data) {
     `- Source hash: ${data.source_hash || '-'}`,
     `- Applied hash: ${data.applied_hash || '-'}`,
     `- Status: ${data.status || 'review_generated'}`,
+    `- Round: ${data.round || 1}`,
     `- Next action: ${nextAction}`,
     '',
+    ...findingsBlock,
     '## Applied Changes',
     '',
     list(data.applied_changes, (change) => `${change.section_id || change.title}: ${change.summary || 'updated'}`),