import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
import { join } from 'path';
import { v7 as ulid } from 'ulid';

// Phase definitions with strict transition rules
type MissionPhase = 'SPECIFY' | 'PLAN' | 'TASKS' | 'IMPLEMENT' | 'REVIEW' | 'MERGE';

interface PhaseGate {
  phase: MissionPhase;
  requiredArtifacts: string[];
  validate(): boolean;
}

interface WorkPackage {
  id: string;
  title: string;
  status: 'PENDING' | 'IN_PROGRESS' | 'REVIEW' | 'APPROVED' | 'REJECTED';
  files: string[];
}

class MissionOrchestrator {
  private missionRoot: string;
  private currentPhase: MissionPhase = 'SPECIFY';
  private auditLog: string[] = [];

  constructor(slug: string) {
    const missionId = ulid();
    this.missionRoot = join('kitty-specs', `${slug}-${missionId}`);
    this.initializeDirectory();
    this.logEvent('MISSION_CREATED', { slug, missionId });
  }

  private initializeDirectory(): void {
    const dirs = ['checklists', 'research'];
    mkdirSync(this.missionRoot, { recursive: true });
    dirs.forEach(d => mkdirSync(join(this.missionRoot, d), { recursive: true }));
  }

  private logEvent(event: string, payload: Record<string, unknown>): void {
    const entry = JSON.stringify({ timestamp: Date.now(), event, payload });
    this.auditLog.push(entry);
    writeFileSync(join(this.missionRoot, 'mission-events.jsonl'), entry + '\n', { flag: 'a' });
  }

  private validatePhaseTransition(nextPhase: MissionPhase): boolean {
    const gate: PhaseGate = {
      phase: this.currentPhase,
      requiredArtifacts: this.getRequiredArtifacts(this.currentPhase),
      validate: () => {
        return this.getRequiredArtifacts(this.currentPhase).every(art =>
          existsSync(join(this.missionRoot, art))
        );
      }
    };

    if (!gate.validate()) {
      throw new Error(`Phase gate failed: missing required artifacts for ${this.currentPhase}`);
    }

    this.currentPhase = nextPhase;
    this.logEvent('PHASE_TRANSITION', { from: gate.phase, to: nextPhase });
    return true;
  }

  private getRequiredArtifacts(phase: MissionPhase): string[] {
    const map: Record<MissionPhase, string[]> = {
      SPECIFY: ['spec.md', 'checklists/requirements.md'],

  PLAN: ['plan.md', 'research/evidence-log.csv'],
  TASKS: ['tasks.json'],
  IMPLEMENT: ['status.json'],
  REVIEW: ['review-report.md'],
  MERGE: []
};
return map[phase];

}

public executePhase(phase: MissionPhase): void { if (phase !== this.currentPhase) { throw new Error(Invalid phase execution. Expected ${this.currentPhase}, got ${phase}); }

switch (phase) {
  case 'SPECIFY': this.runSpecifyPhase(); break;
  case 'PLAN': this.runPlanPhase(); break;
  case 'TASKS': this.runTasksPhase(); break;
  case 'IMPLEMENT': this.runImplementPhase(); break;
  case 'REVIEW': this.runReviewPhase(); break;
  case 'MERGE': this.runMergePhase(); break;
}

}

private runSpecifyPhase(): void { const spec = # Mission Specification\n\n## Scope\nDomain modeling for knowledge service.\n## Constraints\nMust align with existing migration patterns.\n## Acceptance Criteria\n- Architecture docs generated\n- Data model migration validated\n- Test suites passing; writeFileSync(join(this.missionRoot, 'spec.md'), spec); writeFileSync(join(this.missionRoot, 'checklists/requirements.md'), '- [x] Scope defined\n- [x] Constraints documented'); this.logEvent('ARTIFACT_WRITTEN', { file: 'spec.md' }); }

private runPlanPhase(): void { const plan = # Implementation Plan\n\n## Approach\nDecompose domain model into entity boundaries.\n## Evidence\n- Schema analysis: research/source-register.csv\n- Migration strategy: research/evidence-log.csv; writeFileSync(join(this.missionRoot, 'plan.md'), plan); writeFileSync(join(this.missionRoot, 'research/evidence-log.csv'), 'timestamp,source,finding\n1715000000,waaseyaa/docs,entity-boundary-mapping'); this.logEvent('ARTIFACT_WRITTEN', { file: 'plan.md' }); }

private runTasksPhase(): void { const tasks = [ { id: 'WP01', title: 'Domain entity definitions', status: 'PENDING', files: ['src/entities/User.ts'] }, { id: 'WP02', title: 'Migration alignment', status: 'PENDING', files: ['migrations/001_init.sql'] } ]; writeFileSync(join(this.missionRoot, 'tasks.json'), JSON.stringify(tasks, null, 2)); this.logEvent('ARTIFACT_WRITTEN', { file: 'tasks.json' }); }

private runImplementPhase(): void { const status = { phase: 'IMPLEMENT', wps: 2, approved: 0, rejected: 0 }; writeFileSync(join(this.missionRoot, 'status.json'), JSON.stringify(status, null, 2)); this.logEvent('ARTIFACT_WRITTEN', { file: 'status.json' }); }

private runReviewPhase(): void { const report = # Review Report\n\n## WP01: Approved\n## WP02: Approved\n## Notes\nAll acceptance criteria met. Tests passing.; writeFileSync(join(this.missionRoot, 'review-report.md'), report); this.logEvent('ARTIFACT_WRITTEN', { file: 'review-report.md' }); }

private runMergePhase(): void { this.logEvent('MISSION_TERMINAL', { state: 'MERGED', artifacts: 13 }); console.log(Mission complete. Directory: ${this.missionRoot}); }

public advance(): void { const phases: MissionPhase[] = ['SPECIFY', 'PLAN', 'TASKS', 'IMPLEMENT', 'REVIEW', 'MERGE']; const currentIndex = phases.indexOf(this.currentPhase); if (currentIndex < phases.length - 1) { const nextPhase = phases[currentIndex + 1]; this.validatePhaseTransition(nextPhase); } else { throw new Error('Mission already in terminal state'); } } }

// Usage const mission = new MissionOrchestrator('giiken-domain-modeling'); mission.executePhase('SPECIFY'); mission.advance(); mission.executePhase('PLAN'); mission.advance(); mission.executePhase('TASKS'); mission.advance(); mission.executePhase('IMPLEMENT'); mission.advance(); mission.executePhase('REVIEW'); mission.advance(); mission.executePhase('MERGE');

### Why This Architecture Works

The orchestrator enforces deterministic progression by coupling phase execution with artifact validation. Each phase writes specific files that serve as inputs for the next phase. The `validatePhaseTransition` method acts as a circuit breaker, preventing execution from proceeding until all required artifacts exist. JSONL logging ensures that every state change, artifact write, and transition is recorded chronologically. This design eliminates ambiguity, supports external inspection, and guarantees that the mission directory remains a complete, self-documenting record of the entire lifecycle.

## Pitfall Guide

### 1. Treating Specifications as Optional Documentation
**Explanation:** Teams often skip rigorous `spec.md` generation, assuming the agent will infer requirements from the prompt. This leads to scope drift and misaligned deliverables.
**Fix:** Enforce `spec.md` as a hard contract. Require explicit acceptance criteria, constraints, and boundary definitions before allowing phase progression.

### 2. Bypassing Review Gates for Speed
**Explanation:** Pressure to ship code leads to skipping the `REVIEW` phase or marking work packages as approved without validation. This corrupts the audit trail and introduces unverified changes.
**Fix:** Implement strict state validation in the orchestrator. Reject any transition to `MERGE` if work packages remain in `PENDING` or `REVIEW` states.

### 3. Overloading Work Packages
**Explanation:** Decomposing plans into monolithic work packages makes parallel execution impossible and complicates review. Agents struggle to maintain context across large scopes.
**Fix:** Limit each WP to a single cohesive change set. Ensure WPs are independently testable and reviewable. Target 3-7 WPs per mission for optimal throughput.

### 4. Ignoring the Evidence Trail
**Explanation:** Teams focus on code output and neglect `research/` directories, CSVs, and source registers. This breaks traceability and makes future audits impossible.
**Fix:** Mandate artifact generation per phase. Require `source-register.csv` for external references and `evidence-log.csv` for decision justification. Treat these as first-class deliverables.

### 5. Assuming JSONL Logs Are Debugging Artifacts
**Explanation:** Audit logs are often treated as transient debugging output rather than immutable records. This leads to log rotation, truncation, or manual editing.
**Fix:** Store JSONL files with append-only permissions. Implement log verification checksums. Treat the audit trail as a compliance ledger, not a debugging tool.

### 6. Mixing Agent and Human Context
**Explanation:** Storing agent runtime state and human review notes in the same files creates merge conflicts and context pollution.
**Fix:** Separate `meta.json` (agent runtime state, ULID, timestamps) from `status.json` (pipeline state, WP statuses). Keep human annotations in dedicated `review-report.md` or `checklists/` files.

### 7. No Rollback Strategy on Gate Failure
**Explanation:** When a phase gate fails, teams often delete the mission directory and restart. This loses partial progress and audit history.
**Fix:** Implement checkpointing via `status.events.jsonl`. Store the last validated phase and allow the orchestrator to resume from that state without re-executing completed phases.

## Production Bundle

### Action Checklist
- [ ] Initialize mission directory with ULID-suffixed slug and required subdirectories
- [ ] Generate `spec.md` with explicit acceptance criteria and constraints
- [ ] Populate `checklists/requirements.md` and mark validation items
- [ ] Create `plan.md` referencing `research/evidence-log.csv` and `source-register.csv`
- [ ] Decompose plan into independent work packages in `tasks.json`
- [ ] Execute implementation phases with strict artifact validation per transition
- [ ] Run review gates and generate `review-report.md` before merge
- [ ] Verify `mission-events.jsonl` contains complete chronological audit trail

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Small, well-defined feature | Stateless prompt + direct commit | Low overhead, fast iteration | Minimal compute cost |
| Multi-agent handoff required | State-machine mission pipeline | Ensures context persistence and deterministic resumption | Moderate storage cost, higher initial setup |
| Compliance/audit required | JSONL-backed mission with hard gates | Immutable trail, phase validation, artifact traceability | Higher storage, strict process overhead |
| Experimental/prototype | Conversational agent + manual docs | Flexibility, rapid iteration | Low process cost, high context loss risk |
| Production domain modeling | Spec Kitty-style lifecycle | Enforces structure, evidence trail, WP decomposition | Balanced cost, high reliability |

### Configuration Template

```json
{
  "mission": {
    "slug": "project-domain-modeling",
    "version": "1.0.0",
    "phases": ["SPECIFY", "PLAN", "TASKS", "IMPLEMENT", "REVIEW", "MERGE"],
    "gate_policy": "HARD",
    "audit_format": "JSONL",
    "artifacts": {
      "spec": "spec.md",
      "plan": "plan.md",
      "tasks": "tasks.json",
      "status": "status.json",
      "review": "review-report.md",
      "checklist": "checklists/requirements.md",
      "evidence": "research/evidence-log.csv",
      "sources": "research/source-register.csv"
    },
    "work_packages": {
      "max_per_mission": 7,
      "independent_review": true,
      "parallel_execution": true
    }
  }
}

Quick Start Guide

1. Initialize the pipeline: Create a new mission directory using the ULID-slug naming convention. Run the orchestrator constructor with your project slug to generate the base structure.
2. Define the contract: Populate spec.md with scope, constraints, and acceptance criteria. Complete checklists/requirements.md to mark validation items.
3. Execute phase transitions: Run executePhase() for each lifecycle stage. Call advance() to validate gates and move to the next phase. The orchestrator will block progression if required artifacts are missing.
4. Monitor audit trail: Inspect mission-events.jsonl for chronological state changes. Verify artifact generation matches the configuration template.
5. Terminate and merge: Once all work packages reach APPROVED, execute the MERGE phase. The pipeline will log the terminal state and finalize the mission directory for archival or handoff.