chore: script lifecycle audit - deprecate legacy orchestration scripts

[oalanicolas]

Descrição

Scripts novos foram criados nos Epic 11/12 sem deprecar os antigos, gerando potenciais conflitos de import e confusão sobre qual módulo usar.

Referência

• Backlog Item: EPIC12-F4
• Source: Feedback do Engenheiro (Sprint Planning)
• Effort: 1-2 horas

Scripts a Auditar

Conflito Confirmado

• workflow-state-manager.js - Superseded by session-state.js
  • Adicionar @deprecated header
  • Apontar para session-state.js

Semi-Conflito (Avaliar)

• workflow-navigator.js - Avaliar se deve ser deprecated ou documentar scope
  • Pode ter uso legítimo fora do contexto Bob

Sem Conflito (Documentar)

• WorkflowOrchestrator vs BobOrchestrator vs MasterOrchestrator
  • Criar documentação de hierarquia

Tasks

1. Mapear todos os scripts legados superseded por módulos Epic 11/12
2. Adicionar @deprecated headers com ponteiros para substitutos
3. Documentar hierarquia de orquestradores:
   • Bob (PM Orchestrator) - Story-driven, multi-agent
   • Master (AIOS Master) - Agent activation, command routing
   • WorkflowOrchestrator - Workflow execution engine
4. Criar docs/architecture/orchestration-hierarchy.md
5. Verificar que nenhum módulo de orchestration importa scripts deprecated
6. Verificar que nenhum task file referencia scripts deprecated sem fallback

Success Criteria

• Zero conflitos de import entre scripts legados e módulos Epic 11/12
• Documentação de coexistência clara em docs/architecture/
• Todos os deprecated scripts têm header com alternativa

Contexto

Mapeamento completo em sessão @po 2026-02-05 identificou:

• 1 conflito confirmado (workflow-state-manager.js)
• 1 semi-conflito (workflow-navigator.js)
• 3 orquestradores complementares (sem conflito real)

---

🤖 Generated with Claude Code via Happy

[nikolasdehor]

Offering to Help with the Script Audit

I'd like to contribute a PR for this audit. After exploring the codebase I have some concrete observations that could form the basis of the work:

Shebang and Error Handling Gaps

Looking at .aios-core/infrastructure/scripts/, there are 87 scripts total. From sampling several:

• plan-tracker.js has a proper shebang (#!/usr/bin/env node) and JSDoc header -- good reference
• worktree-manager.js has no shebang line -- starts directly with const execa = require('execa'). If invoked directly from a shell (rather than via node), this will fail silently or throw a confusing error
• backup-manager.js also has no shebang and no JSDoc module header -- starts with raw requires
• conflict-resolver.js -- same pattern, no shebang, no module-level documentation

A systematic pass to add shebangs, 'use strict' directives, and module JSDoc headers to all scripts would be a clean, low-risk first task.

Confirmed Deprecation: workflow-state-manager.js -> session-state.js

The session-state.js in .aios-core/core/orchestration/ already has a clear ADR reference in its header:

ADR-011: Unified Session State (absorbs Workflow State from 11.3)

This confirms the supersession is intentional and documented at the architecture level. Adding a @deprecated header to workflow-state-manager.js pointing to session-state.js would formalize what ADR-011 already specifies.

Orchestrator Hierarchy Documentation

The three orchestrators mentioned in the issue are complementary, not conflicting:

Orchestrator	Module	Role
BobOrchestrator	core/orchestration/bob-orchestrator.js	Story-driven PM agent entry point. Routes to brownfield/greenfield handlers. Integrates Epic 11 modules (ExecutorAssignment, TerminalSpawner, WorkflowExecutor, SurfaceChecker, SessionState)
MasterOrchestrator	core/orchestration/master-orchestrator.js	ADE pipeline (Epics 3->4->5->6). State machine with TechStackDetector, RecoveryHandler, GateEvaluator, AgentInvoker
WorkflowOrchestrator	(workflow execution engine)	Phase-based workflow execution with parallel phases

This hierarchy is clear in the code but not documented anywhere a contributor would find it easily. A docs/architecture/orchestration-hierarchy.md as the issue suggests would be valuable.

Proposed Approach

I'd suggest splitting this into 2-3 small PRs rather than one large one:

1. PR 1: Add @deprecated headers to confirmed superseded scripts + shebang/strict-mode pass on scripts missing them
2. PR 2: Orchestration hierarchy documentation (docs/architecture/orchestration-hierarchy.md)
3. PR 3: Import verification -- grep for any modules still importing deprecated scripts and update them

Would this breakdown work for you, or do you prefer a different scope?

[Pedrovaleriolopez]

Maintainer Review of Your Plan 🎯

Hey @nikolasdehor! We reviewed your proposed plan in detail and compared it against our active development (specifically the epic-nogic-code-intelligence branch with 15 stories across 7 waves). Here's our assessment:

---

PR 2: orchestration-hierarchy.md — ✅ APPROVED (go ahead!)

This is the highest-value, zero-risk contribution. No docs/architecture/orchestration-hierarchy.md exists yet, and the documentation of BobOrchestrator / MasterOrchestrator / WorkflowOrchestrator relationships would be genuinely useful.

You can start this immediately. Target branch: main.

---

PR 1: Deprecated Headers + Shebangs — ✅ ACCEPTED with scope note

Good approach, but one heads-up: workflow-state-manager.js already has a @deprecated header (added during Story 11.5 / ADR-011). So you can skip that file.

For the shebang/strict-mode pass on infrastructure scripts — go for it, just be aware it's a large diff (~82 files) so keep the commit focused.

Recommended order: PR 2 first, then PR 1.

---

PR 3: Import Verification — ✅ ACCEPTED with guardrails

This is the most valuable cleanup, but we need scope constraints to avoid conflicts with active development:

⚠️ Files to EXCLUDE from PR 3:

• unified-activation-pipeline.js — Story NOG-12 (State Persistence Hardening) plans to modify lines 713 and 759 for atomic writes. Any changes here risk merge conflicts.
• Note: this file imports workflow-navigator.js which is actively used (NOT deprecated) — you correctly identified this in your analysis.

Safe targets for PR 3 (consumers of the deprecated workflow-state-manager.js):

• .aios-core/workflow-intelligence/engine/suggestion-engine.js:100
• .aios-core/development/scripts/verify-workflow-gaps.js:366,853
• .aios-core/development/tasks/next.md:96 (task doc reference)
• tests/unit/workflow-state-manager.test.js:9

Recommended order: PR 2 → PR 1 → PR 3 (lowest risk first).

---

Summary

PR	Status	Risk	Notes
PR 2 (docs)	✅ Start now	Zero	No conflicts possible
PR 1 (headers)	✅ Go ahead	Low	Skip workflow-state-manager.js (already done)
PR 3 (imports)	✅ With guardrails	Medium	Exclude unified-activation-pipeline.js

Thanks for the thoughtful plan! Looking forward to your PRs. 🚀

— Maintainer review via @devops (Gage)

[nikolasdehor]

Posso ajudar com essa auditoria @oalanicolas. Já tenho bastante contexto sobre os scripts de orquestração — trabalhei em módulos como o master-orchestrator (#536), swarm-intelligence (#572), e cognitive-load-balancer (#571). Consigo mapear quais scripts legados podem ser deprecados com segurança. Quer que eu comece um levantamento?