@jaimevalasek/aioson 1.21.8 → 1.23.0

package/src/harness/scope-guard.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Scope guard do self:loop (loop-guardrails REQ-4/5/6 + REQ-10).
+ *
+ * Módulo puro: recebe o changed set (já calculado por git-baseline) e o
+ * contrato RESOLVIDO (contract-schema.resolveContract — defaults proibidos já
+ * mesclados). Não faz I/O.
+ *
+ * Precedência (REQ-5): deny vence allow — path que casa `forbidden_files` é
+ * violação mesmo casando `allowed_files`. Defaults proibidos são sempre
+ * aplicados (REQ-4) porque vêm mesclados do resolveContract.
+ */
+
+const { matchAny } = require('./glob-match');
+
+/**
+ * @param {object} params
+ * @param {Array<{path, status}>} params.changedFiles — changed set da tentativa
+ * @param {Array<{path, reason}>} [params.rehashViolations] — D2 (git-baseline)
+ * @param {string[]|null} params.allowedGlobs — null = sem allowlist
+ * @param {string[]} params.forbiddenGlobs — já mesclados com defaults
+ * @returns {{ ok: boolean, violations: Array<{path, status, glob, reason}> }}
+ */
+function checkScope({ changedFiles = [], rehashViolations = [], allowedGlobs = null, forbiddenGlobs = [] }) {
+  const violations = [];
+
+  for (const file of changedFiles) {
+    const forbiddenMatch = matchAny(forbiddenGlobs, file.path);
+    if (forbiddenMatch) {
+      violations.push({
+        path: file.path,
+        status: file.status,
+        glob: forbiddenMatch,
+        reason: `matches forbidden glob "${forbiddenMatch}"${file.status === 'deleted' ? ' (deletion counts — EC-4)' : ''}`
+      });
+      continue; // deny vence allow (REQ-5)
+    }
+    if (allowedGlobs && !matchAny(allowedGlobs, file.path)) {
+      violations.push({
+        path: file.path,
+        status: file.status,
+        glob: null,
+        reason: 'outside allowed_files allowlist'
+      });
+    }
+  }
+
+  for (const rehash of rehashViolations) {
+    violations.push({
+      path: rehash.path,
+      status: 'modified',
+      glob: null,
+      reason: rehash.reason
+    });
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/** Conta linhas efetivas de diff (+/− excluindo headers +++/---). */
+function countDiffLines(diffPatch) {
+  if (!diffPatch) return 0;
+  let count = 0;
+  for (const line of String(diffPatch).split('\n')) {
+    if ((line.startsWith('+') && !line.startsWith('+++')) ||
+        (line.startsWith('-') && !line.startsWith('---'))) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Limites de diff (REQ-10, should-have). Avaliados sobre o MESMO conjunto do
+ * scope guard. `null`/`undefined` = sem limite.
+ *
+ * @returns {{ ok: boolean, exceeded: Array<{limit, actual, max}> }}
+ */
+function checkDiffLimits({ changedFiles = [], diffPatch = '', maxChangedFiles = null, maxDiffLines = null }) {
+  const exceeded = [];
+
+  if (Number.isInteger(maxChangedFiles) && maxChangedFiles > 0 && changedFiles.length > maxChangedFiles) {
+    exceeded.push({ limit: 'max_changed_files', actual: changedFiles.length, max: maxChangedFiles });
+  }
+
+  if (Number.isInteger(maxDiffLines) && maxDiffLines > 0) {
+    const actual = countDiffLines(diffPatch);
+    if (actual > maxDiffLines) {
+      exceeded.push({ limit: 'max_diff_lines', actual, max: maxDiffLines });
+    }
+  }
+
+  return { ok: exceeded.length === 0, exceeded };
+}
+
+/**
+ * Feedback de reparo/rollback injetado na próxima iteração após violação
+ * (REQ-6). Texto direto para o agente: reverter os paths e permanecer no escopo.
+ */
+function buildRollbackFeedback(violations) {
+  const lines = violations.slice(0, 10).map((v) => `  - ${v.path} (${v.reason})`);
+  return [
+    'SCOPE VIOLATION — files were changed outside the contract scope:',
+    ...lines,
+    'Revert these changes (git checkout -- <path> / delete untracked files) and redo the task touching ONLY files inside the allowed scope.'
+  ].join('\n');
+}
+
+module.exports = {
+  checkScope,
+  checkDiffLimits,
+  countDiffLines,
+  buildRollbackFeedback
+};

package/src/i18n/messages/en.js

@@ -150,6 +150,27 @@ module.exports = {
       'aioson harness:init [path] --slug=<slug> [--mode=BALANCED|URGENT|ECONOMICAL] [--locale=en]',
     help_harness_validate:
       'aioson harness:validate [path] --slug=<slug> [--artifact=<path>] [--locale=en]',
+    help_harness_retro:
+      'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=en]',
+    help_harness_preview:
+      'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=en]',
+    harnessRetro: {
+      need_target: 'harness:retro requires --feature=<slug> or --last=<N>.',
+      invalid_slug: 'Invalid slug: {slug} (must match ^[a-z0-9][a-z0-9-]*$).',
+      invalid_last: 'Invalid --last value: {value} (use an integer >= 1).',
+      feature_not_found: 'Feature not found: {slug} (searched .aioson/context/, .aioson/plans/{slug}/, .aioson/context/features/{slug}/, .aioson/context/done/{slug}/).',
+      no_closed_features: 'No closed features under .aioson/context/done/ to mine.',
+      written: 'Retro dossier written: {path} ({candidates} candidates, {observations} observations).',
+      empty: 'Retro dossier written with no proposals: {path} (no minable trail).',
+      io_error: 'I/O error writing the dossier: {error}',
+      window_truncated: '--last={n} exceeds available features ({available}); mining all of them.',
+      undatable_excluded: '{count} feature(s) without a resolvable PASS date excluded from the window: {slugs}'
+    },
+    harnessPreview: {
+      file_required: 'harness:preview requires a <file> path argument.',
+      not_found: 'File not found: {path}',
+      read_error: 'Could not read file: {path} ({error})'
+    },
     help_web_map:
       'aioson web:map [path] --url=<url> [--depth=<N>] [--max-pages=<N>] [--include-external] [--json] [--locale=en]',
     help_web_scrape:
@@ -450,6 +471,8 @@ module.exports = {
     bootstrap_coverage_hint_seed: 'Run /discover to seed .aioson/context/bootstrap/{what-is,how-it-works,what-it-does,current-state}.md',
     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.',
     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

@@ -136,6 +136,27 @@ module.exports = {
       'aioson qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json] [--locale=es]',
     help_qa_report:
       'aioson qa:report [path] [--html] [--json] [--locale=es]',
+    help_harness_retro:
+      'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=es]',
+    help_harness_preview:
+      'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=es]',
+    harnessRetro: {
+      need_target: 'harness:retro requiere --feature=<slug> o --last=<N>.',
+      invalid_slug: 'Slug inválido: {slug} (debe cumplir ^[a-z0-9][a-z0-9-]*$).',
+      invalid_last: 'Valor inválido para --last: {value} (use un entero >= 1).',
+      feature_not_found: 'Feature no encontrada: {slug} (buscado en .aioson/context/, .aioson/plans/{slug}/, .aioson/context/features/{slug}/, .aioson/context/done/{slug}/).',
+      no_closed_features: 'No hay features cerradas en .aioson/context/done/ para minar.',
+      written: 'Dosier retrospectivo generado: {path} ({candidates} candidatos, {observations} observaciones).',
+      empty: 'Dosier generado sin propuestas: {path} (fuentes sin rastro minable).',
+      io_error: 'Error de E/S al escribir el dosier: {error}',
+      window_truncated: '--last={n} supera las features disponibles ({available}); minando todas.',
+      undatable_excluded: '{count} feature(s) sin fecha de PASS resoluble excluida(s) de la ventana: {slugs}'
+    },
+    harnessPreview: {
+      file_required: 'harness:preview requiere una ruta de archivo <file>.',
+      not_found: 'Archivo no encontrado: {path}',
+      read_error: 'No se pudo leer el archivo: {path} ({error})'
+    },
     help_web_map:
       'aioson web:map [path] --url=<url> [--depth=<N>] [--max-pages=<N>] [--include-external] [--json] [--locale=es]',
     help_web_scrape:
@@ -160,12 +181,12 @@ module.exports = {
       'aioson squad:pipeline [path] [--sub=list|show|status] [--pipeline=<slug>] [--locale=es]',
     help_squad_investigate:
       'aioson squad:investigate [path] [--sub=list|show|score|link|register] [--investigation=<slug>] [--squad=<slug>] [--locale=es]',
-    help_squad_learning:
-      'aioson squad:learning [path] [--sub=list|stats|archive|promote|export] [--squad=<slug>] [--status=<status>] [--locale=es]',
-    help_quality_audit:
-      'aioson quality:audit [path] [--feature=<slug>] [--provider-output=<path>] [--baseline=<path>] [--changed=<path[,path]>] [--json] [--locale=es]',
-    help_squad_dashboard:
-      'aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=es]',
+    help_squad_learning:
+      'aioson squad:learning [path] [--sub=list|stats|archive|promote|export] [--squad=<slug>] [--status=<status>] [--locale=es]',
+    help_quality_audit:
+      'aioson quality:audit [path] [--feature=<slug>] [--provider-output=<path>] [--baseline=<path>] [--changed=<path[,path]>] [--json] [--locale=es]',
+    help_squad_dashboard:
+      'aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=es]',
     help_squad_worker:
       'aioson squad:worker [path] [--sub=list|run|test|logs|scaffold] [--squad=<slug>] [--worker=<slug>] [--input=<json>] [--locale=es]',
     help_squad_daemon:
@@ -179,7 +200,7 @@ module.exports = {
     help_commit_prepare:
       'aioson commit:prepare [path] [--staged-only] [--agent-safe] [--mode=guarded|trusted|headless] [--json] [--locale=es]',
     help_learning:
-      'aioson learning [path] [--sub=list|stats|promote|import-from-claude] [--status=<status>] [--id=<learning-id>] [--project-hash=<hash>] [--dry-run] [--select=<n[,n]|all>] [--locale=es]',
+      'aioson learning [path] [--sub=list|stats|promote|import-from-claude] [--status=<status>] [--id=<learning-id>] [--project-hash=<hash>] [--dry-run] [--select=<n[,n]|all>] [--locale=es]',
     dashboard_moved:
       'El flujo `{command}` fue eliminado del CLI. El dashboard de AIOSON ahora se instala por separado. Abre la app del dashboard en tu computadora, crea o agrega un proyecto y selecciona la carpeta que ya contiene `.aioson/`.',
     dashboard_moved_line: '{message}\n',
@@ -324,6 +345,8 @@ module.exports = {
     bootstrap_coverage_hint_seed: 'Ejecute /discover para sembrar .aioson/context/bootstrap/{what-is,how-it-works,what-it-does,current-state}.md',
     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.',
     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})',
@@ -609,7 +632,7 @@ module.exports = {
     note_product_optional:
       '@product es opcional para MICRO — omitelo y ve directo a @dev si la idea ya esta clara.',
     note_feature_flow:
-      'Flujo para nueva feature (tras la configuracion inicial): @product → @analyst → @scope-check → @dev → @qa. Sin @setup.'
+      'Flujo para nueva feature (tras la configuracion inicial): @product → @analyst → @scope-check → @dev → @qa. Sin @setup.'
   },
   parallel_init: {
     context_missing:
@@ -1020,7 +1043,7 @@ module.exports = {
     folder_required_example_prompt:
       '  Prompt listo    : aioson agent:prompt analyst --tool=codex',
     folder_required_example_next:
-      '  Flujo tras escaneo completo: @analyst -> @scope-check -> @architect -> @dev',
+      '  Flujo tras escaneo completo: @analyst -> @scope-check -> @architect -> @dev',
     folder_not_found: 'La carpeta "{folder}" no existe en este proyecto. Directorios de nivel superior detectados: {available}',
     config_missing: '{file} no encontrado. Para usar el modo con LLM, copia aioson-models.json y completa tus claves de API.',
     config_invalid: 'JSON invalido en aioson-models.json: {error}',

package/src/i18n/messages/fr.js

@@ -136,6 +136,27 @@ module.exports = {
       'aioson qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json] [--locale=fr]',
     help_qa_report:
       'aioson qa:report [path] [--html] [--json] [--locale=fr]',
+    help_harness_retro:
+      'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=fr]',
+    help_harness_preview:
+      'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=fr]',
+    harnessRetro: {
+      need_target: 'harness:retro requiert --feature=<slug> ou --last=<N>.',
+      invalid_slug: 'Slug invalide : {slug} (doit correspondre à ^[a-z0-9][a-z0-9-]*$).',
+      invalid_last: 'Valeur --last invalide : {value} (utilisez un entier >= 1).',
+      feature_not_found: 'Feature introuvable : {slug} (cherché dans .aioson/context/, .aioson/plans/{slug}/, .aioson/context/features/{slug}/, .aioson/context/done/{slug}/).',
+      no_closed_features: 'Aucune feature clôturée dans .aioson/context/done/ à miner.',
+      written: 'Dossier rétrospectif généré : {path} ({candidates} candidats, {observations} observations).',
+      empty: 'Dossier généré sans propositions : {path} (sources sans piste exploitable).',
+      io_error: 'Erreur d’E/S lors de l’écriture du dossier : {error}',
+      window_truncated: '--last={n} dépasse les features disponibles ({available}) ; minage de toutes.',
+      undatable_excluded: '{count} feature(s) sans date de PASS résoluble exclue(s) de la fenêtre : {slugs}'
+    },
+    harnessPreview: {
+      file_required: 'harness:preview requiert un chemin de fichier <file>.',
+      not_found: 'Fichier introuvable : {path}',
+      read_error: 'Impossible de lire le fichier : {path} ({error})'
+    },
     help_web_map:
       'aioson web:map [path] --url=<url> [--depth=<N>] [--max-pages=<N>] [--include-external] [--json] [--locale=fr]',
     help_web_scrape:
@@ -160,12 +181,12 @@ module.exports = {
       'aioson squad:pipeline [path] [--sub=list|show|status] [--pipeline=<slug>] [--locale=fr]',
     help_squad_investigate:
       'aioson squad:investigate [path] [--sub=list|show|score|link|register] [--investigation=<slug>] [--squad=<slug>] [--locale=fr]',
-    help_squad_learning:
-      'aioson squad:learning [path] [--sub=list|stats|archive|promote|export] [--squad=<slug>] [--status=<status>] [--locale=fr]',
-    help_quality_audit:
-      'aioson quality:audit [path] [--feature=<slug>] [--provider-output=<path>] [--baseline=<path>] [--changed=<path[,path]>] [--json] [--locale=fr]',
-    help_squad_dashboard:
-      'aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=fr]',
+    help_squad_learning:
+      'aioson squad:learning [path] [--sub=list|stats|archive|promote|export] [--squad=<slug>] [--status=<status>] [--locale=fr]',
+    help_quality_audit:
+      'aioson quality:audit [path] [--feature=<slug>] [--provider-output=<path>] [--baseline=<path>] [--changed=<path[,path]>] [--json] [--locale=fr]',
+    help_squad_dashboard:
+      'aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=fr]',
     help_squad_worker:
       'aioson squad:worker [path] [--sub=list|run|test|logs|scaffold] [--squad=<slug>] [--worker=<slug>] [--input=<json>] [--locale=fr]',
     help_squad_daemon:
@@ -179,7 +200,7 @@ module.exports = {
     help_commit_prepare:
       'aioson commit:prepare [path] [--staged-only] [--agent-safe] [--mode=guarded|trusted|headless] [--json] [--locale=fr]',
     help_learning:
-      'aioson learning [path] [--sub=list|stats|promote|import-from-claude] [--status=<status>] [--id=<learning-id>] [--project-hash=<hash>] [--dry-run] [--select=<n[,n]|all>] [--locale=fr]',
+      'aioson learning [path] [--sub=list|stats|promote|import-from-claude] [--status=<status>] [--id=<learning-id>] [--project-hash=<hash>] [--dry-run] [--select=<n[,n]|all>] [--locale=fr]',
     dashboard_moved:
       'Le flux `{command}` a été supprimé du CLI. Le dashboard AIOSON est désormais installé séparément. Ouvrez l application dashboard sur votre ordinateur, créez ou ajoutez un projet, puis sélectionnez le dossier qui contient déjà `.aioson/`.',
     dashboard_moved_line: '{message}\n',
@@ -323,6 +344,8 @@ module.exports = {
     bootstrap_coverage_hint_seed: 'Executez /discover pour creer .aioson/context/bootstrap/{what-is,how-it-works,what-it-does,current-state}.md',
     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.',
     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})',
@@ -612,7 +635,7 @@ module.exports = {
     note_product_optional:
       '@product est optionnel pour MICRO — passez directement a @dev si l idee est deja claire.',
     note_feature_flow:
-      'Flux nouvelle feature (apres configuration initiale) : @product → @analyst → @scope-check → @dev → @qa. Pas de @setup.'
+      'Flux nouvelle feature (apres configuration initiale) : @product → @analyst → @scope-check → @dev → @qa. Pas de @setup.'
   },
   parallel_init: {
     context_missing:
@@ -1028,7 +1051,7 @@ module.exports = {
     folder_required_example_prompt:
       '  Prompt pret     : aioson agent:prompt analyst --tool=codex',
     folder_required_example_next:
-      '  Workflow apres scan complet : @analyst -> @scope-check -> @architect -> @dev',
+      '  Workflow apres scan complet : @analyst -> @scope-check -> @architect -> @dev',
     folder_not_found: 'Le dossier "{folder}" est introuvable dans ce projet. Dossiers de premier niveau detectes : {available}',
     config_missing: '{file} introuvable. Pour utiliser le mode LLM, copiez aioson-models.json et renseignez vos cles API.',
     config_invalid: 'JSON invalide dans aioson-models.json : {error}',

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

@@ -152,6 +152,27 @@ module.exports = {
       'aioson harness:init [path] --slug=<slug> [--mode=BALANCED|URGENT|ECONOMICAL] [--locale=pt-BR]',
     help_harness_validate:
       'aioson harness:validate [path] --slug=<slug> [--artifact=<path>] [--locale=pt-BR]',
+    help_harness_retro:
+      'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=pt-BR]',
+    help_harness_preview:
+      'aioson harness:preview <file> [--max-bytes=8192] [--json] [--locale=pt-BR]',
+    harnessRetro: {
+      need_target: 'harness:retro requer --feature=<slug> ou --last=<N>.',
+      invalid_slug: 'Slug inválido: {slug} (deve casar ^[a-z0-9][a-z0-9-]*$).',
+      invalid_last: 'Valor inválido para --last: {value} (use inteiro >= 1).',
+      feature_not_found: 'Feature não encontrada: {slug} (procurado em .aioson/context/, .aioson/plans/{slug}/, .aioson/context/features/{slug}/, .aioson/context/done/{slug}/).',
+      no_closed_features: 'Nenhuma feature fechada em .aioson/context/done/ para minerar.',
+      written: 'Dossiê retrospectivo gerado: {path} ({candidates} candidatos, {observations} observações).',
+      empty: 'Dossiê gerado sem propostas: {path} (fontes sem trilha minerável).',
+      io_error: 'Erro de I/O ao escrever o dossiê: {error}',
+      window_truncated: '--last={n} excede features disponíveis ({available}); minerando todas.',
+      undatable_excluded: '{count} feature(s) sem data de PASS determinável excluída(s) da janela: {slugs}'
+    },
+    harnessPreview: {
+      file_required: 'harness:preview requer um caminho de arquivo <file>.',
+      not_found: 'Arquivo não encontrado: {path}',
+      read_error: 'Não foi possível ler o arquivo: {path} ({error})'
+    },
     help_web_map:
       'aioson web:map [path] --url=<url> [--depth=<N>] [--max-pages=<N>] [--include-external] [--json] [--locale=pt-BR]',
     help_web_scrape:
@@ -424,6 +445,8 @@ module.exports = {
     bootstrap_coverage_hint_seed: 'Rode /discover para criar .aioson/context/bootstrap/{what-is,how-it-works,what-it-does,current-state}.md',
     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.',
     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/dev-resume.js

@@ -49,34 +49,34 @@ function readClassificationFromFrontmatters(rawList) {
   return null;
 }
 
-function extractDevStateFields(raw) {
-  if (!raw) return { active_feature: null, active_phase: null, next_step: null, status: null };
-  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!fmMatch) return { active_feature: null, active_phase: null, next_step: null, status: null };
-  const fm = {};
-  for (const line of fmMatch[1].split(/\r?\n/)) {
+function extractDevStateFields(raw) {
+  if (!raw) return { active_feature: null, active_phase: null, next_step: null, status: null };
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return { active_feature: null, active_phase: null, next_step: null, status: null };
+  const fm = {};
+  for (const line of fmMatch[1].split(/\r?\n/)) {
     const idx = line.indexOf(':');
     if (idx === -1) continue;
     const key = line.slice(0, idx).trim();
     const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
     fm[key] = val;
-  }
-  return {
-    active_feature: fm.active_feature || null,
-    active_phase: fm.active_phase || null,
-    next_step: fm.next_step || null,
-    status: fm.status || null
-  };
-}
-
-function isCurrentDevStateForFeature(fields, featureSlug) {
-  if (!fields) return false;
-  if (!fields.active_feature) return false;
-  const status = String(fields.status || '').toLowerCase();
-  if (status === 'done' || status === 'abandoned') return false;
-  if (fields.active_feature !== featureSlug) return false;
-  return true;
-}
+  }
+  return {
+    active_feature: fm.active_feature || null,
+    active_phase: fm.active_phase || null,
+    next_step: fm.next_step || null,
+    status: fm.status || null
+  };
+}
+
+function isCurrentDevStateForFeature(fields, featureSlug) {
+  if (!fields) return false;
+  if (!fields.active_feature) return false;
+  const status = String(fields.status || '').toLowerCase();
+  if (status === 'done' || status === 'abandoned') return false;
+  if (fields.active_feature !== featureSlug) return false;
+  return true;
+}
 
 function extractCodeMapPaths(dossierRaw) {
   if (!dossierRaw) return [];
@@ -91,6 +91,42 @@ function extractCodeMapPaths(dossierRaw) {
   return Array.from(new Set(paths));
 }
 
+function readCorrectionsStatus(raw) {
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  // No frontmatter or no status field: treat as open — a corrections plan
+  // must never be silently skipped because of a malformed header.
+  if (!fmMatch) return 'open';
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const m = line.match(/^status:\s*([^#]*)/);
+    if (m) {
+      const val = m[1].trim().replace(/^["']|["']$/g, '').toLowerCase();
+      return val || 'open';
+    }
+  }
+  return 'open';
+}
+
+async function listOpenCorrections(targetDir, featureSlug) {
+  const planDir = path.join(targetDir, '.aioson', 'plans', featureSlug);
+  let entries;
+  try {
+    entries = await fs.readdir(planDir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const name of entries.filter((n) => /^corrections-.+\.md$/.test(n)).sort()) {
+    const raw = await readFileOrNull(path.join(planDir, name));
+    if (!raw) continue;
+    const status = readCorrectionsStatus(raw);
+    if (status === 'open' || status === 'in_progress') {
+      out.push(`.aioson/plans/${featureSlug}/${name}`);
+    }
+  }
+  return out;
+}
+
 function deriveNextStepFromPlan(planRaw) {
   if (!planRaw) return null;
   const lines = planRaw.split('\n');
@@ -121,12 +157,12 @@ async function buildDevResumeData(projectPath) {
   const specRaw = await readFileOrNull(path.join(ctxDir, `spec-${featureSlug}.md`));
   const classification = readClassificationFromFrontmatters([dossierRaw, prdRaw, specRaw]);
 
-  const devStateRaw = await readFileOrNull(path.join(ctxDir, 'dev-state.md'));
-  const devStateFields = extractDevStateFields(devStateRaw);
-  const useDevState = isCurrentDevStateForFeature(devStateFields, featureSlug);
-
-  const planManifestPath = path.join(targetDir, '.aioson', 'plans', featureSlug, 'manifest.md');
-  const planRaw = await readFileOrNull(planManifestPath);
+  const devStateRaw = await readFileOrNull(path.join(ctxDir, 'dev-state.md'));
+  const devStateFields = extractDevStateFields(devStateRaw);
+  const useDevState = isCurrentDevStateForFeature(devStateFields, featureSlug);
+
+  const planManifestPath = path.join(targetDir, '.aioson', 'plans', featureSlug, 'manifest.md');
+  const planRaw = await readFileOrNull(planManifestPath);
   const sheldonPlan = planRaw ? `.aioson/plans/${featureSlug}/manifest.md` : null;
 
   const artifactsConsumed = Array.isArray(lastHandoff && lastHandoff.artifact_uris)
@@ -137,22 +173,35 @@ async function buildDevResumeData(projectPath) {
     ? lastHandoff.decision_rationale
     : [];
 
+  // QA corrections plans with status open/in_progress take precedence over any
+  // persisted next_step: a stale dev-state pointer must not hide mandatory
+  // corrections from a fresh @dev session (loop-guardrails incident, 2026-06-09).
+  const openCorrections = await listOpenCorrections(targetDir, featureSlug);
+  const baseNextStep = useDevState && devStateFields.next_step
+    ? devStateFields.next_step
+    : deriveNextStepFromPlan(planRaw);
+
   return {
-    feature_slug: featureSlug,
-    classification,
-    current_phase: useDevState && devStateFields.active_phase ? devStateFields.active_phase : 'unknown',
-    artifacts_consumed: artifactsConsumed,
-    code_map_paths: extractCodeMapPaths(dossierRaw),
-    sheldon_plan: sheldonPlan,
-    next_step: useDevState && devStateFields.next_step ? devStateFields.next_step : deriveNextStepFromPlan(planRaw),
-    decision_rationale: decisionRationale.length > 0 ? decisionRationale : undefined
-  };
-}
+    feature_slug: featureSlug,
+    classification,
+    current_phase: useDevState && devStateFields.active_phase ? devStateFields.active_phase : 'unknown',
+    artifacts_consumed: artifactsConsumed,
+    code_map_paths: extractCodeMapPaths(dossierRaw),
+    sheldon_plan: sheldonPlan,
+    next_step: openCorrections.length > 0
+      ? `Apply mandatory corrections from ${openCorrections[0]}, then return to @qa for re-verification`
+      : baseNextStep,
+    open_corrections: openCorrections.length > 0 ? openCorrections : undefined,
+    decision_rationale: decisionRationale.length > 0 ? decisionRationale : undefined
+  };
+}
 
 module.exports = {
-  buildDevResumeData,
-  extractDevStateFields,
-  isCurrentDevStateForFeature,
-  extractCodeMapPaths,
-  deriveNextStepFromPlan
-};
+  buildDevResumeData,
+  extractDevStateFields,
+  isCurrentDevStateForFeature,
+  extractCodeMapPaths,
+  deriveNextStepFromPlan,
+  readCorrectionsStatus,
+  listOpenCorrections
+};