@jaimevalasek/aioson 1.22.0 → 1.23.1

package/src/i18n/messages/en.js

@@ -21,12 +21,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agent> --summary=<text> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<text>] [--paths=<path[,path2]>] [--feature=<slug>] [--json] [--locale=en]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=en]',
     help_chain_audit:
       'aioson chain:audit <file> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=en]',
@@ -118,8 +122,10 @@ module.exports = {
       'aioson workflow:next [path] [--complete[=<agent>]] [--agent=<agent>] [--skip=<agent>] [--status] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=en]',
     help_workflow_status:
       'aioson workflow:status [path] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=en]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=en]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=en]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=en]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=en]',
     help_parallel_doctor:
@@ -150,6 +156,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:

package/src/i18n/messages/es.js

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=es]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<ruta[,ruta2]>] [--feature=<slug>] [--json] [--locale=es]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nombre> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=es]',
     help_chain_audit:
       'aioson chain:audit <archivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=es]',
@@ -108,8 +112,10 @@ module.exports = {
       'aioson test:package [source-path] [--keep] [--dry-run] [--json] [--locale=es]',
     help_workflow_plan:
       'aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json] [--locale=es]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=es]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=es]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=es]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=es]',
     help_parallel_doctor:
@@ -136,6 +142,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:

package/src/i18n/messages/fr.js

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agent> --summary=<texte> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=fr]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agent>] [--mode=planning|executing] [--task=<texte>] [--paths=<chemin[,chemin2]>] [--feature=<slug>] [--json] [--locale=fr]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nom> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=fr]',
     help_chain_audit:
       'aioson chain:audit <fichier> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=fr]',
@@ -108,8 +112,10 @@ module.exports = {
       'aioson test:package [source-path] [--keep] [--dry-run] [--json] [--locale=fr]',
     help_workflow_plan:
       'aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json] [--locale=fr]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=fr]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=fr]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=fr]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=fr]',
     help_parallel_doctor:
@@ -136,6 +142,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:

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

@@ -22,12 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--json] [--locale=pt-BR]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
     help_chain_audit:
       'aioson chain:audit <arquivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=pt-BR]',
@@ -120,8 +124,10 @@ module.exports = {
       'aioson workflow:next [path] [--complete[=<agente>]] [--agent=<agente>] [--skip=<agente>] [--status] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
     help_workflow_status:
       'aioson workflow:status [path] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--steps=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=pt-BR]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=pt-BR]',
     help_parallel_doctor:
@@ -152,6 +158,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:

package/src/lib/retro/retro-aggregate.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * Agregação determinística para `aioson harness:retro` (requirements §3.1/§7).
+ *
+ * Agrupa findings por CHAVE DETERMINÍSTICA EXATA — nunca por classe semântica
+ * (isso é trabalho do @sheldon). A chave inclui sempre o slug (um finding-ID
+ * como C-01 existe em quase toda feature; nunca agrupar entre features — edge 5).
+ *
+ * Critério anti-opinião (REQ-2): um grupo vira "Proposta candidata" SOMENTE se
+ *   (a) ≥2 ocorrências da mesma chave, OU
+ *   (b) ≥1 ocorrência de severidade high/critical, OU
+ *   (c) a feature tem ≥2 ciclos FAIL→PASS.
+ * Severidade `unknown` nunca satisfaz (b) sozinha; todo o resto vai para
+ * "Observações". (a) é independente de severidade — assinaturas sha1 (severidade
+ * unknown) promovem ao repetir, AC-6.
+ */
+
+const crypto = require('node:crypto');
+
+const SEVERITY_RANK = { critical: 5, high: 4, medium: 3, low: 2, info: 1, unknown: 0 };
+const PHASE_RE = /(?:[-_/]|\b)(ph\d+|phase[-_]?\d+)\b/i;
+
+function severityRank(sev) {
+  return SEVERITY_RANK[sev] ?? 0;
+}
+
+function sha1short(text) {
+  return crypto.createHash('sha1').update(String(text)).digest('hex').slice(0, 12);
+}
+
+/** Token de phase derivado do path da fonte (edge 4 — desambiguação entre phases). */
+function phaseToken(sourcePath) {
+  if (!sourcePath) return '';
+  const m = String(sourcePath).match(PHASE_RE);
+  return m ? m[1].toLowerCase().replace(/[-_]/g, '') : '';
+}
+
+/** Chave determinística exata de um finding (slug sempre incluído). */
+function groupKey(f) {
+  const phase = phaseToken(f.source_path);
+  const prefix = phase ? `${f.feature_slug}::${phase}` : f.feature_slug;
+  if (f.signature) return `${prefix}::sig:${f.signature}`;
+  if (f.finding_id) return `${prefix}::${f.finding_id}`;
+  return `${prefix}::title:${sha1short(f.title || '')}`;
+}
+
+/** Ordenação estável de ocorrências: severidade (critical→low), depois data, depois path. */
+function compareOccurrences(a, b) {
+  const sr = severityRank(b.severity) - severityRank(a.severity);
+  if (sr !== 0) return sr;
+  const da = a.date || '';
+  const db = b.date || '';
+  if (da !== db) return da < db ? -1 : 1;
+  return (a.source_path || '') < (b.source_path || '') ? -1 : (a.source_path || '') > (b.source_path || '') ? 1 : 0;
+}
+
+/**
+ * @param {object} sources — saída de `collectSources` ({ findings, cycles, cost, costByFeature })
+ * @returns {{ candidates, observations, cost }}
+ */
+function aggregate(sources) {
+  const findings = Array.isArray(sources.findings) ? sources.findings : [];
+  const cycles = Array.isArray(sources.cycles) ? sources.cycles : [];
+  const costByFeature = sources.costByFeature || {};
+
+  // Ciclos FAIL→PASS por feature (ordenados por data).
+  const cyclesByFeature = new Map();
+  for (const c of cycles) {
+    if (!cyclesByFeature.has(c.feature_slug)) cyclesByFeature.set(c.feature_slug, []);
+    cyclesByFeature.get(c.feature_slug).push(c);
+  }
+  for (const arr of cyclesByFeature.values()) {
+    arr.sort((a, b) => (a.fail_at < b.fail_at ? -1 : a.fail_at > b.fail_at ? 1 : 0));
+  }
+
+  // Agrupa findings por chave exata.
+  const groups = new Map();
+  for (const f of findings) {
+    const key = groupKey(f);
+    if (!groups.has(key)) groups.set(key, { key, feature_slug: f.feature_slug, finding_id: f.finding_id, signature: f.signature, occurrences: [] });
+    groups.get(key).occurrences.push(f);
+  }
+
+  const candidates = [];
+  const observations = [];
+
+  for (const g of groups.values()) {
+    g.occurrences.sort(compareOccurrences);
+    const maxSeverity = g.occurrences.reduce((acc, o) => (severityRank(o.severity) > severityRank(acc) ? o.severity : acc), 'unknown');
+    const occCount = g.occurrences.length;
+    const featureCycles = cyclesByFeature.get(g.feature_slug) || [];
+
+    const reasons = [];
+    if (occCount >= 2) reasons.push('recurrence');
+    if (severityRank(maxSeverity) >= severityRank('high')) reasons.push('severity');
+    if (featureCycles.length >= 2) reasons.push('fail_pass_cycle');
+
+    const feCost = costByFeature[g.feature_slug] || {};
+    const cost = {
+      occurrences: occCount,
+      corrections: g.occurrences.filter((o) => o.source_type === 'corrections').length,
+      fail_pass_cycles: featureCycles.length,
+      cycle_dates: featureCycles.map((c) => `${c.fail_at}→${c.pass_at}`),
+      execution_events: feCost.execution_events || 0,
+      corrections_bytes: feCost.corrections_bytes || 0,
+      tokens: feCost.token_count_available ? (feCost.token_total || 0) : null
+    };
+
+    if (reasons.length > 0) {
+      candidates.push({
+        key: g.key,
+        feature_slug: g.feature_slug,
+        finding_id: g.finding_id || null,
+        signature: g.signature || null,
+        max_severity: maxSeverity,
+        reasons,
+        occurrences: g.occurrences,
+        corrections_link: (g.occurrences.find((o) => o.source_type === 'corrections') || {}).source_path || null,
+        cost
+      });
+    } else {
+      // Ocorrência única Medium/Low/info/unknown → Observação (uma linha).
+      const o = g.occurrences[0];
+      observations.push({
+        key: g.key,
+        feature_slug: g.feature_slug,
+        finding_id: g.finding_id || null,
+        severity: o.severity,
+        title: o.title,
+        date: o.date,
+        source_path: o.source_path
+      });
+    }
+  }
+
+  // Candidato sintético por feature com ≥2 ciclos sem finding-âncora já candidato.
+  for (const [slug, arr] of cyclesByFeature.entries()) {
+    if (arr.length < 2) continue;
+    const alreadyCovered = candidates.some((c) => c.feature_slug === slug && c.reasons.includes('fail_pass_cycle'));
+    if (alreadyCovered) continue;
+    const feCost = costByFeature[slug] || {};
+    candidates.push({
+      key: `${slug}::cycles`,
+      feature_slug: slug,
+      finding_id: null,
+      signature: null,
+      max_severity: 'unknown',
+      reasons: ['fail_pass_cycle'],
+      occurrences: [],
+      corrections_link: null,
+      cost: {
+        occurrences: 0,
+        corrections: feCost.corrections || 0,
+        fail_pass_cycles: arr.length,
+        cycle_dates: arr.map((c) => `${c.fail_at}→${c.pass_at}`),
+        execution_events: feCost.execution_events || 0,
+        corrections_bytes: feCost.corrections_bytes || 0,
+        tokens: feCost.token_count_available ? (feCost.token_total || 0) : null
+      }
+    });
+  }
+
+  // Ordena candidatos: severidade (critical→low), depois data mais antiga, depois chave.
+  candidates.sort((a, b) => {
+    const sr = severityRank(b.max_severity) - severityRank(a.max_severity);
+    if (sr !== 0) return sr;
+    const da = (a.occurrences[0] && a.occurrences[0].date) || '';
+    const db = (b.occurrences[0] && b.occurrences[0].date) || '';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  });
+
+  // Ordena observações: severidade, depois data, depois chave.
+  observations.sort((a, b) => {
+    const sr = severityRank(b.severity) - severityRank(a.severity);
+    if (sr !== 0) return sr;
+    const da = a.date || '';
+    const db = b.date || '';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  });
+
+  return { candidates, observations, cost: sources.cost || {} };
+}
+
+module.exports = {
+  aggregate,
+  groupKey,
+  severityRank,
+  _internal: { phaseToken, compareOccurrences }
+};

package/src/lib/retro/retro-render.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * Renderiza o dossiê retrospectivo em Markdown (requirements §3.1).
+ *
+ * Saída byte-estável exceto `generated_at` (AC-4): nenhuma fonte de
+ * não-determinismo além do timestamp injetado pelo caller. As 4 seções existem
+ * SEMPRE — vazias com placeholder. O conteúdo do dossiê é um artefato em idioma
+ * fixo (pt-BR, conforme §3.1); `--locale` afeta só as mensagens de stdout.
+ */
+
+const SOURCE_ORDER = ['qa_reports', 'corrections', 'dossier_trail', 'execution_events', 'attempts', 'failure_signatures', 'devlogs'];
+
+// Defesa em profundidade (SF-01): o dossiê vira contexto do @sheldon. Texto livre
+// minerado (títulos) é apresentado como DADO inline, nunca como estrutura Markdown
+// injetável. Neutraliza newlines/controles/bidi/zero-width — impede que um título
+// forjado injete um header `## …`, um fence ``` ou um bloco de instrução no dossiê.
+// Determinístico e byte-estável: identidade sobre texto limpo (sem esses chars).
+const INJECTABLE_CHARS_RE = new RegExp(
+  '[\\u0000-\\u001F\\u007F\\u200B-\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069\\uFEFF]',
+  'g'
+);
+
+function neutralizeText(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).replace(INJECTABLE_CHARS_RE, ' ').trim();
+}
+
+function severityLabel(sev) {
+  return sev || 'unknown';
+}
+
+function fmtCost(cost) {
+  const parts = [
+    `ocorrências ${cost.occurrences}`,
+    `correções ${cost.corrections}`,
+    `ciclos FAIL→PASS ${cost.fail_pass_cycles}${cost.cycle_dates && cost.cycle_dates.length ? ` (${cost.cycle_dates.join('; ')})` : ''}`,
+    `eventos ${cost.execution_events}`,
+    `bytes corrections ${cost.corrections_bytes}`,
+    `tokens ${cost.tokens === null || cost.tokens === undefined ? 'n/d' : cost.tokens}`
+  ];
+  return parts.join(', ');
+}
+
+function renderCandidate(c) {
+  const lines = [];
+  const anchor = c.finding_id || (c.signature ? `sig:${c.signature.slice(0, 12)}` : c.key);
+  lines.push(`### ${c.key}`);
+  lines.push('');
+  lines.push(`- Âncora: ${anchor} | severidade máxima: ${severityLabel(c.max_severity)} | motivos: ${c.reasons.join(', ')}`);
+  if (c.occurrences.length > 0) {
+    lines.push(`- Ocorrências (${c.occurrences.length}):`);
+    for (const o of c.occurrences) {
+      const id = o.finding_id || (o.signature ? `sig:${o.signature.slice(0, 12)}` : '—');
+      lines.push(`  - (${o.feature_slug}, ${id}, ${severityLabel(o.severity)}, ${o.date || 'sem-data'}, ${o.source_path}, ${o.status})`);
+    }
+  } else {
+    lines.push('- Ocorrências: ciclos FAIL→PASS recorrentes (sem finding-âncora único)');
+  }
+  lines.push(`- Correções aplicadas: ${c.corrections_link || '—'}`);
+  lines.push(`- Custo de retrabalho: ${fmtCost(c.cost)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderObservation(o) {
+  const id = o.finding_id || '—';
+  return `- (${o.feature_slug}, ${id}, ${severityLabel(o.severity)}, ${o.date || 'sem-data'}) — ${neutralizeText(o.title) || id} [${o.source_path}]`;
+}
+
+function renderFrontmatter({ mode, slug, windowN, featuresMined, counts, candidatesCount, observationsCount, generatedAt }) {
+  const lines = ['---'];
+  if (mode === 'window') {
+    lines.push(`window: last-${windowN}`);
+  } else {
+    lines.push(`feature: ${slug}`);
+  }
+  lines.push(`generated_at: ${generatedAt}`);
+  lines.push('generated_by: harness-retro');
+  lines.push('schema_version: "1.0"');
+  lines.push(`features_mined: [${featuresMined.join(', ')}]`);
+  lines.push('sources:');
+  for (const key of SOURCE_ORDER) {
+    lines.push(`  ${key}: ${counts[key] || 0}`);
+  }
+  lines.push(`candidates: ${candidatesCount}`);
+  lines.push(`observations: ${observationsCount}`);
+  lines.push('---');
+  return lines.join('\n');
+}
+
+/**
+ * @param {object} opts
+ * @param {'feature'|'window'} opts.mode
+ * @param {string} [opts.slug]
+ * @param {number} [opts.windowN]
+ * @param {string[]} opts.featuresMined
+ * @param {object} opts.counts — contagens por fonte
+ * @param {Array} opts.candidates
+ * @param {Array} opts.observations
+ * @param {string[]} opts.minedPaths
+ * @param {string[]} opts.warnings
+ * @param {string} opts.dossierRelPath — path relativo deste dossiê (para o Próximo passo)
+ * @param {string} opts.generatedAt — ISO 8601 (única fonte de não-determinismo)
+ * @returns {string}
+ */
+function renderDossier(opts) {
+  const {
+    mode, slug, windowN, featuresMined, counts,
+    candidates, observations, minedPaths, warnings, dossierRelPath, generatedAt
+  } = opts;
+
+  const blocks = [];
+
+  blocks.push(renderFrontmatter({
+    mode, slug, windowN, featuresMined, counts,
+    candidatesCount: candidates.length, observationsCount: observations.length, generatedAt
+  }));
+
+  const title = mode === 'window' ? `Dossiê retrospectivo — janela last-${windowN}` : `Dossiê retrospectivo — ${slug}`;
+  blocks.push(`\n# ${title}\n`);
+
+  // 1. Propostas candidatas
+  const sec1 = ['## Propostas candidatas', ''];
+  if (candidates.length === 0) {
+    sec1.push('_(nenhuma proposta candidata — nenhum item atende ao critério REQ-2)_');
+  } else {
+    for (const c of candidates) sec1.push(renderCandidate(c));
+  }
+  blocks.push(sec1.join('\n'));
+
+  // 2. Observações
+  const sec2 = ['', '## Observações', ''];
+  if (observations.length === 0) {
+    sec2.push('_(nenhuma observação)_');
+  } else {
+    for (const o of observations) sec2.push(renderObservation(o));
+  }
+  blocks.push(sec2.join('\n'));
+
+  // 3. Trilha minerada
+  const sec3 = ['', '## Trilha minerada', '', '### Paths minerados'];
+  if (minedPaths.length === 0) {
+    sec3.push('- _(nenhum path encontrado)_');
+  } else {
+    for (const p of minedPaths) sec3.push(`- ${p}`);
+  }
+  sec3.push('', '### Contagens por fonte');
+  for (const key of SOURCE_ORDER) {
+    sec3.push(`- ${key}: ${counts[key] || 0}`);
+  }
+  sec3.push('', '### Avisos');
+  if (warnings.length === 0) {
+    sec3.push('- _(nenhum aviso — todas as fontes lidas sem degradação)_');
+  } else {
+    for (const w of warnings) sec3.push(`- ${w}`);
+  }
+  blocks.push(sec3.join('\n'));
+
+  // 4. Próximo passo (texto fixo — REQ-5)
+  const sec4 = [
+    '',
+    '## Próximo passo',
+    '',
+    `Ative o @sheldon sob demanda para analisar este dossiê (\`${dossierRelPath}\`):`,
+    '',
+    '```',
+    `aioson agent:prompt sheldon . --task="analisar ${dossierRelPath}"`,
+    '```',
+    '',
+    'Critério de promoção (REQ-2): só vira proposta o item com ≥2 ocorrências da mesma chave determinística, ≥1 finding High/Critical, ou ≥2 ciclos FAIL→PASS na mesma feature.',
+    '',
+    '@sheldon classifica as classes de falha citando as ocorrências deste dossiê e propõe deltas que aterrissam APENAS em `.aioson/learnings/` e `.aioson/rules/`, sempre com aprovação humana. A CLI minera e materializa; ela nunca auto-aplica deltas.',
+    ''
+  ];
+  blocks.push(sec4.join('\n'));
+
+  // Normaliza para LF e garante newline final único (byte-estável).
+  return `${blocks.join('\n').replace(/\r\n/g, '\n').replace(/\n+$/, '')}\n`;
+}
+
+module.exports = {
+  renderDossier,
+  _internal: { renderFrontmatter, renderCandidate, fmtCost, neutralizeText, SOURCE_ORDER }
+};