agentic-orchestrator 0.1.28 → 0.2.0

package/specs/001-runtime-inspection/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Runtime File Inspection (AOP Dashboard)
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-05
+**Feature**: [Link to spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- **Implementation Details Migrated**: The original specification contained detailed implementation information (API routes, file paths, JSON schemas). These have been migrated to `specs/001-runtime-inspection/design.md` to adhere to the spec standard while preserving the technical design.
+- **Spec Structure Updated**: The spec was rewritten to follow the `spec-template.md` structure (User Stories, Functional Requirements, Success Criteria).

package/specs/001-runtime-inspection/design.md

@@ -0,0 +1,338 @@
+# Design Document: Runtime File Inspection (AOP Dashboard)
+
+> **Note**: This document contains detailed implementation specifications migrated from the original feature spec.
+
+## 0. Scope and Standards
+
+### 0.1 Primary User Job
+
+**Operator/Debugger Job:** Understand what happened during a feature run by inspecting:
+
+- Operation Ledger: idempotent tool invocations with request/response payloads
+- Worker Events: agent lifecycle events (started, completed, failed, timeout)
+
+**Key Questions This Feature Answers:**
+
+1. What tools were called for this feature and what were the results?
+2. When did the agent start/stop/fail/timeout?
+3. What was the sequence of events leading to a failure?
+4. Were there any retries or duplicate operations?
+
+### 0.2 UX Principles
+
+1. **Time-first ordering:** All events sorted by timestamp (newest first by default)
+2. **Progressive disclosure:** Raw JSON collapsed by default, formatted summary visible
+3. **Feature-scoped:** Filter to single feature ID, not global view
+4. **Read-only:** No mutation of runtime files through UI
+5. **Performance-bounded:** Limit display to last N events, paginate if needed
+
+### 0.3 Quality Standards
+
+- TypeScript strict mode passes
+- ESLint zero warnings
+- Coverage >= 90% for new code
+- API response time < 200ms for typical feature (< 100 events)
+- Graceful degradation when files are large (> 1000 events)
+- Must pass `npm run verify` checks
+
+---
+
+## 1. Runtime File Structure
+
+### 1.1 Run ID Tracking in Feature State
+
+**File:** `.aop/features/<feature_id>/state.md`
+
+**YAML Frontmatter:**
+
+```yaml
+run_history:
+  - run_id: 'run:69c36d92-3255-435a-806a-6425461e5aa8'
+    started_at: '2026-03-05T06:07:17.975Z'
+    ended_at: '2026-03-05T06:08:22.123Z'
+    status: 'completed'
+  - run_id: 'run:8efe99b2-1b1a-4c9f-9d3e-2a7b8c1d4e5f'
+    started_at: '2026-03-04T22:24:39.635Z'
+    ended_at: null
+    status: 'active'
+```
+
+**Update Behavior:**
+
+- **On feature.init:** Create `run_history` with current run_id, status `active`
+- **On supervisor start:** Append current run_id to `run_history` if not already present
+- **On supervisor stop/complete:** Update latest run_history entry with `ended_at` and final `status`
+- **On feature.delete:** Archive run_history before deletion (optional)
+
+### 1.2 Operation Ledger Files
+
+**Location:** `.aop/runtime/operation-ledger/run:<run_id>.json`
+
+**Structure:**
+
+```json
+{
+  "run_id": "run:69c36d92-3255-435a-806a-6425461e5aa8",
+  "updated_at": "2026-03-05T06:07:17.975Z",
+  "operations": {
+    "<operation_id>": {
+      "operation_id": "feature_delete__my_feature__uuid",
+      "tool_name": "feature.delete",
+      "request_hash": "sha256...",
+      "response": {
+        "ok": true,
+        "data": { ... }
+      }
+    }
+  }
+}
+```
+
+### 1.3 Worker Events Files
+
+**Location:** `.aop/runtime/worker-events/run:<run_id>.jsonl`
+
+**Structure:** JSONL (one JSON object per line)
+
+```json
+{"ts":"2026-03-05T22:24:39.635Z","run_id":"run:8efe99b2...","feature_id":"my_feature","role":"planner","phase":"execution","event_type":"worker_started","output_types":[],"patch_count":0,"plan_submission_count":0,"request_count":0,"note_count":0,"valid":true,"error_code":null,"provider":"claude","model":"local-default","watchdog_reason":null,"signal":null}
+{"ts":"2026-03-05T22:25:17.441Z","run_id":"run:8efe99b2...","feature_id":"my_feature","role":"planner","phase":"execution","event_type":"worker_completed","output_types":["PLAN_SUBMISSION"],"patch_count":0,"plan_submission_count":1,"request_count":0,"note_count":0,"valid":true,"error_code":null,"provider":"claude","model":"local-default","watchdog_reason":null,"signal":null}
+```
+
+---
+
+## 2. API Contract
+
+### 2.1 Operation Ledger Endpoint
+
+**Route:** `GET /api/runtime/operations`
+
+**Query Parameters:**
+
+- `feature_id` (required): Feature ID to filter operations
+- `run_id` (optional): Specific run ID (defaults to latest from `run_history`)
+- `project` (optional): Project name for multi-project setups
+- `limit` (optional, default 100): Max operations to return
+- `offset` (optional, default 0): Pagination offset
+
+**Response Envelope:**
+
+```typescript
+{
+  ok: true,
+  data: {
+    run_id: string;
+    feature_id: string;
+    updated_at: string;
+    run_info: {
+      started_at: string;
+      ended_at: string | null;
+      status: 'active' | 'completed' | 'failed' | 'timeout';
+    };
+    operations: Array<{
+      operation_id: string;
+      tool_name: string;
+      request_hash: string;
+      timestamp: string;
+      response: {
+        ok: boolean;
+        data?: unknown;
+        error?: {
+          code: string;
+          message: string;
+          details?: unknown;
+        };
+      };
+    }>;
+    total_count: number;
+    has_more: boolean;
+  },
+  metadata: {
+    source: 'runtime_ledger';
+  }
+}
+```
+
+### 2.2 Worker Events Endpoint
+
+**Route:** `GET /api/runtime/events`
+
+**Query Parameters:**
+
+- `feature_id` (required): Feature ID to filter events
+- `run_id` (optional): Specific run ID (defaults to latest from `run_history`)
+- `project` (optional): Project name for multi-project setups
+- `limit` (optional, default 100): Max events to return
+- `offset` (optional, default 0): Pagination offset
+- `event_type` (optional): Filter by event type (comma-separated)
+- `role` (optional): Filter by role (comma-separated)
+
+**Response Envelope:**
+
+```typescript
+{
+  ok: true,
+  data: {
+    run_id: string;
+    feature_id: string;
+    run_info: {
+      started_at: string;
+      ended_at: string | null;
+      status: 'active' | 'completed' | 'failed' | 'timeout';
+    };
+    events: Array<{
+      ts: string;
+      run_id: string;
+      feature_id: string;
+      role: string;
+      phase: string;
+      event_type: string;
+      output_types: string[];
+      valid: boolean;
+      error_code: string | null;
+      // ... other fields
+    }>;
+    total_count: number;
+    has_more: boolean;
+  },
+  metadata: {
+    source: 'runtime_events';
+  }
+}
+```
+
+### 2.3 Run History Endpoint (New)
+
+**Route:** `GET /api/runtime/runs`
+
+**Query Parameters:**
+
+- `feature_id` (required): Feature ID to get run history
+- `project` (optional): Project name for multi-project setups
+
+**Response Envelope:**
+
+```typescript
+{
+  ok: true,
+  data: {
+    feature_id: string;
+    runs: Array<{
+      run_id: string;
+      started_at: string;
+      ended_at: string | null;
+      status: 'active' | 'completed' | 'failed' | 'timeout';
+      has_operations: boolean;
+      has_events: boolean;
+    }>;
+  },
+  metadata: {
+    source: 'feature_state';
+  }
+}
+```
+
+---
+
+## 3. UI Components
+
+### 3.1 Runtime Inspector Panel (New Component)
+
+**File:** `packages/web-dashboard/src/components/runtime-inspector.tsx`
+
+**Location:** Appears in Feature Detail Panel (right side) as a new tab
+
+**Tabs:**
+
+1. **Operations** - Operation Ledger view
+2. **Events** - Worker Events view
+
+**Run Selector:**
+
+- Dropdown at top of panel showing all runs from `run_history`
+- Format: `Run <short_id> - <started_at> - <status>`
+- Default: Latest run (index 0)
+
+### 3.2 Operations List View
+
+**Requirements:**
+
+**Summary Row:** `[Icon] tool_name | timestamp | status_badge | expand_icon`
+
+**Expanded View:**
+
+- Operation ID (Copyable)
+- Request Hash (Copyable)
+- Tool Name
+- Timestamp
+- Formatted JSON Response
+
+### 3.3 Events Timeline View
+
+**Timeline Row:** `[timestamp] [role_badge] [event_type_icon] event_type | duration | status`
+
+### 3.4 Filter Controls
+
+- **Operations Filters:** Tool Name, Status, Time Range
+- **Events Filters:** Role, Event Type, Valid Only, Time Range
+- **Persistence:** Store in URL query params
+
+---
+
+## 4. Implementation Details
+
+### 4.0 Schema and State Management Changes
+
+**File:** `agentic/orchestrator/schemas/state.schema.json`
+
+- Add `run_history` array to properties.
+
+**File:** `apps/control-plane/src/application/services/feature-state-service.ts`
+
+- Add methods to append/update run history.
+
+**File:** `apps/control-plane/src/supervisor/runtime.ts`
+
+- Call state service on start/stop/fail.
+
+### 4.1 Backend Implementation
+
+- **`api/runtime/runs/route.ts`**: Resolve feature_id, read state.md, return run_history.
+- **`api/runtime/operations/route.ts`**: Read operation ledger JSON, filter, sort, paginate.
+- **`api/runtime/events/route.ts`**: Read worker events JSONL, filter, sort, paginate.
+
+### 4.2 Frontend Implementation
+
+- **State:** Manage activeTab, selectedRunId, runs, operations, events, filters, pagination.
+- **Hooks:** Custom hooks for fetching data.
+- **Performance:** Virtualization for lists > 100 items.
+
+### 4.3 Integration with Detail Panel
+
+- Add "Runtime" tab to `packages/web-dashboard/src/components/detail-panel.tsx`.
+
+---
+
+## 5. Testing Strategy
+
+### 5.1 Unit Tests
+
+- Schema validation
+- API route logic (mocking file system)
+- Frontend component rendering and interaction
+
+### 5.2 Integration Tests
+
+- End-to-end flow: Create feature -> Run -> Open Dashboard -> Inspect Runtime
+
+### 5.3 Performance Tests
+
+- Load times < 200ms
+- Large file handling
+
+---
+
+## 6. Acceptance Criteria
+
+See `spec.md` for high-level acceptance criteria.
+This document serves as the detailed verification guide.

package/specs/001-runtime-inspection/spec.md

@@ -0,0 +1,95 @@
+# Feature Specification: Runtime File Inspection (AOP Dashboard)
+
+**Feature Branch**: `001-runtime-inspection`
+**Created**: 2026-03-05
+**Status**: Draft
+**Input**: User description: "Process the specification file at spec-files/outstanding/agentic_orchestrator_runtime_inspection_spec.md."
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Inspect Operation Ledger (Priority: P1)
+
+As an operator or debugger, I want to view the sequence of tool invocations (operations) for a specific feature run, so that I can verify inputs/outputs and debug logic errors.
+
+**Why this priority**: Essential for understanding "what the agent did" and verifying tool behavior.
+
+**Independent Test**: Can be tested by running a feature that calls tools, then opening the dashboard to verify the operations appear in the list with correct details.
+
+**Acceptance Scenarios**:
+
+1. **Given** a feature with completed tool calls, **When** I open the "Runtime" tab and select "Operations", **Then** I see a list of operations sorted by time (newest first).
+2. **Given** an operation in the list, **When** I click to expand it, **Then** I see the full request and response payloads formatted as JSON.
+3. **Given** a failed operation, **When** I view the list, **Then** it is visually distinguished (e.g., red badge) from successful ones.
+
+---
+
+### User Story 2 - Inspect Worker Events (Priority: P1)
+
+As an operator, I want to view the lifecycle events of the worker agents (planner/builder/qa), so that I can diagnose crashes, timeouts, or unexpected terminations.
+
+**Why this priority**: Critical for debugging system-level issues like agent crashes or loop behavior.
+
+**Independent Test**: Can be tested by running a feature that triggers agent transitions, then verifying the timeline in the dashboard.
+
+**Acceptance Scenarios**:
+
+1. **Given** a feature run, **When** I switch to the "Events" tab, **Then** I see a timeline of events (started, completed, failed) for all roles.
+2. **Given** a failed run, **When** I inspect the events, **Then** I can see the specific error code or termination reason.
+3. **Given** multiple agents running, **When** I filter by role (e.g., "Planner"), **Then** only events for that role are shown.
+
+---
+
+### User Story 3 - Historical Run Analysis (Priority: P2)
+
+As an operator, I want to access data from previous execution runs of a feature, so that I can investigate intermittent failures or compare current behavior with past runs.
+
+**Why this priority**: Allows debugging of issues that happened in the past, not just the active run.
+
+**Independent Test**: Can be tested by running a feature multiple times, then using the run selector to switch between the data sets.
+
+**Acceptance Scenarios**:
+
+1. **Given** a feature with multiple past runs, **When** I open the run selector dropdown, **Then** I see a list of all historical runs with their status and timestamps.
+2. **Given** I select a past run, **When** the page updates, **Then** the Operations and Events views show data specific to that selected run ID.
+
+---
+
+### Edge Cases
+
+- **Large Log Files**: What happens when an operation has a massive response payload? (UI should handle gracefully, e.g., truncate or virtualize).
+- **Missing Files**: What happens if the runtime files for a valid run ID are deleted? (UI should show a "Data not found" error).
+- **Concurrent Updates**: What happens if the feature is running while I'm inspecting it? (UI should allow refreshing or polling for new data).
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: System MUST track the history of execution runs (ID, start time, end time, status) for each feature.
+- **FR-002**: System MUST provide an interface to retrieve operation ledger data filtered by feature ID and run ID.
+- **FR-003**: System MUST provide an interface to retrieve worker event data filtered by feature ID and run ID.
+- **FR-004**: UI MUST display operations in a reverse-chronological list with expandable details.
+- **FR-005**: UI MUST display worker events in a reverse-chronological timeline.
+- **FR-006**: UI MUST allow filtering operations by tool name and status (success/failure).
+- **FR-007**: UI MUST allow filtering events by agent role and event type.
+- **FR-008**: UI MUST allow selecting a specific historical run to view its associated data.
+
+### Key Entities _(include if feature involves data)_
+
+- **Run**: A specific execution session of a feature, characterized by a Run ID, start/end times, and final status.
+- **Operation**: A single idempotent invocation of a tool by an agent, containing request hash, inputs, and outputs.
+- **Worker Event**: A lifecycle state change event for an agent (e.g., started, completed, failed).
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: Dashboard loads the initial view of operations/events for a typical run (<100 items) in under 200ms.
+- **SC-002**: Operators can identify the specific error message of a failed tool call within 3 clicks.
+- **SC-003**: System successfully handles and displays history for features with 50+ past runs.
+- **SC-004**: System handles large operation payloads (up to 1MB) without crashing the UI.
+
+## Assumptions
+
+- Runtime files (`.aop/runtime/...`) are generated by the orchestrator and are the source of truth.
+- The dashboard has read access to the file system or an API that serves these files.
+- Run IDs are unique across the system.

package/specs/002-scope-aware-lease/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Scope-Aware Run Lease
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-07-23
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
+- Assumptions section documents three deliberate scope decisions: path-prefix matching only (no symlinks), infrequent scope expansion, and opaque plan section identifiers.

package/specs/002-scope-aware-lease/contracts/lease-registry.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "LeaseRegistry",
+  "description": "Global lease registry storing all active run leases and their declared codebase scopes. Used for cross-instance scope conflict detection. Located at .aop/runtime/lease-registry.json.",
+  "type": "object",
+  "required": ["leases", "updated_at"],
+  "additionalProperties": false,
+  "properties": {
+    "leases": {
+      "type": "array",
+      "description": "All currently active (non-expired) run lease entries.",
+      "items": {
+        "$ref": "#/definitions/ActiveLeaseRecord"
+      }
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of the last registry write."
+    }
+  },
+  "definitions": {
+    "ActiveLeaseRecord": {
+      "type": "object",
+      "required": [
+        "run_id",
+        "owner_instance_id",
+        "instance_id",
+        "scope",
+        "lease_expires_at",
+        "acquired_at"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "run_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique run identifier. Matches RuntimeSessionsSnapshot.run_id."
+        },
+        "owner_instance_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Owning orchestrator instance identifier."
+        },
+        "instance_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Kernel instanceId (config-path-derived hash). Used for per-instance file correlation."
+        },
+        "scope": {
+          "description": "Declared codebase scope. null = unknown/undeclared (conflicts with all). Empty arrays = explicitly touches nothing.",
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "Unknown scope — conservative fallback that conflicts with all active leases."
+            },
+            {
+              "$ref": "#/definitions/LeaseScope"
+            }
+          ]
+        },
+        "lease_expires_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 TTL expiry. Entries with lease_expires_at < now are pruned on the next registry read."
+        },
+        "acquired_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp when this lease was first acquired."
+        }
+      }
+    },
+    "LeaseScope": {
+      "type": "object",
+      "required": ["paths", "plan_section_ids"],
+      "additionalProperties": false,
+      "description": "The declared codebase sections a run expects to touch.",
+      "properties": {
+        "paths": {
+          "type": "array",
+          "description": "File-system paths relative to repoRoot. Prefix-matched for overlap detection. Trailing slash is normalized at runtime.",
+          "items": {
+            "type": "string",
+            "minLength": 0
+          },
+          "uniqueItems": true
+        },
+        "plan_section_ids": {
+          "type": "array",
+          "description": "Plan section identifiers. Equality-matched (opaque strings, no hierarchy).",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}