aiox-core 5.0.4 → 5.0.5

package/.aiox-core/development/scripts/workflow-validator.js

@@ -101,36 +101,38 @@ class WorkflowValidator {
       return result; // Can't continue without parsed data
     }
 
-    const workflow = parseResult.data;
+    const workflow = this._normalizeWorkflowDocument(parseResult.data);
 
     // 3. Required fields
     const fieldsResult = this.validateRequiredFields(workflow, workflowPath);
     this._mergeResults(result, fieldsResult);
 
+    const phaseSequence = this._getPhaseSequence(workflow);
+
     // 4. Phase sequence
-    if (workflow.workflow && workflow.workflow.sequence) {
-      const sequenceResult = this.validatePhaseSequence(workflow.workflow.sequence);
+    if (phaseSequence.length > 0) {
+      const sequenceResult = this.validatePhaseSequence(phaseSequence);
       this._mergeResults(result, sequenceResult);
 
       // 5. Agent references
-      const agentResult = await this.validateAgentReferences(workflow.workflow.sequence);
+      const agentResult = await this.validateAgentReferences(phaseSequence);
       this._mergeResults(result, agentResult);
 
       // 6. Artifact flow
-      const artifactResult = this.validateArtifactFlow(workflow.workflow.sequence);
+      const artifactResult = this.validateArtifactFlow(phaseSequence);
       this._mergeResults(result, artifactResult);
 
       // 7. Circular dependencies
-      const circularResult = this.detectCircularDeps(workflow.workflow.sequence);
+      const circularResult = this.detectCircularDeps(phaseSequence);
       this._mergeResults(result, circularResult);
 
       // 8. Conditional logic
-      const conditionalResult = this.validateConditionalLogic(workflow.workflow.sequence);
+      const conditionalResult = this.validateConditionalLogic(phaseSequence);
       this._mergeResults(result, conditionalResult);
     }
 
     // 9. Handoff prompts
-    const handoffResult = this.validateHandoffPrompts(workflow);
+    const handoffResult = this.validateHandoffPrompts(workflow, phaseSequence);
     this._mergeResults(result, handoffResult);
 
     // 10. Mermaid diagram
@@ -191,18 +193,18 @@ class WorkflowValidator {
     const result = { valid: true, errors: [], warnings: [], suggestions: [] };
     const filename = path.basename(filePath);
 
-    if (!workflow.workflow) {
+    const wf = workflow.workflow;
+    if (!wf || typeof wf !== 'object') {
       result.valid = false;
       result.errors.push({
         code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
-        message: 'Missing top-level "workflow:" key',
+        message: 'Missing workflow payload (expected workflow.id, workflow.name, and sequence/phases)',
         file: filename,
-        suggestion: 'Add workflow: as the root key containing id, name, and sequence',
+        suggestion: 'Add workflow: root key or canonical top-level id/name/sequence|phases',
       });
       return result;
     }
 
-    const wf = workflow.workflow;
     const requiredFields = ['id', 'name'];
 
     for (const field of requiredFields) {
@@ -217,13 +219,22 @@ class WorkflowValidator {
       }
     }
 
-    if (!wf.sequence || !Array.isArray(wf.sequence) || wf.sequence.length === 0) {
+    const hasSequence = Array.isArray(wf.sequence) && wf.sequence.length > 0;
+    const hasPhases = Array.isArray(wf.phases) && wf.phases.length > 0;
+    if (!hasSequence && !hasPhases) {
       result.valid = false;
       result.errors.push({
         code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
-        message: 'Missing or empty "sequence:" array',
+        message: 'Missing or empty workflow execution array ("sequence" or "phases")',
+        file: filename,
+        suggestion: 'Add workflow.sequence (official) with at least one step; phases is compatibility only',
+      });
+    } else if (!hasSequence && hasPhases) {
+      result.warnings.push({
+        code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
+        message: 'Workflow uses workflow.phases without workflow.sequence',
         file: filename,
-        suggestion: 'Add sequence: with at least one step entry containing agent and creates/action',
+        suggestion: 'Prefer workflow.sequence as canonical execution contract (keep phases only as supplemental metadata)',
       });
     }
 
@@ -539,18 +550,20 @@ class WorkflowValidator {
   /**
    * Validate handoff prompts exist for transitions
    * @param {Object} workflow - Full parsed workflow
+   * @param {Array|null} phaseSequence - Optional resolved phase sequence
    * @returns {Object} Validation result
    */
-  validateHandoffPrompts(workflow) {
+  validateHandoffPrompts(workflow, phaseSequence = null) {
     const result = { valid: true, errors: [], warnings: [], suggestions: [] };
 
     const wf = workflow.workflow;
-    if (!wf || !wf.sequence || !Array.isArray(wf.sequence)) return result;
+    const sequence = Array.isArray(phaseSequence) ? phaseSequence : this._getPhaseSequence(workflow);
+    if (!wf || !Array.isArray(sequence) || sequence.length === 0) return result;
 
     // Count agent transitions (where one agent hands off to another)
     let transitionCount = 0;
     let prevAgent = null;
-    for (const step of wf.sequence) {
+    for (const step of sequence) {
       if (step.agent && step.agent !== prevAgent) {
         if (prevAgent) transitionCount++;
         prevAgent = step.agent;
@@ -687,6 +700,67 @@ class WorkflowValidator {
       target.valid = false;
     }
   }
+
+  /**
+   * Normalize workflow payload to keep backward compatibility across
+   * workflow-wrapped and top-level workflow documents.
+   * @private
+   * @param {Object} data
+   * @returns {Object}
+   */
+  _normalizeWorkflowDocument(data) {
+    if (!data || typeof data !== 'object') {
+      return { workflow: null };
+    }
+
+    if (data.workflow && typeof data.workflow === 'object') {
+      const normalizedWorkflow = { ...data.workflow };
+      if (!normalizedWorkflow.phases && Array.isArray(data.phases)) {
+        normalizedWorkflow.phases = data.phases;
+      }
+      return { ...data, workflow: normalizedWorkflow };
+    }
+
+    const normalizedWorkflow = {
+      id: data.id,
+      name: data.name,
+      version: data.version,
+      description: data.description,
+      type: data.type,
+      orchestrator: data.orchestrator,
+      sequence: Array.isArray(data.sequence) ? data.sequence : undefined,
+      phases: Array.isArray(data.phases) ? data.phases : undefined,
+      handoff_prompts: data.handoff_prompts,
+      flow_diagram: data.flow_diagram,
+    };
+
+    return {
+      ...data,
+      workflow: normalizedWorkflow,
+    };
+  }
+
+  /**
+   * Resolve executable entries from canonical workflow.sequence[], with
+   * workflow.phases[] as compatibility fallback.
+   * @private
+   * @param {Object} workflow
+   * @returns {Array}
+   */
+  _getPhaseSequence(workflow) {
+    const wf = workflow && workflow.workflow ? workflow.workflow : null;
+    if (!wf) return [];
+
+    if (Array.isArray(wf.sequence) && wf.sequence.length > 0) {
+      return wf.sequence;
+    }
+
+    if (Array.isArray(wf.phases) && wf.phases.length > 0) {
+      return wf.phases;
+    }
+
+    return [];
+  }
 }
 
 module.exports = {

package/.aiox-core/development/tasks/create-workflow.md

@@ -273,23 +273,23 @@ ELICIT: Workflow Basic Information
 4. What is the expected outcome?
 ```
 
-### Step 2: Workflow Stages
-```
-ELICIT: Workflow Stages and Flow
-1. What are the main stages/phases? (e.g., "planning", "implementation", "testing")
-2. What is the sequence of these stages?
+### Step 2: Workflow Sequence Design
+```text
+ELICIT: Workflow Sequence and Flow
+1. What are the main execution steps/phases? (e.g., "planning", "implementation", "testing")
+2. What is the exact step order (`workflow.sequence`)?
 3. Are there any parallel activities?
 4. Are there decision points or conditional flows?
-5. What are the exit criteria for each stage?
+5. What are the exit criteria for each step?
 ```
 
 ### Step 3: Agent Orchestration
-```
+```text
 ELICIT: Agent Participation
-For each stage:
+For each workflow step:
 1. Which agent(s) are involved?
 2. What are their specific responsibilities?
-3. How do agents hand off work between stages?
+3. How do agents hand off work between steps?
 4. Are there any approval requirements?
 ```
 
@@ -316,39 +316,41 @@ ELICIT: Resources and Dependencies
    workflow:
      id: {workflow-name}
      name: {Workflow Display Name}
+     version: {semver}
      description: {Purpose and overview}
      type: {greenfield|brownfield}
      scope: {ui|service|fullstack}
-     
-   stages:
-     - id: stage-1
-       name: {Stage Name}
-       agent: {agent-id}
-       tasks:
-         - {task-name}
-       outputs:
-         - {output-description}
-       next: stage-2
-       
-   transitions:
-     - from: stage-1
-       to: stage-2
-       condition: {optional condition}
-       
-   resources:
-     templates:
-       - {template-name}
-     data:
-       - {data-file}
-       
-   validation:
-     checkpoints:
-       - stage: {stage-id}
-         criteria: {validation-criteria}
+ 
+     # Optional compatibility metadata (non-executable)
+     phases:
+       - phase_1: {phase label}
+       - phase_2: {phase label}
+ 
+     # Canonical executable contract
+     sequence:
+       - step: {step-slug}
+         id: {step-id}
+         phase: {1..N}
+         phase_name: {Phase Display Name}
+         agent: {agent-id}
+         task: {task-name}
+         action: {what happens}
+         requires: {previous-step-id}
+         outputs:
+           - {artifact-name}
+         next: {next-step-id}
+         on_failure: {fallback-step-id}
+
+       - workflow_end:
+           id: complete
+           action: workflow_complete
+
+     handoff_prompts:
+       {from}_to_{to}: {handoff guidance}
    ```
 
 3. **Add Security Controls**
-   - Stage authorization requirements
+   - Step authorization requirements
    - Data access restrictions
    - Audit logging points
    - Approval workflows
@@ -378,7 +380,7 @@ ELICIT: Resources and Dependencies
      timestamp: new Date().toISOString(),
      metadata: {
        type: workflowType,
-       stages: stageList,
+       sequence_steps: stepList,
        agents: involvedAgents
      }
    });
@@ -386,13 +388,13 @@ ELICIT: Resources and Dependencies
 
 6. **Generate Documentation**
    - Create workflow diagram (text-based)
-   - Document each stage's purpose
+   - Document each step's purpose
    - List all handoff points
    - Include troubleshooting guide
 
 ## Validation Checklist
 - [ ] Workflow name is unique and valid
-- [ ] All stages have clear purposes
+- [ ] All sequence steps have clear purposes
 - [ ] Agent assignments are valid
 - [ ] No circular dependencies
 - [ ] All resources exist
@@ -415,7 +417,7 @@ ELICIT: Resources and Dependencies
    (hybrid → squads/{squad_name}/workflows/{workflow-name}.yaml)
 📊 Workflow Summary:
    - Context: {target_context} {squad_name if applicable}
-   - Stages: {stage-count}
+   - Steps: {step-count}
    - Agents: {agent-list}
    - Type: {workflow-type}
 🚀 To use: Select workflow when starting new project
@@ -423,6 +425,6 @@ ELICIT: Resources and Dependencies
 
 ## Workflow Execution Notes
 - Workflows are selected during project initialization
-- Each stage execution is logged in memory
+- Each step execution is logged in memory
 - Progress tracking available through memory queries
-- Agents automatically receive stage-specific context 
+- Agents automatically receive step-specific context

package/.aiox-core/development/tasks/project-status.md

@@ -0,0 +1,280 @@
+# Task: Project Status — Full Panorama
+
+> **Command:** `*status`
+> **Agent:** @aiox-master, @po, @sm
+> **Purpose:** Display accurate, real-time panorama of all epics and stories
+> **Created:** 2026-03-05
+
+---
+
+## Purpose
+
+Display a comprehensive, **100% accurate** panorama of all epics and stories in the project. The status of each story is read directly from its **source of truth** — the `## Status` field in each story file — never inferred from epic metadata, git history, or cached data.
+
+---
+
+## Usage
+
+```bash
+# Full panorama (all epics, all stories)
+*status
+
+# Single epic
+*status epic-7
+
+# Summary only (no story details)
+*status --summary
+```
+
+### Arguments
+
+| Argument  | Required | Description                            |
+| --------- | -------- | -------------------------------------- |
+| epic-id   | No       | Show only specific epic (e.g. epic-7)  |
+| --summary | No       | Show only epic-level counts            |
+
+---
+
+## CRITICAL RULES
+
+### Rule 1: Source of Truth
+
+The **ONLY** source of truth for story status is the `## Status` field in each story file (`docs/stories/{N}.{M}.*.md`). **NEVER** use:
+
+- ❌ Epic file metadata (`status: "In Progress (1/2 done)"`)
+- ❌ Git log or gitStatus snapshot from system prompt
+- ❌ Cached data from previous reads in the conversation
+- ❌ Subagent summaries that don't read every story file
+- ❌ Assumptions based on which stories have files vs not
+
+### Rule 2: Read Every File
+
+Every execution of `*status` MUST read the `## Status` field from **every** story file that exists. No shortcuts, no sampling, no relying on epic summaries.
+
+### Rule 3: Divergence Detection
+
+If an epic file's progress count (e.g., "1/2 done") does not match the actual status of its stories, **flag the divergence** visually with ⚠️ and suggest updating the epic file.
+
+---
+
+## Workflow
+
+```yaml
+steps:
+  - name: Discover Epics
+    action: |
+      Glob: docs/stories/epic-*.md
+      Read each epic file to extract:
+        - epic_id, title, status (from metadata block)
+        - Story references (from ## Stories section)
+
+  - name: Discover Stories
+    action: |
+      Glob: docs/stories/[0-9]*.md
+      This finds ALL story files (e.g., 7.1.*.md, 8.3.*.md, 9.1.*.md)
+
+  - name: Read Story Status (MANDATORY)
+    action: |
+      For EACH story file found in Step 2:
+        Read the file and extract:
+          - Story title: first line starting with "# "
+          - Status: the line immediately after "## Status" heading,
+            trimmed of "**" markers and whitespace.
+            Do NOT rely on fixed line numbers — the Status section
+            position may vary across story templates.
+        Map story to its epic (first number = epic_id)
+    critical: true
+    note: |
+      This step CANNOT be skipped or delegated to a subagent
+      that might use cached data. Each file MUST be read fresh.
+
+  - name: Cross-Reference & Detect Divergence
+    action: |
+      Normalize status values before counting:
+        - "Ready" | "Ready for Dev" | "Ready to Start" → Ready
+        - "InProgress" | "In Progress" → InProgress
+        - "InReview" | "In Review" | "Ready for Review" → InReview
+        - "Done" | "Complete" | "Completed" → Done
+        - "Draft" → Draft
+        - Anything else → Unknown (flag with ⚠️)
+      For each epic:
+        - Count stories by normalized status (Done, Ready, Draft, InProgress, etc.)
+        - Compare with epic file's stated progress
+        - If mismatch: mark with ⚠️ DIVERGENCE flag
+      For stories referenced in epics but without story files:
+        - Mark as "📄 No story file"
+
+  - name: Format Output
+    action: |
+      Display formatted panorama with:
+        - Epic-level summary table (all epics)
+        - Story-level detail per epic (status from source of truth)
+        - Divergence warnings (if any)
+        - Quality metrics (test count, lint, typecheck — from last known)
+        - Next steps recommendation
+```
+
+---
+
+## Output Format
+
+### Full Panorama
+
+```text
+📊 Status Completo — {Project Name}
+
+Panorama Geral: {done}/{total} stories done ({percentage}%)
+
+═══════════════════════════════════════════════════════
+
+Epic 1 — Foundation & Shell                    3/3 ✅
+  ✅ 1.1 Project Scaffold & Database Setup     Done
+  ✅ 1.2 Filesystem Scanner Core               Done
+  ✅ 1.3 App Shell & Layout                    Done
+
+Epic 7 — Critical Fixes & Data Config         2/2 ✅
+  ✅ 7.1 Fix Critical Bugs                     Done
+  ✅ 7.2 Squad Origin Corrections              Done
+  ⚠️  DIVERGÊNCIA: Epic diz "1/2 done" mas stories indicam 2/2 Done
+
+Epic 9 — Functional Enhancements              0/2
+  📄 9.1 (no story file found)
+  📄 9.2 (no story file found)
+
+═══════════════════════════════════════════════════════
+
+Qualidade: {test_count} testes | Lint: {status} | TypeCheck: {status}
+
+Próximo: {next story recommendation}
+```
+
+### Status Icons
+
+| Icon | Status      | Description                    |
+| ---- | ----------- | ------------------------------ |
+| ✅   | Done        | Story completed and QA passed  |
+| 🔄   | InProgress  | Story being implemented        |
+| ⏳   | Ready       | Story validated, ready for dev |
+| 📝   | Draft       | Story created, not validated   |
+| 🔍   | InReview    | Story in QA review             |
+| 📄   | —           | No story file exists           |
+| ⚠️   | DIVERGENCE  | Epic metadata doesn't match    |
+
+---
+
+## Divergence Resolution
+
+When divergence is detected, suggest the fix:
+
+```text
+⚠️  DIVERGÊNCIA detectada em Epic 7:
+    Epic file diz: "In Progress (1/2 stories done)"
+    Stories reais: 2/2 Done
+
+    Sugestão: Atualizar epic-7-critical-fixes-data-config.md
+      status: "Done (2/2 stories done)"
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Directory docs/stories/ exists
+    tipo: pre-condition
+    blocker: true
+    error_message: "No docs/stories/ directory found"
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] Every story file in docs/stories/ was read for status
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Count of story files read == count of story files found by Glob
+    error_message: "Not all story files were read — status may be inaccurate"
+```
+
+---
+
+## Anti-Patterns (NEVER DO)
+
+1. **NEVER** rely on epic files for story status — epics are summaries that can be stale
+2. **NEVER** use gitStatus snapshot — it's frozen at conversation start
+3. **NEVER** delegate to a subagent without explicit instruction to "read the ## Status section of EVERY story file"
+4. **NEVER** assume a story doesn't exist without running Glob first
+5. **NEVER** report status without having read the actual `## Status` field from the file
+6. **NEVER** use git log to infer story completion
+
+---
+
+## Error Handling
+
+**Strategy:** graceful-fallback
+
+**Common Errors:**
+
+1. **Error:** Story file has no Status field
+   - **Resolution:** Report as "⚠️ Status field missing"
+   - **Recovery:** Flag for manual review
+
+2. **Error:** Epic references story that has no file
+   - **Resolution:** Report as "📄 No story file"
+   - **Recovery:** Note in output, continue with other stories
+
+3. **Error:** Story file exists but is not referenced in any epic
+   - **Resolution:** Report as orphan story
+   - **Recovery:** List in "Orphan Stories" section
+
+---
+
+## Performance
+
+```yaml
+duration_expected: 10-30 seconds
+cost_estimated: $0.001-0.005
+token_usage: ~1,000-5,000 tokens
+optimization: |
+  Read each story file and search for the ## Status section heading.
+  Use parallel Read calls for multiple story files.
+  Cache nothing — always read fresh.
+```
+
+---
+
+## Metadata
+
+```yaml
+version: 1.0.0
+tags:
+  - project-management
+  - status
+  - panorama
+updated_at: 2026-03-05
+agents: [aiox-master, po, sm]
+```
+
+---
+
+## Related Commands
+
+- `*orchestrate-status {story-id}` — Status de uma story específica em orquestração
+- `*build-status {story-id}` — Status de build autônomo
+- `*stories-index` — Regenerar índice de stories
+
+---
+
+## User Preferences
+
+- **Full panorama by default:** Always show ALL epics and ALL stories, not just current epic
+- **Include progress counts, story statuses, and next steps**
+
+---
+
+_Task criada para resolver o problema de status reporting impreciso — garantindo que `*status` sempre leia a fonte da verdade (story files) ao invés de dados derivados (epic metadata, git log)._

package/.aiox-core/development/tasks/validate-workflow.md

@@ -190,8 +190,8 @@ acceptance-criteria:
    - **Recovery:** Show line/column of syntax error
 
 3. **Error:** Missing Required Fields
-   - **Cause:** Workflow missing workflow.id, workflow.name, or sequence
-   - **Resolution:** Add missing fields to workflow YAML
+   - **Cause:** Workflow missing workflow.id, workflow.name, or execution array
+   - **Resolution:** Add `workflow.sequence` (official). `workflow.phases` is accepted for compatibility only.
    - **Recovery:** Show which fields are missing with examples
 
 ---