overseer.advance_phase

Advance project phases by validating deliverables and transitioning to the next phase, ensuring structured workflow progression in software development.

Instructions

Advance a phase to the next phase after validating all deliverables are complete. Marks current phase as "locked" and sets next phase as current.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`repo_root`	Yes	Root path of the repository
`expected_current_phase`	Yes	Phase ID that should currently be active (e.g., "01", "02")

Implementation Reference

src/tools/advance-phase.ts:29-266 (handler)

The primary handler function executing the overseer.advance_phase tool logic: checks completion of deliverables and criteria, advances phase status, updates repository files (PHASES.md and PHASE-XX.md).

export async function handleAdvancePhase(
  args: {
    repo_root: string;
    expected_current_phase: string;
  },
  phaseManager: PhaseManager
): Promise<{
  success: boolean;
  message: string;
  status: 'advanced' | 'incomplete';
  current_phase: {
    id: string;
    name: string;
    status: string;
  } | null;
  next_phase: {
    id: string;
    name: string;
    status: string;
  } | null;
  missing_items: Array<{
    type: 'deliverable' | 'done_criterion';
    item: string;
    reason: string;
  }>;
  changes_applied: string[];
}> {
  const missingItems: Array<{ type: 'deliverable' | 'done_criterion'; item: string; reason: string }> = [];
  const changesApplied: string[] = [];

  try {
    // Resolve repo path
    let repoPath = args.repo_root;
    if (!repoPath.startsWith('/')) {
      repoPath = join(homedir(), 'dev', repoPath);
    }
    repoPath = FSUtils.expandPath(repoPath);

    const expectedPhaseId = args.expected_current_phase.padStart(2, '0');

    // Read PHASES.md using absolute path (handles paths with spaces)
    const repoName = repoPath.split('/').pop() || 'unknown';
    const repoHandler = new RepoHandler();
    const projectPhases = repoHandler.readPhasesIndexFromPath(repoPath);

    if (!projectPhases) {
      return {
        success: false,
        message: 'Project not found. Run plan_project first.',
        status: 'incomplete',
        current_phase: null,
        next_phase: null,
        missing_items: [],
        changes_applied: [],
      };
    }

    // Find the expected phase
    const currentPhase = projectPhases.phases.find(p => p.id === expectedPhaseId);
    if (!currentPhase) {
      return {
        success: false,
        message: `Phase ${expectedPhaseId} not found`,
        status: 'incomplete',
        current_phase: null,
        next_phase: null,
        missing_items: [],
        changes_applied: [],
      };
    }

    // Verify this is the current phase
    if (currentPhase.status !== 'in_progress' && currentPhase.status !== 'active') {
      return {
        success: false,
        message: `Phase ${expectedPhaseId} is not currently active (status: ${currentPhase.status})`,
        status: 'incomplete',
        current_phase: {
          id: currentPhase.id,
          name: currentPhase.name,
          status: currentPhase.status,
        },
        next_phase: null,
        missing_items: [],
        changes_applied: [],
      };
    }

    // Read PHASE-XX.md to check deliverables and done criteria (handles paths with spaces)
    const phaseFilePath = repoHandler.getPhaseFileByIdFromPath(repoPath, expectedPhaseId);
    if (!FSUtils.fileExists(phaseFilePath)) {
      return {
        success: false,
        message: `Phase file PHASE-${expectedPhaseId}.md not found`,
        status: 'incomplete',
        current_phase: {
          id: currentPhase.id,
          name: currentPhase.name,
          status: currentPhase.status,
        },
        next_phase: null,
        missing_items: [{ type: 'deliverable', item: 'Phase file', reason: 'PHASE-XX.md file missing' }],
        changes_applied: [],
      };
    }

    const phaseContent = FSUtils.readFile(phaseFilePath);

    // Extract deliverables and check completion
    const deliverablesMatch = phaseContent.match(/## Deliverables\s*\n((?:- \[[ x]\] .+\n?)+)/);
    if (deliverablesMatch) {
      const items = deliverablesMatch[1].match(/- \[([ x])\] (.+)/g);
      if (items) {
        items.forEach(item => {
          const checked = item.startsWith('- [x]');
          const text = item.replace(/- \[[ x]\] /, '').trim();
          if (!checked) {
            missingItems.push({
              type: 'deliverable',
              item: text,
              reason: 'Deliverable not marked as complete in checklist',
            });
          } else {
            // Verify the deliverable actually exists
            const verification = verifyDeliverableExists(text, repoPath);
            if (!verification.exists) {
              missingItems.push({
                type: 'deliverable',
                item: text,
                reason: verification.reason,
              });
            }
          }
        });
      }
    }

    // Extract done criteria and check completion
    const doneCriteriaMatch = phaseContent.match(/## Done Criteria\s*\n((?:- \[[ x]\] .+\n?)+)/);
    if (doneCriteriaMatch) {
      const items = doneCriteriaMatch[1].match(/- \[([ x])\] (.+)/g);
      if (items) {
        items.forEach(item => {
          const checked = item.startsWith('- [x]');
          const text = item.replace(/- \[[ x]\] /, '').trim();
          if (!checked) {
            missingItems.push({
              type: 'done_criterion',
              item: text,
              reason: 'Done criterion not marked as complete in checklist',
            });
          } else {
            // Verify the criterion is actually met
            const verification = verifyCriterionMet(text, repoPath);
            if (!verification.met) {
              missingItems.push({
                type: 'done_criterion',
                item: text,
                reason: verification.reason,
              });
            }
          }
        });
      }
    }

    // If there are missing items, return incomplete
    if (missingItems.length > 0) {
      return {
        success: true,
        message: `Phase ${expectedPhaseId} is incomplete. ${missingItems.length} item(s) missing.`,
        status: 'incomplete',
        current_phase: {
          id: currentPhase.id,
          name: currentPhase.name,
          status: currentPhase.status,
        },
        next_phase: null,
        missing_items: missingItems,
        changes_applied: [],
      };
    }

    // All items complete - advance the phase
    // Mark current phase as "locked" (completed)
    currentPhase.status = 'locked';
    currentPhase.completed_at = new Date().toISOString();
    changesApplied.push(join(repoPath, 'PHASES.md'));

    // Update phase file with completion summary
    const updatedPhaseContent = addCompletionSummary(phaseContent, currentPhase);
    FSUtils.writeFile(phaseFilePath, updatedPhaseContent);
    changesApplied.push(phaseFilePath);

    // Find and activate next phase
    const currentPhaseIndex = projectPhases.phases.findIndex(p => p.id === expectedPhaseId);
    let nextPhase = null;
    
    if (currentPhaseIndex < projectPhases.phases.length - 1) {
      nextPhase = projectPhases.phases[currentPhaseIndex + 1];
      nextPhase.status = 'in_progress';
      nextPhase.started_at = new Date().toISOString();
      changesApplied.push(join(repoPath, 'PHASES.md'));
    }

    // Write updated PHASES.md using absolute path
    repoHandler.writePhasesIndexToPath(repoPath, projectPhases);

    return {
      success: true,
      message: `Phase ${expectedPhaseId} advanced successfully. ${nextPhase ? `Next phase ${nextPhase.id} activated.` : 'No more phases.'}`,
      status: 'advanced',
      current_phase: {
        id: currentPhase.id,
        name: currentPhase.name,
        status: currentPhase.status,
      },
      next_phase: nextPhase ? {
        id: nextPhase.id,
        name: nextPhase.name,
        status: nextPhase.status,
      } : null,
      missing_items: [],
      changes_applied: changesApplied,
    };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    return {
      success: false,
      message: `Failed to advance phase: ${errorMessage}`,
      status: 'incomplete',
      current_phase: null,
      next_phase: null,
      missing_items: [],
      changes_applied: [],
    };
  }
}

src/tools/advance-phase.ts:8-27 (schema)

Creates the Tool object defining the name, description, and input schema for overseer.advance_phase.

export function createAdvancePhaseTool(phaseManager: PhaseManager): Tool {
  return {
    name: 'overseer.advance_phase',
    description: 'Advance a phase to the next phase after validating all deliverables are complete. Marks current phase as "locked" and sets next phase as current.',
    inputSchema: {
      type: 'object',
      required: ['repo_root', 'expected_current_phase'],
      properties: {
        repo_root: {
          type: 'string',
          description: 'Root path of the repository',
        },
        expected_current_phase: {
          type: 'string',
          description: 'Phase ID that should currently be active (e.g., "01", "02")',
        },
      },
    },
  };
}

src/tools/index.ts:22-41 (registration)

Registers the advance phase tool in the list of available tools via createTools.

export function createTools(context: ToolContext): Tool[] {
  return [
    // Planning tools
    createPlanProjectTool(context.phaseManager),
    createInferPhasesTool(context.configLoader),
    createUpdatePhasesTool(context.phaseManager),
    // Execution tools
    createRunPhaseTool(context.phaseManager),
    createAdvancePhaseTool(context.phaseManager),
    createStatusTool(context.phaseManager),
    // QA tools
    createLintRepoTool(context.configLoader),
    createSyncDocsTool(context.phaseManager),
    createCheckComplianceTool(context.phaseManager),
    // Environment tools
    createEnvMapTool(context.phaseManager),
    createGenerateCiTool(context.phaseManager),
    createSecretsTemplateTool(context.phaseManager),
  ];
}

src/tools/index.ts:59-60 (registration)
Registers the handler for overseer.advance_phase in the tool dispatcher switch statement.
```
case 'overseer.advance_phase':
  return await handleAdvancePhase(args, context.phaseManager);
```

src/tools/advance-phase.ts:268-304 (helper)

Helper function to verify if deliverables (files/directories) actually exist in the repo.

function verifyDeliverableExists(deliverable: string, repoPath: string): { exists: boolean; reason: string } {
  // Check for file references
  const filePattern = /([a-zA-Z0-9_\-./]+\.(md|ts|js|json|yml|yaml|txt|py|java|go|rs|php|rb|ex|exs))/g;
  const fileMatches = deliverable.match(filePattern);

  if (fileMatches) {
    for (const fileRef of fileMatches) {
      const filePath = join(repoPath, fileRef);
      if (!FSUtils.fileExists(filePath)) {
        return {
          exists: false,
          reason: `File ${fileRef} does not exist`,
        };
      }
    }
    return { exists: true, reason: '' };
  }

  // Check for directory references
  const dirPattern = /(src|app|lib|tests|docs|config|dist|build)\//;
  if (dirPattern.test(deliverable)) {
    const dirMatch = deliverable.match(dirPattern);
    if (dirMatch) {
      const dirPath = join(repoPath, dirMatch[1]);
      if (!FSUtils.dirExists(dirPath)) {
        return {
          exists: false,
          reason: `Directory ${dirMatch[1]}/ does not exist`,
        };
      }
    }
    return { exists: true, reason: '' };
  }

  // Generic deliverable - assume exists if we can't verify
  return { exists: true, reason: '' };
}

Overseer MCP Server