agentic-orchestrator 0.1.25 → 0.1.26

package/dist/apps/control-plane/application/services/feature-state-service.d.ts

@@ -8,21 +8,107 @@ type StateUpdater = (frontMatter: AnyRecord, body: string) => Promise<{
     frontMatter?: AnyRecord;
     body?: string;
 }>;
+/**
+ * @fileoverview Feature state persistence and version management service.
+ */
 export interface FeatureStateServicePort {
     withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
     readState(featureId: string): Promise<StateReadResult>;
     writeState(featureId: string, frontMatter: AnyRecord, body?: string): Promise<void>;
 }
+/**
+ * Manages feature state persistence with version control.
+ *
+ * ## Responsibilities
+ * - Read/write state.md files (YAML front matter + markdown body)
+ * - Parse and validate front matter
+ * - Enforce optimistic concurrency via version guards
+ * - Atomic state updates with file locking
+ *
+ * ## Dependencies
+ * Depends on {@link FeatureStateServicePort} for:
+ * - File operations and state path resolution
+ * - Feature-level locking primitives
+ *
+ * ## Key Methods
+ * - `featureStateGet()` - read parsed state
+ * - `featureStatePatch()` - update state with version guard
+ * - `updateState()` - internal atomic update with custom updater
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - state file does not exist
+ * - VERSION_CONFLICT - concurrent state update detected
+ * - INVALID_STATE_TRANSITION - illegal status transition
+ *
+ * @example
+ * ```typescript
+ * const stateService = new FeatureStateService(port);
+ * const state = await stateService.featureStateGet('my_feature');
+ * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+ * ```
+ *
+ * ## State Format
+ * ```markdown
+ * ---
+ * feature_id: my_feature
+ * version: 5
+ * status: building
+ * ---
+ * # Feature State
+ * Body content...
+ * ```
+ */
 export declare class FeatureStateService {
     private readonly port;
     constructor(port: FeatureStateServicePort);
+    /**
+     * Updates feature state atomically with version guard.
+     *
+     * Internal method used by public state operations. Acquires feature lock,
+     * validates version, applies updater function, and writes merged state.
+     *
+     * @param featureId - feature identifier
+     * @param expectedVersion - expected current version (null = no check)
+     * @param updater - function returning state updates
+     * @returns Updated state frontmatter
+     * @throws VERSION_CONFLICT - version mismatch
+     * @throws INVALID_STATE_TRANSITION - illegal status transition
+     */
     updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+    /**
+     * Reads and parses feature state.
+     *
+     * @param featureId - feature identifier
+     * @returns Parsed state with frontmatter and body
+     * @throws FILE_NOT_FOUND - state file does not exist
+     *
+     * @example
+     * ```typescript
+     * const state = await stateService.featureStateGet('my_feature');
+     * console.log(state.data.frontMatter.status);
+     * ```
+     */
     featureStateGet(featureId: string): Promise<{
         data: {
             front_matter: AnyRecord;
             body: string;
         };
     }>;
+    /**
+     * Updates feature state with partial updates and version guard.
+     *
+     * @param featureId - feature identifier
+     * @param updates - partial state updates
+     * @param expectedVersion - expected current version
+     * @returns Updated state
+     * @throws VERSION_CONFLICT - version mismatch
+     * @throws INVALID_STATE_TRANSITION - illegal status transition
+     *
+     * @example
+     * ```typescript
+     * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+     * ```
+     */
     featureStatePatch(featureId: string, expectedVersion: number | null, patch: AnyRecord | null | undefined): Promise<{
         data: {
             feature_id: string;

package/dist/apps/control-plane/application/services/feature-state-service.js

@@ -22,11 +22,66 @@ function readVersion(frontMatter) {
     }
     return 0;
 }
+/**
+ * Manages feature state persistence with version control.
+ *
+ * ## Responsibilities
+ * - Read/write state.md files (YAML front matter + markdown body)
+ * - Parse and validate front matter
+ * - Enforce optimistic concurrency via version guards
+ * - Atomic state updates with file locking
+ *
+ * ## Dependencies
+ * Depends on {@link FeatureStateServicePort} for:
+ * - File operations and state path resolution
+ * - Feature-level locking primitives
+ *
+ * ## Key Methods
+ * - `featureStateGet()` - read parsed state
+ * - `featureStatePatch()` - update state with version guard
+ * - `updateState()` - internal atomic update with custom updater
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - state file does not exist
+ * - VERSION_CONFLICT - concurrent state update detected
+ * - INVALID_STATE_TRANSITION - illegal status transition
+ *
+ * @example
+ * ```typescript
+ * const stateService = new FeatureStateService(port);
+ * const state = await stateService.featureStateGet('my_feature');
+ * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+ * ```
+ *
+ * ## State Format
+ * ```markdown
+ * ---
+ * feature_id: my_feature
+ * version: 5
+ * status: building
+ * ---
+ * # Feature State
+ * Body content...
+ * ```
+ */
 export class FeatureStateService {
     port;
     constructor(port) {
         this.port = port;
     }
+    /**
+     * Updates feature state atomically with version guard.
+     *
+     * Internal method used by public state operations. Acquires feature lock,
+     * validates version, applies updater function, and writes merged state.
+     *
+     * @param featureId - feature identifier
+     * @param expectedVersion - expected current version (null = no check)
+     * @param updater - function returning state updates
+     * @returns Updated state frontmatter
+     * @throws VERSION_CONFLICT - version mismatch
+     * @throws INVALID_STATE_TRANSITION - illegal status transition
+     */
     async updateState(featureId, expectedVersion, updater) {
         return await this.port.withFeatureLock(featureId, async () => {
             const current = await this.port.readState(featureId);
@@ -61,6 +116,19 @@ export class FeatureStateService {
             return merged;
         });
     }
+    /**
+     * Reads and parses feature state.
+     *
+     * @param featureId - feature identifier
+     * @returns Parsed state with frontmatter and body
+     * @throws FILE_NOT_FOUND - state file does not exist
+     *
+     * @example
+     * ```typescript
+     * const state = await stateService.featureStateGet('my_feature');
+     * console.log(state.data.frontMatter.status);
+     * ```
+     */
     async featureStateGet(featureId) {
         const state = await this.port.readState(featureId);
         return {
@@ -70,6 +138,21 @@ export class FeatureStateService {
             },
         };
     }
+    /**
+     * Updates feature state with partial updates and version guard.
+     *
+     * @param featureId - feature identifier
+     * @param updates - partial state updates
+     * @param expectedVersion - expected current version
+     * @returns Updated state
+     * @throws VERSION_CONFLICT - version mismatch
+     * @throws INVALID_STATE_TRANSITION - illegal status transition
+     *
+     * @example
+     * ```typescript
+     * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+     * ```
+     */
     async featureStatePatch(featureId, expectedVersion, patch) {
         const updated = await this.updateState(featureId, expectedVersion, (frontMatter, body) => {
             const nextFront = { ...frontMatter, ...(patch?.front_matter ?? {}) };

package/dist/apps/control-plane/application/services/feature-state-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-state-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/feature-state-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"feature-state-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/feature-state-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAgBjD,MAAM,iBAAiB,GAAG;IACxB,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC;IACrE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC/D,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;IAC/D,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/E,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC;IAC/E,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;IAChC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;CACjD,CAAC;AAEF,SAAS,iBAAiB,CAAC,IAAY,EAAE,EAAU;IACjD,MAAM,OAAO,GAAI,iBAA8C,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5E,OAAO,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,WAAsB;IACzC,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,OAAO,mBAAmB;IACb,IAAI,CAA0B;IAE/C,YAAY,IAA6B;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,eAA8B,EAC9B,OAAqB;QAErB,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC3D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YACrD,IAAI,eAAe,IAAI,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;gBAC/E,MAAM;oBACJ,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,wBAAwB,EAAE;wBAC/E,gBAAgB,EAAE,eAAe;wBACjC,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO;wBAC3C,SAAS,EAAE,IAAI;wBACf,cAAc,EAAE,KAAK;qBACtB,CAAC;iBACH,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/E,MAAM,MAAM,GAAc;gBACxB,GAAG,OAAO,CAAC,WAAW;gBACtB,GAAG,IAAI,CAAC,WAAW;gBACnB,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC;gBAC7C,YAAY,EAAE,MAAM,EAAE;aACvB,CAAC;YAEF,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClE,MAAM;oBACJ,kBAAkB,EAAE,IAAI,CACtB,WAAW,CAAC,yBAAyB,EACrC,iCAAiC,EACjC;wBACE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,MAAM;wBAChC,EAAE,EAAE,MAAM,CAAC,MAAM;wBACjB,SAAS,EAAE,KAAK;wBAChB,cAAc,EAAE,IAAI;qBACrB,CACF;iBACF,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;YACzE,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,eAAe,CACnB,SAAiB;QAEjB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACnD,OAAO;YACL,IAAI,EAAE;gBACJ,YAAY,EAAE,KAAK,CAAC,WAAW;gBAC/B,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,iBAAiB,CACrB,SAAiB,EACjB,eAA8B,EAC9B,KAAmC;QAEnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,eAAe,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE;YACvF,MAAM,SAAS,GAAG,EAAE,GAAG,WAAW,EAAE,GAAG,CAAC,KAAK,EAAE,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;YACrE,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,IAAI;aAC1B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,IAAI,EAAE;gBACJ,UAAU,EAAE,SAAS;gBACrB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/apps/control-plane/application/services/gate-selection-service.d.ts

@@ -17,6 +17,34 @@ export interface CanonicalizedPlanInput {
     plan: AnyRecord;
     findings: GateSelectionFinding[];
 }
+/**
+ * Manages gate profile selection and resolution.
+ *
+ * ## Responsibilities
+ * - Select gate profile based on feature state
+ * - Resolve profile/mode configuration
+ * - Apply policy defaults and fallbacks
+ * - Auto-heal invalid state profiles
+ *
+ * ## Dependencies
+ * Depends on {@link GateSelectionServicePort} for:
+ * - Gates configuration
+ * - Policy snapshot
+ *
+ * ## Key Methods
+ * - `resolveProfileAndMode()` - resolve profile/mode configuration
+ * - `selectGateProfile()` - select profile from state or policy
+ * - `isAutoHealInvalidStateProfileEnabled()` - check auto-heal policy
+ *
+ * ## Error Conditions
+ * - INVALID_ARGUMENT - unknown profile or mode
+ *
+ * @example
+ * ```typescript
+ * const gateSelection = new GateSelectionService(port);
+ * const resolved = gateSelection.resolveProfileAndMode('fast', 'fast');
+ * ```
+ */
 export declare class GateSelectionService {
     private readonly port;
     constructor(port: GateSelectionServicePort);

package/dist/apps/control-plane/application/services/gate-selection-service.js

@@ -26,6 +26,34 @@ function asStringArray(value) {
     }
     return normalized;
 }
+/**
+ * Manages gate profile selection and resolution.
+ *
+ * ## Responsibilities
+ * - Select gate profile based on feature state
+ * - Resolve profile/mode configuration
+ * - Apply policy defaults and fallbacks
+ * - Auto-heal invalid state profiles
+ *
+ * ## Dependencies
+ * Depends on {@link GateSelectionServicePort} for:
+ * - Gates configuration
+ * - Policy snapshot
+ *
+ * ## Key Methods
+ * - `resolveProfileAndMode()` - resolve profile/mode configuration
+ * - `selectGateProfile()` - select profile from state or policy
+ * - `isAutoHealInvalidStateProfileEnabled()` - check auto-heal policy
+ *
+ * ## Error Conditions
+ * - INVALID_ARGUMENT - unknown profile or mode
+ *
+ * @example
+ * ```typescript
+ * const gateSelection = new GateSelectionService(port);
+ * const resolved = gateSelection.resolveProfileAndMode('fast', 'fast');
+ * ```
+ */
 export class GateSelectionService {
     port;
     constructor(port) {

package/dist/apps/control-plane/application/services/gate-selection-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate-selection-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/gate-selection-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate-selection-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/gate-selection-service.ts"],"names":[],"mappings":"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"}

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

@@ -3,26 +3,158 @@ type StateUpdater = (frontMatter: AnyRecord, body: string) => Promise<{
     frontMatter?: AnyRecord;
     body?: string;
 }>;
+/**
+ * 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 declare class GateService {
     private readonly port;
     private readonly gateSelectionService;
     constructor(port: GateServicePort);
+    /**
+     * 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): {
         data: AnyRecord;
     };
+    /**
+     * 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;
+    /**
+     * 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');
+     * ```
+     */
     gatesRun(featureId: string, profileName: string | null, mode: string): Promise<{
         data: {
             feature_id: string;
@@ -36,6 +168,22 @@ export declare class GateService {
             log_path: string;
         };
     }>;
+    /**
+     * 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);
+     * ```
+     */
     evidenceLatest(featureId: string): Promise<{
         data: {
             feature_id: string;

package/dist/apps/control-plane/application/services/gate-service.js

@@ -26,6 +26,55 @@ function deriveStatusFromGateResult(currentStatus, mode, overall) {
     }
     return currentStatus;
 }
+/**
+ * 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 {
     port;
     gateSelectionService;
@@ -33,6 +82,21 @@ export class GateService {
         this.port = port;
         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 = null) {
         const gatesConfig = this.port.getGatesConfig();
         if (profileName) {
@@ -49,9 +113,49 @@ 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, mode) {
         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, profileName, mode) {
         const state = await this.port.readState(featureId);
         const resolvedProfile = this.gateSelectionService.resolveProfileFromState(state.frontMatter.gate_profile);
@@ -144,6 +248,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) {
         const repoRoot = this.port.getRepoRoot();
         const evidenceDir = this.port.evidencePath(featureId);