agentic-orchestrator 0.1.25 → 0.1.26

package/apps/control-plane/src/application/services/performance-analytics-service.ts

@@ -1,6 +1,10 @@
 import { atomicWriteJson, ensureDir, nowIso, readJson } from '../../core/fs.js';
 import path from 'node:path';
 
+/**
+ * @fileoverview Performance analytics and outcome tracking service.
+ */
+
 export interface FeatureOutcome {
   feature_id: string;
   provider: string;
@@ -73,6 +77,49 @@ function computeAggregates(outcomes: FeatureOutcome[]): ProviderModelStats[] {
   return aggregates;
 }
 
+/**
+ * Manages performance analytics and outcome tracking.
+ *
+ * ## Responsibilities
+ * - Record feature outcomes (status, retries, duration, cost)
+ * - Aggregate metrics by provider/model
+ * - Calculate success rates and averages
+ * - Provide analytics for dashboard
+ *
+ * ## Dependencies
+ * Depends on {@link PerformanceAnalyticsServicePort} for:
+ * - Analytics file path resolution
+ * - Timestamp utilities
+ *
+ * ## Key Methods
+ * - `recordOutcome()` - record feature outcome
+ * - `getAnalytics()` - retrieve aggregated metrics
+ * - `getProviderStats()` - get metrics by provider/model
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - analytics file does not exist
+ *
+ * @example
+ * ```typescript
+ * const perfService = new PerformanceAnalyticsService(port);
+ * await perfService.recordOutcome({
+ *   feature_id: 'my_feature',
+ *   status: 'merged',
+ *   provider: 'claude',
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   retries: 2,
+ *   duration_ms: 300000,
+ *   cost_usd: 1.50
+ * });
+ * const analytics = await perfService.getAnalytics();
+ * ```
+ *
+ * ## Metrics Tracked
+ * - Success rate by provider/model
+ * - Average cost per feature
+ * - Average duration per phase
+ * - Retry counts and reasons
+ */
 export class PerformanceAnalyticsService {
   private readonly port: PerformanceAnalyticsServicePort;
 
@@ -80,6 +127,25 @@ export class PerformanceAnalyticsService {
     this.port = port;
   }
 
+  /**
+   * Records feature outcome for analytics.
+   *
+   * @param outcome - outcome data (status, retries, duration, cost, provider, model)
+   * @returns Updated analytics snapshot
+   *
+   * @example
+   * ```typescript
+   * await perfService.recordOutcome({
+   *   feature_id: 'my_feature',
+   *   status: 'merged',
+   *   provider: 'claude',
+   *   model: 'claude-3-5-sonnet-20241022',
+   *   retries: 2,
+   *   duration_ms: 300000,
+   *   cost_usd: 1.50
+   * });
+   * ```
+   */
   async recordOutcome(outcome: FeatureOutcome): Promise<AnalyticsSnapshot> {
     const filePath = this.port.analyticsPath();
     await ensureDir(path.dirname(filePath));
@@ -93,10 +159,34 @@ export class PerformanceAnalyticsService {
     return current;
   }
 
+  /**
+   * Retrieves aggregated performance analytics.
+   *
+   * @returns Analytics snapshot with provider/model metrics
+   *
+   * @example
+   * ```typescript
+   * const analytics = await perfService.getAnalytics();
+   * console.log(analytics.by_provider);
+   * ```
+   */
   async getAnalytics(): Promise<AnalyticsSnapshot> {
     return await this.readSnapshot();
   }
 
+  /**
+   * Retrieves provider/model statistics with optional filtering.
+   *
+   * @param provider - optional provider filter
+   * @param model - optional model filter
+   * @returns Array of provider/model stats
+   *
+   * @example
+   * ```typescript
+   * const stats = await perfService.getProviderStats('claude');
+   * console.log(stats[0].success_rate);
+   * ```
+   */
   async getProviderStats(provider?: string, model?: string): Promise<ProviderModelStats[]> {
     const snapshot = await this.readSnapshot();
     let stats = snapshot.aggregates;

package/apps/control-plane/src/application/services/plan-service.ts

@@ -165,10 +165,38 @@ export interface PlanServicePort {
  * - State and index operations
  * - File locking primitives
  *
+ * ## Key Methods
+ * - `planSubmit()` - submit initial plan with full validation
+ * - `planUpdate()` - submit versioned plan revision
+ * - `planGet()` - retrieve accepted plan
+ * - `checkPlanCollision()` - detect collisions with other features
+ * - `assertPlanLocksHeld()` - verify required locks are held
+ *
+ * ## Error Conditions
+ * - SCHEMA_VALIDATION_FAILED - plan fails JSON schema validation
+ * - PLAN_COLLISION - file/area/contract conflicts with another feature
+ * - LOCK_NOT_HELD - required resource locks not acquired
+ * - VERSION_CONFLICT - plan version mismatch (concurrent update)
+ * - DEPENDENCY_CYCLE - circular feature dependencies detected
+ *
  * ## Thread Safety
  * All mutations are protected by feature-level or index-level locks.
  * Concurrent reads are safe. Concurrent writes are serialized.
  *
+ * @example
+ * ```typescript
+ * const planService = new PlanService(port);
+ *
+ * // Submit initial plan
+ * await planService.planSubmit('my_feature', planData, null);
+ *
+ * // Update plan with version guard
+ * await planService.planUpdate('my_feature', updatedPlan, 1);
+ *
+ * // Check for collisions
+ * const result = await planService.checkPlanCollision('my_feature', planData);
+ * ```
+ *
  * @see CollisionDetector - for collision detection algorithm
  * @see GateSelectionService - for gate profile selection
  */
@@ -181,6 +209,19 @@ export class PlanService {
     this.gateSelectionService = new GateSelectionService(port);
   }
 
+  /**
+   * Retrieves the accepted plan for a feature.
+   *
+   * @param featureId - feature identifier
+   * @returns Plan data wrapped in success response
+   * @throws FILE_NOT_FOUND - plan file does not exist
+   *
+   * @example
+   * ```typescript
+   * const result = await planService.planGet('my_feature');
+   * console.log(result.data.plan);
+   * ```
+   */
   async planGet(featureId: string): Promise<{ data: { feature_id: string; plan: unknown } }> {
     const plan = await readJson(this.port.planPath(featureId), null);
     return {
@@ -191,6 +232,20 @@ export class PlanService {
     };
   }
 
+  /**
+   * Collects all accepted plans from discovered features.
+   *
+   * Used for collision detection and dependency analysis.
+   *
+   * @param excludeFeatureId - optional feature to exclude from collection
+   * @returns Array of plan objects
+   *
+   * @example
+   * ```typescript
+   * // Get all plans except current feature
+   * const plans = await planService.collectAcceptedPlans('my_feature');
+   * ```
+   */
   async collectAcceptedPlans(excludeFeatureId: string | null = null): Promise<AnyRecord[]> {
     const specs = await this.port.featureDiscoverSpecs();
     const plans: AnyRecord[] = [];
@@ -206,6 +261,20 @@ export class PlanService {
     return plans;
   }
 
+  /**
+   * Determines required resource locks based on plan contracts.
+   *
+   * Maps contract modifications to resource identifiers per policy.
+   *
+   * @param plan - plan object with contracts section
+   * @returns Sorted array of required resource identifiers
+   *
+   * @example
+   * ```typescript
+   * const resources = planService.requiredResourcesForPlan(plan);
+   * // ['openapi', 'db_migrations']
+   * ```
+   */
   requiredResourcesForPlan(plan: AnyRecord): string[] {
     const resources: string[] = [];
     const policy = this.port.getPolicySnapshot();
@@ -221,6 +290,18 @@ export class PlanService {
     return sortResourcesDeterministically(resources);
   }
 
+  /**
+   * Verifies that all required resource locks are held by the feature.
+   *
+   * @param featureId - feature identifier
+   * @param plan - plan object requiring locks
+   * @throws LOCK_NOT_HELD - required locks are not held
+   *
+   * @example
+   * ```typescript
+   * await planService.assertPlanLocksHeld('my_feature', plan);
+   * ```
+   */
   async assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<void> {
     const state = await this.port.readState(featureId);
     const held = new Set(readHeldLocks(state.frontMatter));
@@ -243,6 +324,20 @@ export class PlanService {
     }
   }
 
+  /**
+   * Validates plan revision rules for versioning and optimistic concurrency.
+   *
+   * Enforces:
+   * - Initial plans must be version 1 without revision_of
+   * - Updates must increment version and reference previous version
+   * - Version guard must match current plan version
+   *
+   * @param existingPlan - current plan or null for initial submission
+   * @param plan - new plan to validate
+   * @param expectedPlanVersion - expected current version for concurrency guard
+   * @throws PLAN_VALIDATION_FAILED - revision rules violated
+   * @throws VERSION_CONFLICT - version mismatch (concurrent update)
+   */
   validatePlanRevisionRules(
     existingPlan: AnyRecord | null,
     plan: AnyRecord,
@@ -289,6 +384,17 @@ export class PlanService {
     }
   }
 
+  /**
+   * Validates plan against JSON schema.
+   *
+   * @param plan - plan object to validate
+   * @throws SCHEMA_VALIDATION_FAILED - plan does not conform to schema
+   *
+   * @example
+   * ```typescript
+   * await planService.validatePlanSchema(planData);
+   * ```
+   */
   async validatePlanSchema(plan: AnyRecord): Promise<void> {
     const validation = await this.port.validateSchema('plan.schema.json', plan);
     if (!validation.valid) {
@@ -306,6 +412,24 @@ export class PlanService {
     }
   }
 
+  /**
+   * Detects file, area, and contract collisions with other features.
+   *
+   * Compares plan against all accepted plans to find conflicts.
+   *
+   * @param featureId - feature identifier
+   * @param plan - plan to check for collisions
+   * @returns Collision matrix with conflicts by feature
+   * @throws PLAN_COLLISION - collisions detected (per policy)
+   *
+   * @example
+   * ```typescript
+   * const result = await planService.checkPlanCollision('my_feature', plan);
+   * if (result.data.has_collisions) {
+   *   console.log(result.data.collisions);
+   * }
+   * ```
+   */
   async checkPlanCollision(featureId: string, plan: AnyRecord): Promise<unknown> {
     const policy = this.port.getPolicySnapshot();
     const acceptedPlans = await this.collectAcceptedPlans(featureId);
@@ -382,6 +506,17 @@ export class PlanService {
     };
   }
 
+  /**
+   * Validates feature dependencies and detects circular references.
+   *
+   * @param featureId - feature to check (null checks all features)
+   * @throws DEPENDENCY_CYCLE - circular dependency detected
+   *
+   * @example
+   * ```typescript
+   * await planService.checkDependencies('my_feature');
+   * ```
+   */
   async checkDependencies(featureId: string | null): Promise<void> {
     if (!featureId) {
       return;
@@ -443,6 +578,33 @@ export class PlanService {
     }
   }
 
+  /**
+   * Submits initial plan with full validation pipeline.
+   *
+   * Validation steps:
+   * 1. Schema validation
+   * 2. Revision rules check
+   * 3. Lock requirement verification
+   * 4. Collision detection
+   * 5. Dependency cycle check
+   * 6. Gate profile selection
+   *
+   * @param featureId - feature identifier
+   * @param plan - plan object to submit
+   * @param expectedVersion - expected state version for concurrency guard
+   * @returns Acceptance result with plan version
+   * @throws INVALID_ARGUMENT - missing or invalid plan
+   * @throws SCHEMA_VALIDATION_FAILED - plan schema invalid
+   * @throws LOCK_NOT_HELD - required locks not held
+   * @throws PLAN_COLLISION - collisions detected
+   * @throws DEPENDENCY_CYCLE - circular dependencies
+   *
+   * @example
+   * ```typescript
+   * const result = await planService.planSubmit('my_feature', planData, null);
+   * console.log(`Plan accepted: version ${result.data.plan_version}`);
+   * ```
+   */
   async planSubmit(
     featureId: string | null,
     plan: AnyRecord | null,
@@ -532,6 +694,28 @@ export class PlanService {
     };
   }
 
+  /**
+   * Submits versioned plan revision with full revalidation.
+   *
+   * Requires plan_version to be current_version + 1 and revision_of
+   * to reference current version. Runs full validation pipeline.
+   *
+   * @param featureId - feature identifier
+   * @param plan - updated plan object
+   * @param expectedPlanVersion - expected current plan version
+   * @returns Acceptance result with new plan version
+   * @throws VERSION_CONFLICT - plan version mismatch
+   * @throws PLAN_VALIDATION_FAILED - revision rules violated
+   * @throws SCHEMA_VALIDATION_FAILED - plan schema invalid
+   * @throws LOCK_NOT_HELD - required locks not held
+   * @throws PLAN_COLLISION - collisions detected
+   *
+   * @example
+   * ```typescript
+   * // Update plan from version 1 to version 2
+   * const result = await planService.planUpdate('my_feature', updatedPlan, 1);
+   * ```
+   */
   async planUpdate(
     featureId: string | null,
     expectedPlanVersion: number | null,

package/apps/control-plane/src/application/services/pr-monitor-service.ts

@@ -102,6 +102,38 @@ function mapReviewDecision(decision: string | null | undefined): ReviewDecision
   }
 }
 
+/**
+ * Monitors pull request status and handles review feedback.
+ *
+ * ## Responsibilities
+ * - Detect PRs for feature branches
+ * - Monitor PR status and review decisions
+ * - Handle changes_requested events
+ * - Store PR metadata in feature state
+ *
+ * ## Dependencies
+ * - {@link SupervisorToolCaller} - for tool invocation
+ * - {@link NotifierService} - for PR notifications
+ * - GitHub CLI - for PR queries
+ *
+ * ## Key Methods
+ * - `detectPr()` - detect PR for feature branch
+ * - `checkAndUpdate()` - check PR status and update state
+ * - `handleChangesRequested()` - handle review feedback
+ * - `storePrState()` - persist PR metadata
+ *
+ * ## Error Conditions
+ * - PR detection failures are logged but don't block
+ *
+ * @example
+ * ```typescript
+ * const prMonitor = new PrMonitorService({ toolCaller, notifier });
+ * const pr = await prMonitor.detectPr('my_feature', 'my_feature');
+ * if (pr) {
+ *   await prMonitor.checkAndUpdate('my_feature', 'my_feature');
+ * }
+ * ```
+ */
 export class PrMonitorService {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly notifier: NotifierService | undefined;
@@ -115,6 +147,13 @@ export class PrMonitorService {
     this.ghRunner = dependencies.ghRunner ?? createGhRunner();
   }
 
+  /**
+   * Detects PR for feature branch.
+   *
+   * @param featureId - feature identifier
+   * @param branch - branch name
+   * @returns PR info or null if not found
+   */
   async detectPr(featureId: string, branch: string): Promise<PrInfo | null> {
     const candidates = [
       ...new Set(
@@ -171,6 +210,12 @@ export class PrMonitorService {
     return { ...partial, merge_score };
   }
 
+  /**
+   * Stores PR metadata in feature state.
+   *
+   * @param featureId - feature identifier
+   * @param prInfo - PR information
+   */
   async storePrState(featureId: string, prInfo: PrInfo): Promise<void> {
     const current = await this.toolCaller.callTool<FeatureStatePayload>(
       'orchestrator',
@@ -215,6 +260,12 @@ export class PrMonitorService {
     return score;
   }
 
+  /**
+   * Handles changes_requested review decision.
+   *
+   * @param featureId - feature identifier
+   * @param prInfo - PR information with review decision
+   */
   async handleChangesRequested(featureId: string, prInfo: PrInfo): Promise<void> {
     const reaction = this.reactionsPolicy?.changes_requested;
     if (!reaction?.enabled) {
@@ -264,6 +315,13 @@ export class PrMonitorService {
     }
   }
 
+  /**
+   * Checks PR status and updates feature state.
+   *
+   * @param featureId - feature identifier
+   * @param branch - branch name
+   * @returns Updated PR info or null
+   */
   async checkAndUpdate(featureId: string, branch: string): Promise<PrInfo | null> {
     const prInfo = await this.detectPr(featureId, branch);
     if (!prInfo) {

package/apps/control-plane/src/application/services/qa-index-service.ts

@@ -6,11 +6,48 @@ import { fail } from '../../core/response.js';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
 
+/**
+ * @fileoverview QA test obligation tracking service.
+ */
+
 export interface QaIndexServicePort {
   qaIndexPath(featureId: string): string;
   validateSchema(schemaName: string, value: unknown): Promise<{ valid: boolean; errors?: unknown }>;
 }
 
+/**
+ * Manages QA test obligation tracking.
+ *
+ * ## Responsibilities
+ * - Create qa_test_index.json from diff hunks
+ * - Track test status per hunk (pending/covered/skipped)
+ * - Link evidence to test obligations
+ * - Validate all obligations are resolved
+ *
+ * ## Dependencies
+ * Depends on {@link QaIndexServicePort} for:
+ * - QA index file path resolution
+ * - Schema validation
+ *
+ * ## Key Methods
+ * - `qaTestIndexGet()` - retrieve test index
+ * - `qaTestIndexUpdate()` - update hunk statuses with evidence
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - index file does not exist
+ * - VERSION_CONFLICT - concurrent index update
+ * - SCHEMA_VALIDATION_FAILED - invalid index structure
+ *
+ * @example
+ * ```typescript
+ * const qaService = new QaIndexService(port);
+ * const index = await qaService.qaTestIndexGet('my_feature');
+ * await qaService.qaTestIndexUpdate('my_feature', updates, 1);
+ * ```
+ *
+ * ## Index Format
+ * Each hunk has: path, line range, required tests, status, evidence refs
+ */
 export class QaIndexService {
   private readonly port: QaIndexServicePort;
 
@@ -18,6 +55,20 @@ export class QaIndexService {
     this.port = port;
   }
 
+  /**
+   * Retrieves QA test index for a feature.
+   *
+   * @param featureId - feature identifier
+   * @returns Test index with hunk obligations and pending summary
+   * @throws FILE_NOT_FOUND - index does not exist
+   *
+   * @example
+   * ```typescript
+   * const index = await qaService.qaTestIndexGet('my_feature');
+   * console.log(index.data.items);
+   * console.log(index.data.pending_obligations);
+   * ```
+   */
   async qaTestIndexGet(featureId: string): Promise<{
     data: {
       index: AnyRecord;
@@ -53,6 +104,23 @@ export class QaIndexService {
     };
   }
 
+  /**
+   * Updates hunk statuses with evidence references and version guard.
+   *
+   * @param featureId - feature identifier
+   * @param updates - hunk status updates with evidence refs
+   * @param expectedVersion - expected index version
+   * @returns Updated index
+   * @throws VERSION_CONFLICT - version mismatch
+   * @throws SCHEMA_VALIDATION_FAILED - invalid updates
+   *
+   * @example
+   * ```typescript
+   * await qaService.qaTestIndexUpdate('my_feature', {
+   *   items: [{ path: 'file.ts', status: 'covered', evidence_refs: ['gate_123'] }]
+   * }, 1);
+   * ```
+   */
   async qaTestIndexUpdate(
     featureId: string,
     expectedVersion: number | null,

package/apps/control-plane/src/application/services/reactions-service.ts

@@ -5,6 +5,10 @@ import type {
 } from '../../core/tool-caller.js';
 import type { NotifierService } from './notifier-service.js';
 
+/**
+ * @fileoverview Event-driven reactions and retry policy service.
+ */
+
 export interface GateFailedReaction {
   enabled: boolean;
   max_retries: number;
@@ -58,6 +62,47 @@ const DEFAULT_GATE_FAILED_REACTION: GateFailedReaction = {
   retry_delay_ms: 30000,
 };
 
+/**
+ * Manages event-driven reactions and retry policies.
+ *
+ * ## Responsibilities
+ * - Execute reactions for events (gate_failed, agent_stuck, collision_detected, etc.)
+ * - Enforce retry limits and backoff
+ * - Trigger escalation when limits exceeded
+ * - Record reaction outcomes
+ *
+ * ## Dependencies
+ * Depends on:
+ * - {@link SupervisorToolCaller} - for tool invocation
+ * - {@link NotifierService} - for escalation notifications
+ * - Policy reactions configuration
+ *
+ * ## Key Methods
+ * - `shouldRetry()` - determine if retry is allowed
+ * - `waitBeforeRetry()` - apply retry delay
+ * - `recordRetry()` - log retry attempt
+ * - `notifyEscalation()` - escalate to human
+ *
+ * ## Error Conditions
+ * - RETRY_LIMIT_EXCEEDED - max retries reached
+ * - REACTION_NOT_CONFIGURED - no reaction defined for event
+ *
+ * @example
+ * ```typescript
+ * const reactionsService = new ReactionsService({ toolCaller, notifier, policy });
+ * if (reactionsService.shouldRetry('my_feature', 1)) {
+ *   await reactionsService.waitBeforeRetry();
+ *   await reactionsService.recordRetry('my_feature', 2);
+ * }
+ * ```
+ *
+ * ## Supported Events
+ * - gate_failed: retry with feedback
+ * - agent_stuck: restart or escalate
+ * - collision_detected: re-drive queue
+ * - ready_to_merge: notify reviewers
+ * - changes_requested: restart QA phase
+ */
 export class ReactionsService {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly notifier: NotifierService | undefined;
@@ -104,6 +149,16 @@ export class ReactionsService {
     return DEFAULT_GATE_FAILED_REACTION.max_retries;
   }
 
+  /**
+   * Waits for retry delay before next attempt.
+   *
+   * @returns Promise that resolves after delay
+   *
+   * @example
+   * ```typescript
+   * await reactionsService.waitBeforeRetry();
+   * ```
+   */
   async waitBeforeRetry(): Promise<void> {
     const delayMs = this.retryDelayMs();
     if (delayMs <= 0) {
@@ -145,6 +200,17 @@ export class ReactionsService {
     ].join('\n');
   }
 
+  /**
+   * Records retry attempt in feature state.
+   *
+   * @param featureId - feature identifier
+   * @param retryCount - current retry count
+   *
+   * @example
+   * ```typescript
+   * await reactionsService.recordRetry('my_feature', 2);
+   * ```
+   */
   async recordRetry(featureId: string, retryCount: number): Promise<void> {
     const current = await this.toolCaller.callTool<FeatureStatePayload>(
       'orchestrator',
@@ -168,6 +234,17 @@ export class ReactionsService {
     return retryCount >= reaction.escalate_after;
   }
 
+  /**
+   * Notifies escalation when retry limit exceeded.
+   *
+   * @param featureId - feature identifier
+   * @param ctx - gate repair context with failure details
+   *
+   * @example
+   * ```typescript
+   * await reactionsService.notifyEscalation('my_feature', context);
+   * ```
+   */
   async notifyEscalation(featureId: string, ctx: GateRepairContext): Promise<void> {
     if (!this.notifier) {
       return;