agentic-orchestrator 0.1.25 → 0.1.26

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

@@ -54,21 +54,98 @@ function deriveStatusFromGateResult(
   return currentStatus;
 }
 
+/**
+ * Port interface for gate operations.
+ *
+ * ## Contract
+ * Implementations must ensure:
+ * - Access to gates configuration and policy
+ * - State read/update with version guards
+ * - Path resolution for worktrees, logs, and evidence
+ *
+ * ## Error Handling
+ * All methods throw normalized errors with stable error codes.
+ */
 export interface GateServicePort {
+  /** Returns repository root path. */
   getRepoRoot(): string;
+  /** Returns gates configuration. */
   getGatesConfig(): AnyRecord;
+  /** Returns policy snapshot. */
   getPolicySnapshot(): AnyRecord;
+  /**
+   * Reads feature state.
+   * @throws FEATURE_NOT_FOUND - if state doesn't exist
+   */
   readState(featureId: string): Promise<{ frontMatter: AnyRecord }>;
+  /**
+   * Updates feature state with version guard.
+   * @param featureId - feature identifier
+   * @param expectedVersion - expected version (null = no check)
+   * @param updater - function returning updated state
+   */
   updateState(
     featureId: string,
     expectedVersion: number | null,
     updater: StateUpdater,
   ): Promise<AnyRecord>;
+  /** Returns absolute path to feature worktree. */
   worktreePath(featureId: string): string;
+  /** Returns absolute path to feature logs directory. */
   logsPath(featureId: string): string;
+  /** Returns absolute path to feature evidence directory. */
   evidencePath(featureId: string): string;
 }
 
+/**
+ * Manages gate execution, evidence collection, and threshold enforcement.
+ *
+ * ## Responsibilities
+ * - Execute gate profiles (fast/full/merge) with command interpolation
+ * - Collect logs and evidence artifacts
+ * - Parse coverage reports and enforce thresholds
+ * - Update feature state with gate results
+ * - Transition status based on gate outcomes
+ *
+ * ## Dependencies
+ * Depends on {@link GateServicePort} for:
+ * - Gates configuration and policy access
+ * - State updates and file operations
+ * - Worktree and evidence path resolution
+ *
+ * ## Key Methods
+ * - `gatesRun()` - execute gate profile with evidence collection
+ * - `gatesList()` - list available gate profiles
+ * - `evidenceLatest()` - retrieve latest evidence summary
+ * - `gateProfileAndMode()` - resolve profile/mode configuration
+ *
+ * ## Error Conditions
+ * - GATE_FAILED - gate execution failed or thresholds not met
+ * - INVALID_ARGUMENT - unknown profile or mode
+ * - FILE_NOT_FOUND - missing evidence or coverage files
+ *
+ * ## Gate Lifecycle
+ * 1. Select profile and mode based on feature state
+ * 2. Interpolate commands with feature context
+ * 3. Execute steps (sequential or parallel)
+ * 4. Collect evidence and parse coverage
+ * 5. Enforce thresholds (minimums and targets)
+ * 6. Update state and transition status
+ *
+ * @example
+ * ```typescript
+ * const gateService = new GateService(port);
+ *
+ * // Execute fast gate profile
+ * await gateService.gatesRun('my_feature', 'fast', 'fast', null);
+ *
+ * // Get latest evidence
+ * const evidence = await gateService.evidenceLatest('my_feature');
+ * ```
+ *
+ * ## Thread Safety
+ * State updates are atomic via version guards.
+ */
 export class GateService {
   private readonly port: GateServicePort;
   private readonly gateSelectionService: GateSelectionService;
@@ -78,6 +155,21 @@ export class GateService {
     this.gateSelectionService = new GateSelectionService(port);
   }
 
+  /**
+   * Lists available gate profiles or returns specific profile configuration.
+   *
+   * @param profileName - optional profile name to retrieve
+   * @returns Profile configuration or all profiles
+   *
+   * @example
+   * ```typescript
+   * // List all profiles
+   * const all = gateService.gatesList();
+   *
+   * // Get specific profile
+   * const fast = gateService.gatesList('fast');
+   * ```
+   */
   gatesList(profileName: string | null = null): { data: AnyRecord } {
     const gatesConfig = this.port.getGatesConfig();
     if (profileName) {
@@ -96,10 +188,50 @@ export class GateService {
     };
   }
 
+  /**
+   * Resolves gate profile and mode configuration.
+   *
+   * @param profileName - profile identifier
+   * @param mode - mode identifier
+   * @returns Resolved profile/mode configuration
+   * @throws INVALID_ARGUMENT - unknown profile or mode
+   *
+   * @example
+   * ```typescript
+   * const config = gateService.gateProfileAndMode('fast', 'fast');
+   * ```
+   */
   gateProfileAndMode(profileName: string, mode: string): AnyRecord {
     return this.gateSelectionService.resolveProfileAndMode(profileName, mode);
   }
 
+  /**
+   * Executes gate profile with evidence collection and threshold enforcement.
+   *
+   * Workflow:
+   * 1. Resolve profile/mode from state or explicit parameters
+   * 2. Interpolate commands with feature context
+   * 3. Execute steps (parallel groups or sequential)
+   * 4. Collect logs and evidence artifacts
+   * 5. Parse coverage and enforce thresholds
+   * 6. Update state with results and transition status
+   *
+   * @param featureId - feature identifier
+   * @param profileName - gate profile (null = auto-select from state)
+   * @param mode - gate mode (fast/full/merge)
+   * @returns Gate execution results with coverage and evidence
+   * @throws GATE_FAILED - execution failed or thresholds not met
+   * @throws INVALID_ARGUMENT - unknown profile or mode
+   *
+   * @example
+   * ```typescript
+   * // Auto-select profile from state
+   * await gateService.gatesRun('my_feature', null, 'fast');
+   *
+   * // Explicit profile
+   * await gateService.gatesRun('my_feature', 'fast', 'fast');
+   * ```
+   */
   async gatesRun(
     featureId: string,
     profileName: string | null,
@@ -236,6 +368,22 @@ export class GateService {
     };
   }
 
+  /**
+   * Retrieves latest evidence summary for a feature.
+   *
+   * Returns most recent gate execution evidence including logs,
+   * coverage reports, and artifact paths.
+   *
+   * @param featureId - feature identifier
+   * @returns Evidence summary with paths and metadata
+   * @throws FILE_NOT_FOUND - no evidence exists
+   *
+   * @example
+   * ```typescript
+   * const evidence = await gateService.evidenceLatest('my_feature');
+   * console.log(evidence.data.coverage);
+   * ```
+   */
   async evidenceLatest(
     featureId: string,
   ): Promise<{ data: { feature_id: string; latest: AnyRecord | null; path?: string } }> {

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

@@ -83,6 +83,16 @@ function tryParseJson(value: string): Record<string, unknown> | null {
   }
 }
 
+/**
+ * GitHub issue tracker implementation.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new GitHubIssueTracker({ repo: 'owner/repo' });
+ * const issue = await tracker.getIssue('123');
+ * await tracker.updateIssueStatus('123', 'closed');
+ * ```
+ */
 export class GitHubIssueTracker implements IssueTracker {
   private readonly repo: string | undefined;
   private readonly ghRunner: GhRunner;
@@ -194,6 +204,15 @@ function mapDefaultJiraTransition(status: string): string {
 }
 
 // --- Linear adapter (GraphQL HTTP) ---
+/**
+ * Linear issue tracker implementation.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new LinearIssueTracker({ api_key: 'lin_...' });
+ * const issue = await tracker.getIssue('PROJ-123');
+ * ```
+ */
 export class LinearIssueTracker implements IssueTracker {
   private readonly token: string;
   private readonly baseUrl: string;
@@ -343,6 +362,15 @@ function toJiraDescription(value: unknown): string {
 }
 
 // --- Jira adapter (REST HTTP) ---
+/**
+ * Jira issue tracker implementation.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new JiraIssueTracker({ base_url: 'https://company.atlassian.net', api_token: '...' });
+ * const issue = await tracker.getIssue('PROJ-123');
+ * ```
+ */
 export class JiraIssueTracker implements IssueTracker {
   private readonly baseUrl: string;
   private readonly token: string;

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

@@ -18,17 +18,41 @@ interface CollisionQueueDrivePort {
   }>;
 }
 
+/**
+ * Port interface for lock operations.
+ *
+ * ## Contract
+ * Implementations must ensure:
+ * - Atomic lock acquisition and release via index lock
+ * - Lease TTL enforcement with stale lock reclamation
+ * - State updates reflect lock ownership changes
+ *
+ * ## Error Handling
+ * All methods throw normalized errors with stable error codes.
+ */
 export interface LockServicePort {
+  /** Executes an operation with index-level lock held. */
   withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  /** Reads the global feature index. */
   readIndex(): Promise<AnyRecord>;
+  /** Writes the global feature index atomically. */
   writeIndex(index: AnyRecord): Promise<void>;
+  /**
+   * Updates feature state with version guard.
+   * @param featureId - feature identifier
+   * @param expectedVersion - expected version (null = no check)
+   * @param updater - function returning updated state
+   */
   updateState(
     featureId: string,
     expectedVersion: number | null,
     updater: StateUpdater,
   ): Promise<AnyRecord>;
+  /** Returns absolute path to feature state file. */
   statePath(featureId: string): string;
+  /** Returns current policy snapshot. */
   getPolicySnapshot(): AnyRecord;
+  /** Optional collision queue service for re-drive after lock release. */
   collisionQueueService?: CollisionQueueDrivePort;
 }
 
@@ -40,6 +64,42 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Manages resource lock acquisition, renewal, and release.
+ *
+ * ## Responsibilities
+ * - Acquire resource locks with wait/backoff behavior
+ * - Enforce lease TTL and reclaim stale locks
+ * - Update feature state to reflect lock ownership
+ * - Trigger collision queue re-drive on lock release
+ *
+ * ## Dependencies
+ * - {@link LockServicePort} - for index/state operations and policy access
+ *
+ * ## Key Methods
+ * - `locksAcquire()` - acquire resource lock with wait/backoff
+ * - `locksRelease()` - release resource lock and trigger re-drive
+ *
+ * ## Error Conditions
+ * - INVALID_ARGUMENT - unknown resource or missing featureId
+ * - LOCK_CONFLICT - lock held by another feature (fail mode)
+ * - LOCK_TIMEOUT - wait timeout exceeded
+ *
+ * ## Thread Safety
+ * All lock operations are atomic via index-level lock.
+ *
+ * @example
+ * ```typescript
+ * // Acquire lock with default wait behavior
+ * await lockService.locksAcquire('openapi', 'my_feature', null);
+ *
+ * // Acquire with custom timeout
+ * await lockService.locksAcquire('db_migrations', 'my_feature', 60);
+ *
+ * // Release lock
+ * await lockService.locksRelease('openapi', 'my_feature');
+ * ```
+ */
 export class LockService {
   private readonly port: LockServicePort;
 
@@ -47,6 +107,17 @@ export class LockService {
     this.port = port;
   }
 
+  /**
+   * Acquires a resource lock for a feature with optional wait behavior.
+   *
+   * @param resource - resource identifier (must be in policy.locks.resources)
+   * @param featureId - feature requesting the lock
+   * @param waitTimeoutSeconds - max wait time (null = use policy default)
+   * @returns Success response with lease metadata
+   * @throws INVALID_ARGUMENT - unknown resource or missing featureId
+   * @throws LOCK_TIMEOUT - wait timeout exceeded
+   * @throws LOCK_HELD - lock held by another feature (fail behavior only)
+   */
   async locksAcquire(
     resource: string | null,
     featureId: string | null,
@@ -176,6 +247,23 @@ export class LockService {
     }
   }
 
+  /**
+   * Releases a resource lock held by a feature.
+   *
+   * Removes lock from index, updates feature state, and triggers
+   * collision queue re-drive to unblock waiting features.
+   *
+   * @param resource - resource identifier
+   * @param featureId - feature releasing the lock
+   * @returns Success response
+   * @throws INVALID_ARGUMENT - missing resource or featureId
+   * @throws LOCK_CONFLICT - lock held by another feature
+   *
+   * @example
+   * ```typescript
+   * await lockService.locksRelease('openapi', 'my_feature');
+   * ```
+   */
   async locksRelease(resource: string | null, featureId: string | null) {
     if (!resource || !featureId) {
       throw {

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

@@ -33,6 +33,10 @@ function asArray<T = unknown>(value: unknown): T[] {
   return Array.isArray(value) ? (value as T[]) : [];
 }
 
+/**
+ * @fileoverview Merge promotion and branch management service.
+ */
+
 export interface MergeServicePort {
   getRepoRoot(): string;
   getPolicySnapshot(): AnyRecord;
@@ -50,6 +54,41 @@ export interface MergeServicePort {
   writeIndex(index: AnyRecord): Promise<void>;
 }
 
+/**
+ * Manages merge promotion and branch lifecycle.
+ *
+ * ## Responsibilities
+ * - Validate merge readiness (gates passed, approval obtained)
+ * - Commit worktree changes
+ * - Merge feature branch to base
+ * - Clean up worktree and branch
+ * - Update index to reflect merge
+ *
+ * ## Dependencies
+ * Depends on {@link MergeServicePort} for:
+ * - State and index operations
+ * - Policy and worktree access
+ * - Lock release coordination
+ *
+ * ## Key Methods
+ * - `featureReadyToMerge()` - validate, commit, merge, and cleanup
+ *
+ * ## Error Conditions
+ * - MERGE_REQUIREMENTS_NOT_MET - gates not passed or approval missing
+ * - MERGE_CONFLICT - git merge failed
+ * - UNCOMMITTED_CHANGES - worktree has uncommitted changes
+ *
+ * ## Merge Requirements
+ * - All required gates must pass
+ * - Approval token must be valid (if required by policy)
+ * - No uncommitted changes in worktree
+ *
+ * @example
+ * ```typescript
+ * const mergeService = new MergeService(port);
+ * await mergeService.featureReadyToMerge('my_feature', 'approve_abc123');
+ * ```
+ */
 export class MergeService {
   private readonly port: MergeServicePort;
 
@@ -99,6 +138,30 @@ export class MergeService {
     }
   }
 
+  /**
+   * Validates merge readiness, commits changes, merges to base, and cleans up.
+   *
+   * Full workflow:
+   * 1. Validate required gates passed
+   * 2. Verify approval token (if policy requires)
+   * 3. Commit worktree changes
+   * 4. Merge feature branch to base branch
+   * 5. Release held locks
+   * 6. Update index (move to merged, remove from active)
+   * 7. Schedule cleanup (worktree/branch removal per policy)
+   *
+   * @param featureId - feature identifier
+   * @param approvalToken - approval token (required if policy enforces)
+   * @returns Merge result with commit SHA and cleanup status
+   * @throws MERGE_REQUIREMENTS_NOT_MET - gates not passed or approval invalid
+   * @throws MERGE_CONFLICT - git merge failed
+   * @throws UNCOMMITTED_CHANGES - worktree has uncommitted changes
+   *
+   * @example
+   * ```typescript
+   * await mergeService.featureReadyToMerge('my_feature', 'approve_abc123');
+   * ```
+   */
   async featureReadyToMerge(
     featureId: string,
     commitMessage: string,

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

@@ -72,6 +72,15 @@ const EVENT_PRIORITY: Record<NotificationEvent, CanonicalPriority> = {
 
 const THROTTLE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
 
+/**
+ * Desktop notification channel using notify-send.
+ *
+ * @example
+ * ```typescript
+ * const channel = new DesktopNotifierChannel();
+ * await channel.send(payload);
+ * ```
+ */
 export class DesktopNotifierChannel implements NotifierChannel {
   readonly name = 'desktop';
 
@@ -96,6 +105,15 @@ export class DesktopNotifierChannel implements NotifierChannel {
   }
 }
 
+/**
+ * Slack notification channel using webhook.
+ *
+ * @example
+ * ```typescript
+ * const channel = new SlackNotifierChannel(webhookUrl, '#alerts');
+ * await channel.send(payload);
+ * ```
+ */
 export class SlackNotifierChannel implements NotifierChannel {
   readonly name = 'slack';
   private readonly webhookUrl: string;
@@ -139,6 +157,15 @@ export class SlackNotifierChannel implements NotifierChannel {
   }
 }
 
+/**
+ * Generic webhook notification channel.
+ *
+ * @example
+ * ```typescript
+ * const channel = new WebhookNotifierChannel('https://example.com/webhook');
+ * await channel.send(payload);
+ * ```
+ */
 export class WebhookNotifierChannel implements NotifierChannel {
   readonly name = 'webhook';
   private readonly url: string;
@@ -159,6 +186,36 @@ export class WebhookNotifierChannel implements NotifierChannel {
   }
 }
 
+/**
+ * Manages multi-channel notifications with priority routing.
+ *
+ * ## Responsibilities
+ * - Route notifications by priority (critical/warning/info)
+ * - Send to multiple channels (desktop/Slack/webhook)
+ * - Throttle duplicate notifications
+ * - Map events to priorities
+ *
+ * ## Dependencies
+ * - Notification channel implementations
+ * - Policy notification configuration
+ *
+ * ## Key Methods
+ * - `notify()` - send notification with priority routing
+ *
+ * ## Error Conditions
+ * - Channel send failures are logged but don't block
+ *
+ * @example
+ * ```typescript
+ * const notifier = new NotifierService(config, dashboardUrl);
+ * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+ * ```
+ *
+ * ## Supported Channels
+ * - desktop: notify-send
+ * - slack: webhook
+ * - webhook: generic HTTP POST
+ */
 export class NotifierService {
   private readonly config: NotificationConfig;
   private readonly channels: Map<string, NotifierChannel>;
@@ -222,6 +279,19 @@ export class NotifierService {
     return false;
   }
 
+  /**
+   * Sends notification with priority-based routing.
+   *
+   * @param event - notification event type
+   * @param featureId - optional feature identifier
+   * @param message - notification message
+   * @param details - optional additional details
+   *
+   * @example
+   * ```typescript
+   * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+   * ```
+   */
   async notify(
     event: NotificationEvent,
     context: { feature_id?: string; message: string; details?: Record<string, unknown> },

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

@@ -47,6 +47,10 @@ function normalizeFromWorktree(
   return path.relative(repoRoot, absolute).replaceAll('\\\\', '/');
 }
 
+/**
+ * @fileoverview Patch validation and application service.
+ */
+
 export interface PatchServicePort {
   getRepoRoot(): string;
   getPolicySnapshot(): AnyRecord;
@@ -63,6 +67,41 @@ export interface PatchServicePort {
   ): Promise<AnyRecord>;
 }
 
+/**
+ * Manages patch validation and atomic application.
+ *
+ * ## Responsibilities
+ * - Validate unified diff format
+ * - Enforce plan area restrictions
+ * - Apply policy path rules
+ * - Verify lock requirements
+ * - Apply patches atomically to worktree
+ *
+ * ## Dependencies
+ * Depends on {@link PatchServicePort} for:
+ * - Plan and policy access
+ * - State operations
+ * - Worktree path resolution
+ *
+ * ## Key Methods
+ * - `repoApplyPatch()` - validate and apply unified diff
+ * - `validatePatchPaths()` - enforce plan/policy path rules
+ * - `assertPlanLocksHeld()` - verify required locks
+ *
+ * ## Error Conditions
+ * - PATCH_VALIDATION_FAILED - invalid diff format or path violations
+ * - LOCK_NOT_HELD - required locks not acquired
+ * - PLAN_NOT_FOUND - no accepted plan exists
+ *
+ * @example
+ * ```typescript
+ * const patchService = new PatchService(port);
+ * await patchService.repoApplyPatch('my_feature', unifiedDiff);
+ * ```
+ *
+ * ## Thread Safety
+ * Patch application is atomic within feature worktree.
+ */
 export class PatchService {
   private readonly port: PatchServicePort;
   private readonly gateSelectionService: GateSelectionService;
@@ -72,6 +111,12 @@ export class PatchService {
     this.gateSelectionService = new GateSelectionService(port);
   }
 
+  /**
+   * Loads accepted plan for a feature.
+   *
+   * @param featureId - feature identifier
+   * @returns Plan object or null if not found
+   */
   async loadAcceptedPlan(featureId: string): Promise<AnyRecord | null> {
     const plan = await readJson(this.port.planPath(featureId), null);
     if (!plan && this.port.getPolicySnapshot().patch_policy.enforce_plan) {
@@ -102,6 +147,13 @@ export class PatchService {
     return sortResourcesDeterministically(resources);
   }
 
+  /**
+   * Verifies required resource locks are held for plan.
+   *
+   * @param featureId - feature identifier
+   * @param plan - plan requiring locks
+   * @throws LOCK_NOT_HELD - required locks not held
+   */
   async assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<void> {
     const state = await this.port.readState(featureId);
     const held = new Set(readHeldLocks(state.frontMatter));
@@ -124,6 +176,24 @@ export class PatchService {
     }
   }
 
+  /**
+   * Validates patch paths against plan areas and policy rules.
+   *
+   * Enforces:
+   * - Paths must be in plan allowed_areas
+   * - Paths must not be in plan forbidden_areas
+   * - Paths must not violate policy path rules
+   *
+   * @param featureId - feature identifier
+   * @param patch - unified diff content
+   * @param plan - accepted plan with area restrictions
+   * @throws PATCH_VALIDATION_FAILED - path violations detected
+   *
+   * @example
+   * ```typescript
+   * await patchService.validatePatchPaths('my_feature', diff, plan);
+   * ```
+   */
   async validatePatchPaths(
     featureId: string,
     parsedDiff: ReturnType<typeof parseUnifiedDiff>,
@@ -199,6 +269,31 @@ export class PatchService {
     return normalizedTouched;
   }
 
+  /**
+   * Validates and applies unified diff to feature worktree.
+   *
+   * Full validation pipeline:
+   * 1. Load accepted plan
+   * 2. Verify required locks held
+   * 3. Validate patch format
+   * 4. Enforce path restrictions
+   * 5. Apply patch atomically
+   * 6. Update state with patch metadata
+   *
+   * @param featureId - feature identifier
+   * @param patch - unified diff content
+   * @returns Success response with applied patch metadata
+   * @throws PLAN_NOT_FOUND - no accepted plan
+   * @throws LOCK_NOT_HELD - required locks not held
+   * @throws PATCH_VALIDATION_FAILED - invalid format or path violations
+   * @throws PATCH_APPLICATION_FAILED - git apply failed
+   *
+   * @example
+   * ```typescript
+   * const diff = `--- a/file.ts\n+++ b/file.ts\n...`;
+   * await patchService.repoApplyPatch('my_feature', diff);
+   * ```
+   */
   async repoApplyPatch(
     featureId: string,
     unifiedDiff: string,