diff --git a/.aiox-core/core/docs/orchestration-hierarchy.md b/.aiox-core/core/docs/orchestration-hierarchy.md new file mode 100644 index 000000000..8e1997658 --- /dev/null +++ b/.aiox-core/core/docs/orchestration-hierarchy.md @@ -0,0 +1,122 @@ +# Hierarquia de Orquestradores - AIOX Core + +> Issue: #90 - Script lifecycle audit +> EPIC12-F4 - Documentacao de coexistencia + +## Visao Geral + +O AIOX possui tres orquestradores que operam em camadas complementares. Nenhum conflita com os outros -- cada um tem escopo e responsabilidades distintas. + +``` +MasterOrchestrator (Epic 0) + |-- Ativacao de agentes, roteamento de comandos + |-- Pipeline completo: Epics 3 -> 4 -> 5 -> 6 + | +BobOrchestrator (Epic 12) + |-- Decision tree do PM agent + |-- Story-driven, multi-agent orchestration + |-- Integra todos os modulos Epic 11 + | +WorkflowOrchestrator (Core) + |-- Engine de execucao de workflows + |-- Multi-agent phase dispatch + |-- Pre-Flight detection, skill dispatch +``` + +## Detalhamento + +### 1. MasterOrchestrator + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/core/orchestration/master-orchestrator.js` | +| **Epic** | Epic 0 (ADE - Autonomous Development Engine) | +| **Story** | 0.1 - Master Orchestrator Core | +| **Escopo** | Orquestracao central do pipeline de desenvolvimento autonomo | + +**Responsabilidades:** +- `executeFullPipeline()` — executa Epics 3, 4, 5, 6 em sequencia +- `executeEpic(epicNum)` — execucao individual de um epic +- `resumeFromEpic(epicNum)` — retomada de ponto especifico +- State machine: INITIALIZED -> READY -> IN_PROGRESS -> BLOCKED -> COMPLETE +- Integracao com TechStackDetector para pre-flight detection + +**Quando usar:** Pipeline completo de desenvolvimento autonomo, ativacao de agentes no nivel mais alto. + +--- + +### 2. BobOrchestrator + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/core/orchestration/bob-orchestrator.js` | +| **Epic** | Epic 12 (Projeto Bob) | +| **Story** | 12.3 - Bob Orchestration Logic (Decision Tree) | +| **Escopo** | PM agent routing via decision tree codificada | + +**Responsabilidades:** +- Detecta estado do projeto e roteia para workflow correto +- Integra TODOS os modulos Epic 11: + - ExecutorAssignment (11.1) — selecao de agente + - TerminalSpawner (11.2) — spawn de agentes + - WorkflowExecutor (11.3) — ciclo de desenvolvimento + - SurfaceChecker (11.4) — criterios de decisao humana + - SessionState (11.5) — persistencia de sessao +- Decision tree sem LLM (roteamento deterministico) +- Constraint: < 50 linhas de logica especifica de outros agentes + +**Quando usar:** Orquestracao story-driven multi-agente via PM. + +--- + +### 3. WorkflowOrchestrator + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/core/orchestration/workflow-orchestrator.js` | +| **Epic** | Core (pre-Epic 11) | +| **Escopo** | Engine de execucao de workflows multi-agente | + +**Responsabilidades:** +- Executa workflows com subagentes reais (persona transformation) +- Cada fase despacha para agente especializado +- Integracao com: + - SubagentPromptBuilder — construcao de prompts + - ContextManager — gerenciamento de contexto + - ParallelExecutor — execucao paralela + - ChecklistRunner — execucao de checklists + - TechStackDetector (V3.1) — pre-flight detection + - ConditionEvaluator, SkillDispatcher — dispatch condicional + +**Quando usar:** Execucao de workflows que envolvem multiplos agentes com fases definidas. + +--- + +## Relacao Entre Orquestradores + +``` +Requisicao do usuario + | + v +MasterOrchestrator (ativa agente) + | + |-- Se PM/Bob --> BobOrchestrator (decision tree) + | | + | v + | WorkflowExecutor (ciclo dev) + | | + | v + | WorkflowOrchestrator (executa fases) + | + |-- Se outro agente --> execucao direta ou task +``` + +## Modulos Deprecados (ver docs/deprecated-scripts.md) + +| Modulo Legado | Substituto | Status | +|---------------|-----------|--------| +| `workflow-state-manager.js` | `session-state.js` | @deprecated | +| `workflow-navigator.js` | `bob-orchestrator.js` + `session-state.js` | @deprecated (semi) | +| `command-execution-hook.js` | `session-state.js` | @deprecated | + +Estes modulos ainda existem para backward compatibility mas nao devem ser usados em codigo novo. diff --git a/.aiox-core/development/scripts/workflow-navigator.js b/.aiox-core/development/scripts/workflow-navigator.js index 8e083a6e2..6815d5b18 100644 --- a/.aiox-core/development/scripts/workflow-navigator.js +++ b/.aiox-core/development/scripts/workflow-navigator.js @@ -1,6 +1,15 @@ /** * Workflow Navigator - Next-Step Suggestions for Workflow State * + * @deprecated Semi-deprecated since Epic 11/12. Bob Orchestrator (Story 12.3) + * now handles workflow routing via codified decision tree, and SessionState + * (Story 11.5) manages session persistence. This module may still be used + * by greeting-builder.js and unified-activation-pipeline.js for legacy + * command suggestion flows. New workflow navigation should use: + * - .aiox-core/core/orchestration/bob-orchestrator.js (decision routing) + * - .aiox-core/core/orchestration/session-state.js (state persistence) + * - .aiox-core/core/orchestration/workflow-executor.js (execution engine) + * * Provides intelligent next-step command suggestions based on: * - Current workflow state (detected from command history) * - Workflow transitions (defined in workflow-patterns.yaml) @@ -12,6 +21,8 @@ * - Numbered list formatting for user selection */ +console.warn('[DEPRECATED] workflow-navigator.js — workflow routing now handled by bob-orchestrator.js (Story 12.3) and session-state.js (Story 11.5)'); + const fs = require('fs'); const path = require('path'); const yaml = require('js-yaml'); diff --git a/.aiox-core/development/scripts/workflow-state-manager.js b/.aiox-core/development/scripts/workflow-state-manager.js index 964ff49a0..8200ad1b9 100644 --- a/.aiox-core/development/scripts/workflow-state-manager.js +++ b/.aiox-core/development/scripts/workflow-state-manager.js @@ -20,6 +20,8 @@ * @version 2.0.0 */ +console.warn('[DEPRECATED] workflow-state-manager.js — use .aiox-core/core/orchestration/session-state.js instead (Story 11.5)'); + const fs = require('fs').promises; const path = require('path'); const yaml = require('js-yaml'); diff --git a/.aiox-core/install-manifest.yaml b/.aiox-core/install-manifest.yaml index 05816fa4f..4db8724db 100644 --- a/.aiox-core/install-manifest.yaml +++ b/.aiox-core/install-manifest.yaml @@ -8,9 +8,9 @@ # - File types for categorization # version: 5.0.3 -generated_at: "2026-03-11T15:04:09.395Z" +generated_at: "2026-03-12T18:49:52.538Z" generator: scripts/generate-install-manifest.js -file_count: 1090 +file_count: 1091 files: - path: cli/commands/config/index.js hash: sha256:25c4b9bf4e0241abf7754b55153f49f1a214f1fb5fe904a576675634cb7b3da9 @@ -284,6 +284,10 @@ files: hash: sha256:3505471b0adff9bfcea08f46cca3aeeda46a283bbe7ee711dd566e5974c3257f type: template size: 721 + - path: core/docs/orchestration-hierarchy.md + hash: sha256:86daaa7fbc1f7b1f62466c929c523ad5a807ea44d50c87ad302ac34191b775e3 + type: documentation + size: 4060 - path: core/doctor/checks/agent-memory.js hash: sha256:08d5d685e4fdaaedf081020229844f4a58c9fd00244e4c37eb5b3fd78f4feb61 type: core @@ -1705,13 +1709,13 @@ files: type: script size: 15887 - path: development/scripts/workflow-navigator.js - hash: sha256:45bd9f0317b6a0b9e9577b5b26550f1b7fafec2c45c1b542a6947ffd69a70fec + hash: sha256:43e3fb1a9655a06bcfd54d450b0e6e079fbb3f292673afd86afbe4adb578c6de type: script - size: 9847 + size: 10595 - path: development/scripts/workflow-state-manager.js - hash: sha256:3a896079b32b8efb8c532c0626c4ce14fb52cc92afbb086f6f2d2a0367d60dec + hash: sha256:5300937308b430285891afda757ea83ccf20fcdd64005a870c06f3b072c0ee06 type: script - size: 20129 + size: 20262 - path: development/scripts/workflow-validator.js hash: sha256:abb16e5cd34ec06bbca0a31af3fc500c3a5c98f66d0a72546e4a2827653abcd3 type: script @@ -4073,21 +4077,21 @@ files: type: script size: 8761 - path: scripts/batch-migrate-phase1.ps1 - hash: sha256:c1f72c94244b7fe8f1f5cf12f0eb2cea017aeaca620953ede02c5c8f0125b429 + hash: sha256:6f9d7117cee5a9180a9ff952ea9b2a9cc66d0365b76bdd4e3ba879329636da99 type: script - size: 974 + size: 1333 - path: scripts/batch-migrate-phase2.ps1 - hash: sha256:9f7d0a90fec3c2553cd5b757765b15839a0eeefb040fe6e23d58faa801eefe61 + hash: sha256:290b25e360894ea33b6fda3bef572b57e49292bed516221eb89b9cc77fa03814 type: script - size: 2591 + size: 2950 - path: scripts/batch-migrate-phase3.ps1 - hash: sha256:5555a7095693dd7a64be48c6fb0e03b706a68ffd66af9edebac65b798dc4f2bb + hash: sha256:eadbccd740b43fa430e590d6412fecc53bc0e45bcc457d6dfce5c7ded526b1c1 type: script - size: 1492 + size: 1851 - path: scripts/command-execution-hook.js - hash: sha256:295663ee1d236c1085f359773c8940a2cb05cea648e39ef1f02f745a3e7d0990 + hash: sha256:43360a859c8d1701b2dc05cd32b9451227daa30c268fc7296f0cae4c850f86d0 type: script - size: 5047 + size: 5518 - path: scripts/diagnostics/diagnose-installation.js hash: sha256:a3e2dc1b3630d6c14098a7becf007caeb7ecf5ded72b1d2be116fdc8b5778fe4 type: script @@ -4257,9 +4261,9 @@ files: type: script size: 4468 - path: scripts/migrate-framework-docs.sh - hash: sha256:535844ae659e1cb4d35658cde8379b64a4195ff62ee84d048b9a5c7249f5b617 + hash: sha256:b6380908affc59158594a7cbeaf737b0a755ff12d99a8bf6527e0f6c616154ec type: script - size: 9488 + size: 9837 - path: scripts/pm.sh hash: sha256:ee33d9c7cd88a4d537bf2dc8c89c734f3e6027fc7d0cf4c668066e6c600e7e3a type: script @@ -4269,9 +4273,9 @@ files: type: script size: 4527 - path: scripts/session-context-loader.js - hash: sha256:c994dcd432125f969e1bf1b9eac2b1511b02722b7e73f16aa20db3d2fb4d0b90 + hash: sha256:bf7aab6da9feda285bab0d5456e7eb412289a85687a671e117a141264a2a4cfa type: script - size: 1583 + size: 1717 - path: scripts/test-template-system.js hash: sha256:a9950ff166530e657ac7fb64fb1b121fa2d909371618e35a0543c554a34be435 type: script @@ -4281,9 +4285,9 @@ files: type: script size: 6083 - path: scripts/validate-phase1.ps1 - hash: sha256:ea9f40a265c44fffeb859f5041f7d7cbcd49322d3f0c0d88949f8ac8b7c25c15 + hash: sha256:26402ca0e4d97c0f1671222fccab463435b83d8d464e4771c6b6e8d1ce29f971 type: script - size: 768 + size: 1053 - path: scripts/workflow-management.md hash: sha256:fae596f7be326f897fafeab252fdffd2c6d6cb3163f31f71a4c01d5c88e79930 type: script diff --git a/.aiox-core/scripts/batch-migrate-phase1.ps1 b/.aiox-core/scripts/batch-migrate-phase1.ps1 index df4b4f50b..678ffa321 100644 --- a/.aiox-core/scripts/batch-migrate-phase1.ps1 +++ b/.aiox-core/scripts/batch-migrate-phase1.ps1 @@ -1,3 +1,8 @@ +# @deprecated One-time migration script (Task V2.0 migration, completed). +# All tasks have been migrated to V2.0 format. This script is no longer needed. +# Replacement: tasks are now natively V2.0 — use validate-task-v2.js for validation. +Write-Warning "[DEPRECATED] batch-migrate-phase1.ps1 — migration already completed. Tasks are V2.0 natively." + # Phase 1 - Batch migrate critical tasks $tasks = @( diff --git a/.aiox-core/scripts/batch-migrate-phase2.ps1 b/.aiox-core/scripts/batch-migrate-phase2.ps1 index 08ef8e1f2..9dc34902d 100644 --- a/.aiox-core/scripts/batch-migrate-phase2.ps1 +++ b/.aiox-core/scripts/batch-migrate-phase2.ps1 @@ -1,3 +1,8 @@ +# @deprecated One-time migration script (Task V2.0 migration, completed). +# All tasks have been migrated to V2.0 format. This script is no longer needed. +# Replacement: tasks are now natively V2.0 — use validate-task-v2.js for validation. +Write-Warning "[DEPRECATED] batch-migrate-phase2.ps1 — migration already completed. Tasks are V2.0 natively." + # Phase 2 - Batch migrate agent-specific tasks (50 tasks) $tasks = @( diff --git a/.aiox-core/scripts/batch-migrate-phase3.ps1 b/.aiox-core/scripts/batch-migrate-phase3.ps1 index 0f72c3b39..b147c240b 100644 --- a/.aiox-core/scripts/batch-migrate-phase3.ps1 +++ b/.aiox-core/scripts/batch-migrate-phase3.ps1 @@ -1,3 +1,8 @@ +# @deprecated One-time migration script (Task V2.0 migration, completed). +# All tasks have been migrated to V2.0 format. This script is no longer needed. +# Replacement: tasks are now natively V2.0 — use validate-task-v2.js for validation. +Write-Warning "[DEPRECATED] batch-migrate-phase3.ps1 — migration already completed. Tasks are V2.0 natively." + # Phase 3 - Batch migrate remaining utility & support tasks # Get all remaining non-compliant tasks diff --git a/.aiox-core/scripts/command-execution-hook.js b/.aiox-core/scripts/command-execution-hook.js index 804ce3030..e41f8abb8 100644 --- a/.aiox-core/scripts/command-execution-hook.js +++ b/.aiox-core/scripts/command-execution-hook.js @@ -1,22 +1,30 @@ #!/usr/bin/env node /** * Command Execution Hook - * + * + * @deprecated Superseded by SessionState (Story 11.5) which provides unified + * session state persistence with crash recovery, phase tracking, and epic/story + * context. This script's simple command-history tracking is now a subset of + * SessionState's capabilities. New code should use: + * - .aiox-core/core/orchestration/session-state.js + * * Updates session state after command execution for workflow continuity. - * + * * Responsibilities: * - Track command execution history - * - Update session type (new → existing → workflow) + * - Update session type (new -> existing -> workflow) * - Record agent transitions * - Enable intelligent greeting adaptation - * + * * Usage: * const { updateSessionAfterCommand } = require('./command-execution-hook'); * await updateSessionAfterCommand(agentId, commandName); - * + * * Part of Story 6.1.4: Unified Greeting System Integration */ +console.warn('[DEPRECATED] command-execution-hook.js — use .aiox-core/core/orchestration/session-state.js instead (Story 11.5)'); + const fs = require('fs').promises; const path = require('path'); diff --git a/.aiox-core/scripts/migrate-framework-docs.sh b/.aiox-core/scripts/migrate-framework-docs.sh index 1dd5cd7a4..5e496c4a8 100644 --- a/.aiox-core/scripts/migrate-framework-docs.sh +++ b/.aiox-core/scripts/migrate-framework-docs.sh @@ -2,6 +2,10 @@ # # AIOX Framework Documentation Migration Script # +# @deprecated One-time migration script (Story 6.1.2.6, completed). +# Framework docs have been migrated to aiox-core. This script is no longer needed. +# Documentation now lives natively in docs/ and .aiox-core/docs/. +# # Purpose: Migrate framework docs from aiox-fullstack to aiox-core (REPO 1) # Story: 6.1.2.6 - Framework Configuration System # Execution Timeline: Q2 2026 (Repository Migration Phase) @@ -15,6 +19,8 @@ # --help Show this help message # +echo "[DEPRECATED] migrate-framework-docs.sh — migration already completed. Docs live natively in docs/ and .aiox-core/docs/." + set -e # Exit on error # Colors for output diff --git a/.aiox-core/scripts/session-context-loader.js b/.aiox-core/scripts/session-context-loader.js index 3d147dfbd..6184ba16c 100644 --- a/.aiox-core/scripts/session-context-loader.js +++ b/.aiox-core/scripts/session-context-loader.js @@ -15,6 +15,8 @@ 'use strict'; +console.warn('[DEPRECATED] session-context-loader.js — use require(\'.aiox-core/core/session/context-loader\') directly (WIS-3)'); + // Re-export from canonical location const SessionContextLoader = require('../core/session/context-loader'); diff --git a/.aiox-core/scripts/validate-phase1.ps1 b/.aiox-core/scripts/validate-phase1.ps1 index c5c2872fc..f1bdcd88f 100644 --- a/.aiox-core/scripts/validate-phase1.ps1 +++ b/.aiox-core/scripts/validate-phase1.ps1 @@ -1,3 +1,7 @@ +# @deprecated One-time validation script for Task V2.0 Phase 1 migration. +# Migration is complete. Use validate-task-v2.js directly for ongoing validation. +Write-Warning "[DEPRECATED] validate-phase1.ps1 — Phase 1 migration already validated. Use validate-task-v2.js directly." + $tasks = @( 'dev-develop-story.md', 'create-next-story.md', diff --git a/docs/deprecated-scripts.md b/docs/deprecated-scripts.md new file mode 100644 index 000000000..c824807dd --- /dev/null +++ b/docs/deprecated-scripts.md @@ -0,0 +1,116 @@ +# Scripts Deprecados - Auditoria de Lifecycle + +> Issue: #90 - Script lifecycle audit +> EPIC12-F4 - Sprint Planning Feedback + +## Resumo + +Scripts legados que foram superseded por modulos Epic 11/12 e migracao de tasks V2.0. Nenhum script foi removido -- todos foram marcados com `@deprecated` e `console.warn` para visibilidade em runtime. + +--- + +## Scripts Deprecados + +### 1. `workflow-state-manager.js` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/development/scripts/workflow-state-manager.js` | +| **Substituto** | `.aiox-core/core/orchestration/session-state.js` | +| **Motivo** | SessionState (Story 11.5, ADR-011) unifica persistencia de estado. Bob usa SessionState exclusivamente. | +| **Impacto** | Ainda importado por `verify-workflow-gaps.js`, `suggestion-engine.js`, `next.md` | +| **Acao** | Migrar importadores para session-state.js em sprint futuro | + +### 2. `workflow-navigator.js` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/development/scripts/workflow-navigator.js` | +| **Substituto** | `.aiox-core/core/orchestration/bob-orchestrator.js` + `session-state.js` | +| **Motivo** | Bob Orchestrator (Story 12.3) agora faz roteamento de workflow via decision tree codificada. SessionState gerencia persistencia. | +| **Impacto** | Ainda importado por `greeting-builder.js`, `unified-activation-pipeline.js` | +| **Acao** | Avaliar se consumers podem migrar para bob-orchestrator; manter como compat ate entao | + +### 3. `command-execution-hook.js` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/command-execution-hook.js` | +| **Substituto** | `.aiox-core/core/orchestration/session-state.js` | +| **Motivo** | SessionState (Story 11.5) absorve tracking de comandos, transicoes de agente e persistencia de sessao com capabilities superiores (crash recovery, phase tracking, epic/story context). | +| **Impacto** | Nenhum import ativo em JS -- apenas referenciado em docs | +| **Acao** | Seguro para remocao futura | + +### 4. `session-context-loader.js` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/session-context-loader.js` | +| **Substituto** | `.aiox-core/core/session/context-loader.js` | +| **Motivo** | Re-export de compatibilidade (WIS-3). Localizacao canonica movida para core/session/. | +| **Impacto** | Funciona como proxy -- pode ser removido quando todos os imports migrarem | +| **Acao** | Migrar imports restantes para core/session/context-loader | + +### 5. `batch-migrate-phase1.ps1` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/batch-migrate-phase1.ps1` | +| **Substituto** | N/A (migracao concluida) | +| **Motivo** | Script one-time para migracao de tasks para formato V2.0. Migracao ja concluida. | +| **Impacto** | Nenhum | +| **Acao** | Pode ser removido em cleanup futuro | + +### 6. `batch-migrate-phase2.ps1` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/batch-migrate-phase2.ps1` | +| **Substituto** | N/A (migracao concluida) | +| **Motivo** | Script one-time para migracao de 50 tasks agent-specific. Migracao ja concluida. | +| **Impacto** | Nenhum | +| **Acao** | Pode ser removido em cleanup futuro | + +### 7. `batch-migrate-phase3.ps1` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/batch-migrate-phase3.ps1` | +| **Substituto** | N/A (migracao concluida) | +| **Motivo** | Script one-time para migracao de tasks restantes. Migracao ja concluida. | +| **Impacto** | Nenhum | +| **Acao** | Pode ser removido em cleanup futuro | + +### 8. `validate-phase1.ps1` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/validate-phase1.ps1` | +| **Substituto** | `validate-task-v2.js` (direto) | +| **Motivo** | Script one-time para validar Phase 1 da migracao V2.0. Validacao agora feita via validate-task-v2.js. | +| **Impacto** | Nenhum | +| **Acao** | Pode ser removido em cleanup futuro | + +### 9. `migrate-framework-docs.sh` + +| Campo | Valor | +|-------|-------| +| **Path** | `.aiox-core/scripts/migrate-framework-docs.sh` | +| **Substituto** | N/A (migracao concluida) | +| **Motivo** | Script one-time (Story 6.1.2.6) para migrar docs de aiox-fullstack para aiox-core. Migracao ja concluida. | +| **Impacto** | Nenhum | +| **Acao** | Pode ser removido em cleanup futuro | + +--- + +## Scripts NAO Deprecados (Documentar Coexistencia) + +Os tres orquestradores coexistem com escopos complementares. Nenhum conflito real: + +| Orquestrador | Escopo | Epic | +|--------------|--------|------| +| `BobOrchestrator` | PM agent decision tree, story-driven multi-agent | Epic 12 | +| `MasterOrchestrator` | Agent activation, command routing, full pipeline | Epic 0 | +| `WorkflowOrchestrator` | Workflow execution engine (multi-agent phases) | Core | + +Ver `.aiox-core/core/docs/orchestration-hierarchy.md` para detalhes.