agentic-orchestrator 0.1.27 → 0.2.0

package/spec-files/outstanding/agentic_orchestrator_dashboard_quick_launch_and_control_surface_spec.md

@@ -0,0 +1,331 @@
+# Feature Spec: Dashboard Quick Launch and Control Surface (AOP)
+
+> **Purpose of this document**: Define the dashboard-side authoring and operator controls for launching specs, re-enrolling stalled or blocked features, reducing triage-drawer interference, and adding persistent footer navigation.
+
+**Version:** 1.0
+**Date:** 2026-03-16
+**Status:** Draft
+**Roadmap Mapping:** M51
+**Depends On:**
+
+- `spec-files/completed/agentic_orchestrator_dashboard_advanced_ux_spec.md`
+- `spec-files/completed/agentic_orchestrator_add_feature_to_active_execution_spec.md`
+- `spec-files/completed/agentic_orchestrator_reactive_execution_enrollment_spec.md`
+- `spec-files/completed/agentic_orchestrator_dashboard_command_center_redesign_spec.md`
+
+---
+
+## 0. Scope
+
+This spec covers the following user requests:
+
+1. Move Quick Launch onto its own route with a visible dashboard entrypoint.
+2. Allow Quick Launch to accept either uploaded spec markdown files or pasted markdown text.
+3. Render imported markdown on the Quick Launch page before submission.
+4. Submit Quick Launch work through the same active-run enrollment path as `aop add`.
+5. Support adding multiple features in one dashboard submission.
+6. Allow direct dashboard resume/retry actions for features in client-visible `stalled` or `blocked` states.
+7. Refactor the root triage drawer so it remains helpful without obstructing root-route navigation.
+8. Add footer links to the GitHub repository and documentation.
+
+Out of scope:
+
+- background runtime boot and standby behavior
+- per-phase model/provider selection
+- token telemetry collection internals
+- organizer/spec-ordering behavior
+
+### 0.1 Required Standards
+
+All implementation derived from this spec MUST preserve:
+
+- deterministic execution-request submission through the existing runtime enrollment path
+- normalized `{ ok, data/error }` dashboard and tool response envelopes
+- single-active-run repository ownership semantics
+- atomic state mutation through existing kernel/service seams rather than ad hoc dashboard writes
+- accessibility and responsive behavior already required by the dashboard specs this document depends on
+
+### 0.2 OOP and Architecture Guardrails (Mandatory)
+
+Implementation MUST follow:
+
+- **KISS**: keep dashboard intake, preview, submission, and recovery actions as separate focused modules instead of one oversized route/controller.
+- **SRP**: root triage layout, launch authoring flow, execution-request submission, and action authorization MUST remain separate responsibilities.
+- **SOLID-oriented design**:
+  - open/closed for future intake sources beyond upload/paste without rewriting enrollment plumbing
+  - interface segregation between preview/render helpers, submission helpers, and recovery-action helpers
+  - dependency inversion so dashboard routes depend on reusable orchestration/service seams rather than hard-coded CLI behavior
+- **Hexagonal alignment**: the dashboard MUST call orchestrator services/tools; it MUST NOT become a second control-plane implementation.
+- **Composition over inheritance**: build the launch page from small draft/preview/submission components and helper modules.
+- **High cohesion / low coupling**: triage-drawer UX fixes must not be bundled with deep Focus-view review behavior.
+
+---
+
+## 1. Problem Statement
+
+The current dashboard has three related gaps:
+
+1. Quick Launch exists only as a small inline panel and initializes a single feature via `feature.init`; it does not work as a first-class spec intake surface and does not reuse the active-run enrollment model introduced by `aop add`.
+2. Operators can see blocked or stalled work but cannot consistently recover it from the dashboard using the same semantics as CLI `add --resume` and `retry`.
+3. The root triage drawer is positioned in a way that can obscure header controls, and the dashboard lacks persistent navigation affordances to repo/docs destinations.
+
+The desired behavior is a dashboard command surface that is useful for intake and lightweight control, while leaving deep review in `/feature/:id`.
+
+---
+
+## 2. Design Summary
+
+### 2.1 New Quick Launch Route
+
+Add a dedicated route:
+
+- `packages/web-dashboard/src/app/launch/page.tsx`
+
+This route becomes the primary dashboard authoring surface for new work intake.
+
+The existing root-page Quick Launch affordance MUST be reduced to:
+
+- a button or link to `/launch`
+- lightweight availability/status messaging only
+- no multi-field authoring workflow on the root route
+
+### 2.2 Submission Model
+
+Quick Launch MUST submit through the same durable execution-enrollment pipeline as CLI `aop add`.
+
+That means the dashboard MUST NOT shell out to CLI commands and MUST NOT bypass runtime request persistence.
+
+Normative rule:
+
+- dashboard intake -> server-side spec normalization/preview -> execution request submission -> supervisor enrollment
+
+### 2.3 Multi-Spec Authoring Model
+
+The Quick Launch page MUST support a batch of draft specs.
+
+Each draft card contains:
+
+- `feature_id`
+- markdown source
+- source type: `upload` or `paste`
+- preview status
+- validation errors, if any
+
+The page MUST allow operators to:
+
+- upload multiple `.md` files in one action
+- paste one markdown block and add it as a draft
+- paste multiple markdown blocks as separate drafts only if they are explicitly delimited by the UI flow; free-form auto-splitting is out of scope for v1
+- remove drafts before submission
+- submit one draft or all valid drafts
+
+---
+
+## 3. Functional Requirements
+
+### FR-1 Dedicated Launch Navigation
+
+The dashboard header or root-page control surface MUST include a visible link/button to the new Quick Launch route.
+
+Acceptance criteria:
+
+1. `/` exposes a non-hidden path to `/launch`.
+2. `/launch` is reachable by keyboard and touch.
+3. The current inline panel no longer owns the full intake workflow.
+
+### FR-2 Markdown Upload and Paste
+
+Quick Launch MUST accept either:
+
+- file upload of one or more markdown files
+- direct markdown paste into a draft composer
+
+Acceptance criteria:
+
+1. Uploaded files are read server-side or client-side and shown as draft specs before submission.
+2. Pasted markdown is preserved exactly for preview and downstream ingestion.
+3. Unsupported file types fail with inline validation, not silent ignore.
+
+### FR-3 Rendered Markdown Preview
+
+Each draft MUST have a rendered preview panel and a raw markdown editor/reader panel.
+
+Acceptance criteria:
+
+1. Markdown rendering happens before submission.
+2. Preview and raw source stay synchronized.
+3. Render failures degrade to raw markdown with an explicit warning.
+
+### FR-4 Reuse `aop add` Semantics
+
+Quick Launch MUST reuse the same core semantics as `aop add`:
+
+- canonical feature resolution
+- durable execution request submission
+- active-run targeting
+- request disposition tracking
+
+Acceptance criteria:
+
+1. Dashboard submissions create an execution request artifact, not an ad hoc state mutation.
+2. The server path rejects submission when no active run is available.
+3. Duplicate/terminal/already-queued handling matches the enrollment scheduler behavior already used by `aop add`.
+
+### FR-5 Multi-Feature Add
+
+The Quick Launch page MUST support batch submission of multiple valid specs in one request.
+
+Acceptance criteria:
+
+1. A single dashboard action can submit multiple feature specs.
+2. Request ordering remains deterministic by draft order, then `feature_id`.
+3. Partial validity is supported: invalid drafts block only themselves unless the operator chooses “submit all-or-none”.
+
+### FR-6 Resume/Retry Dashboard Actions
+
+Dashboard operators MUST be able to recover stalled or blocked features directly from dashboard surfaces.
+
+Rules:
+
+- `blocked` features with retry-eligible evidence use the existing retry path.
+- `stalled` features use resumable re-enrollment semantics aligned to `aop add --resume`.
+- the UI label MAY be unified (`Resume / Retry`) but the backend action MUST preserve the correct semantic path.
+
+Acceptance criteria:
+
+1. Root triage drawer and focus view both expose recovery affordances when the action is valid.
+2. `stalled` does not incorrectly call the gate retry endpoint.
+3. Recovery actions return updated action-state envelopes just like existing dashboard mutations.
+
+### FR-7 Non-Intrusive Triage Drawer
+
+The root-route triage drawer MUST stop blocking access to `Board`, `List`, and `Analytics`.
+
+Normative layout rule:
+
+- on desktop, the triage drawer must live inside the page grid below the header, not as an overlay that can cover top navigation
+- on smaller breakpoints, it may become a sheet/drawer, but header navigation must remain reachable or the drawer must yield focus/space cleanly
+
+Acceptance criteria:
+
+1. Header controls remain clickable while a feature is selected.
+2. Keyboard focus is not trapped unexpectedly on desktop.
+3. The drawer still shows summary, actions, and “Open Focus View”.
+
+### FR-8 Footer Links
+
+The dashboard MUST include persistent footer links to:
+
+- the GitHub repository
+- the documentation
+
+Acceptance criteria:
+
+1. Links appear on root, launch, analytics, and focus routes through shared layout or shared footer composition.
+2. URLs can come from configuration, environment, or package metadata fallback.
+3. Missing configured URLs degrade to sensible repository-local defaults where possible.
+
+---
+
+## 4. API and UI Contracts
+
+### 4.1 New Routes
+
+Add:
+
+- `GET /launch`
+- `POST /api/launch/preview`
+- `POST /api/launch/submit`
+
+`/api/launch/preview` responsibilities:
+
+- accept uploaded or pasted markdown drafts
+- validate shape and derive candidate `feature_id`
+- return rendered preview payloads and validation results
+
+`/api/launch/submit` responsibilities:
+
+- normalize approved drafts into execution-request payloads
+- submit durable enrollment requests against the active run
+- return per-draft outcomes and request ids
+
+### 4.2 Draft Payload Shape
+
+```json
+{
+  "drafts": [
+    {
+      "draft_id": "draft_01",
+      "feature_id": "feature_checkout_flow",
+      "markdown": "# Feature Spec ...",
+      "source_type": "upload"
+    }
+  ],
+  "mode": "submit_valid"
+}
+```
+
+### 4.3 Action Additions
+
+Extend dashboard action handling with a resumable action path.
+
+Recommended action names:
+
+- `feature.resume`
+- `feature.retry`
+
+If the existing `feature.retry` name is retained for the UI, the server must still branch into resume vs retry logic based on feature state and action type rather than overloading one tool call blindly.
+
+---
+
+## 5. File-Level Targets
+
+- `packages/web-dashboard/src/app/page.tsx`
+  - replace root Quick Launch authoring with route link and compact status.
+- `packages/web-dashboard/src/app/launch/page.tsx`
+  - new dedicated intake route.
+- `packages/web-dashboard/src/app/layout.tsx`
+  - shared footer with repo/docs links.
+- `packages/web-dashboard/src/app/api/launch/preview/route.ts`
+  - new preview endpoint.
+- `packages/web-dashboard/src/app/api/launch/submit/route.ts`
+  - new submission endpoint wired to execution request submission.
+- `packages/web-dashboard/src/app/api/actions/route.ts`
+  - add resume-aware dashboard recovery path.
+- `packages/web-dashboard/src/components/quick-launch-panel.tsx`
+  - repurpose as compact link/status affordance or retire in favor of route-local components.
+- `packages/web-dashboard/src/components/dashboard/triage-drawer.tsx`
+  - move to non-obstructive layout contract and add resume/retry affordances.
+- `packages/web-dashboard/src/components/dashboard/command-center-header.tsx`
+  - add Quick Launch navigation entry.
+- `packages/web-dashboard/src/lib/orchestrator-tools.ts`
+  - add execution-request submission helpers if required.
+- `packages/web-dashboard/src/lib/types.ts`
+  - add launch draft/preview/submit payload types.
+- `apps/control-plane/src/cli/spec-input-resolver.ts`
+  - reuse semantics only; dashboard must not fork spec parsing logic from the CLI path.
+- `apps/control-plane/src/cli/spec-ingestion-service.ts`
+  - likely extraction target for dashboard/server reuse.
+
+---
+
+## 6. Acceptance Criteria
+
+1. Operators can navigate to a dedicated Quick Launch route from the dashboard.
+2. Quick Launch accepts uploaded or pasted markdown and renders a preview before submission.
+3. Quick Launch can submit multiple features in one action.
+4. Submitted dashboard work enters the same durable active-run enrollment pipeline as `aop add`.
+5. Blocked and stalled features can be recovered from dashboard surfaces using the correct underlying semantics.
+6. The root triage drawer no longer obstructs root-route navigation controls.
+7. Footer links to repo/docs are visible across dashboard routes.
+
+---
+
+## 7. Risks and Mitigations
+
+- Risk: dashboard implements a separate spec parser that diverges from CLI behavior.
+  - Mitigation: extract reusable normalization logic from existing CLI services instead of duplicating markdown-to-feature rules in the Next.js layer.
+- Risk: batch submission hides partial failures.
+  - Mitigation: return per-draft outcomes and explicit request ids.
+- Risk: resume and retry semantics get conflated for stalled vs blocked work.
+  - Mitigation: keep server-side state-driven branching explicit and test both flows separately.

package/spec-files/outstanding/agentic_orchestrator_enterprise_governance_dashboard_spec.md

@@ -2,9 +2,9 @@
 
 > **Purpose of this document**: Define implementation-ready delivery for Q5 and Q6: compliance policy packs + control export, and production-grade dashboard authentication/authorization with audit federation.
 
-**Version:** 1.0  
-**Date:** 2026-03-03  
-**Status:** Draft  
+**Version:** 1.1  
+**Date:** 2026-03-15  
+**Status:** Draft (Audited Against Current Repo State)  
 **Roadmap Mapping:** M37
 
 ---
@@ -27,6 +27,15 @@ Implementation MUST preserve:
 - audit-log completeness for privileged operations
 - optional/off-by-default behavior for local developer environments
 
+### 0.3 Current Project State
+
+This spec is still outstanding, but the dashboard/runtime baseline has advanced since the original draft:
+
+- The web dashboard already exists and now routes most privileged mutations through `packages/web-dashboard/src/app/api/actions/route.ts`, with launch actions under `packages/web-dashboard/src/app/api/run/route.ts` and triage-state reads under `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`.
+- A pluggable authorization seam already exists in `packages/web-dashboard/src/lib/authz-adapter.ts`, but it currently defaults to allow-all behavior and does not satisfy Q6.
+- No compliance-pack assets, compliance export service/tool, real auth middleware, or dashboard audit-federation service exist yet.
+- This spec must therefore build on the current dashboard seams rather than the older per-route action layout assumed in v1.0.
+
 ---
 
 ## 1. Objectives
@@ -247,10 +256,11 @@ Each action must map to role permission in policy.
 ### 4.2.6 File Targets
 
 - `packages/web-dashboard/src/middleware.ts` (new)
-- `packages/web-dashboard/src/lib/authz.ts` (new)
+- `packages/web-dashboard/src/lib/authz-adapter.ts`
 - `packages/web-dashboard/src/app/api/auth/*` (new)
-- `packages/web-dashboard/src/app/api/features/[id]/review/route.ts`
-- `packages/web-dashboard/src/app/api/features/[id]/checkout/route.ts`
+- `packages/web-dashboard/src/app/api/actions/route.ts`
+- `packages/web-dashboard/src/app/api/run/route.ts`
+- `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`
 - `apps/control-plane/src/application/services/dashboard-audit-service.ts` (new)
 
 ### 4.2.7 Acceptance Criteria

package/spec-files/outstanding/agentic_orchestrator_evidence_integrity_doctor_spec.md

@@ -4,9 +4,9 @@
 > **Covers**: OID2 (Q4 Evidence Integrity) + OID3 (Q11 Doctor) + OID4 (CLI surface) + OID5 (Hardening)
 > **Roadmap Mapping:** M33 / Q4 + Q11
 
-**Version:** 1.0
-**Date:** 2026-03-05
-**Status:** Implementation-Ready
+**Version:** 1.2
+**Date:** 2026-03-16
+**Status:** Draft (Audited Against Current Repo State)
 
 ---
 
@@ -14,7 +14,9 @@
 
 ### 0.1 Prerequisite
 
-**This spec MUST NOT begin implementation until `agentic_orchestrator_observability_replay_spec` has been merged.**
+**Prerequisite status (2026-03-15): satisfied.** `agentic_orchestrator_observability_replay_spec` OID0/OID1/OID4 has been implemented in the repository.
+
+This spec was originally blocked on that merge because it depends on shared observability scaffolding from the replay spec.
 
 Specifically, that spec's OID0 must be complete, which provides:
 
@@ -31,7 +33,7 @@ grep -q "evidence_chain_missing" apps/control-plane/src/core/error-codes.ts
 grep -q "evidence.verify_chain" agentic/orchestrator/tools/catalog.json
 ```
 
-If either check fails, do not proceed — block on the prerequisite spec.
+If either check fails, assume the local branch has drifted or regressed and block on restoring the prerequisite scaffolding before continuing.
 
 ### 0.2 Required Standards
 
@@ -82,6 +84,33 @@ Out of scope:
 - External KMS/HSM signing
 - Remote telemetry backends
 
+### 0.5 Current Project State
+
+This spec was audited against the live repository on 2026-03-16.
+
+Current status:
+
+1. **Replay scaffolding is complete; evidence/doctor implementation is not.**
+   - `replay.timeline_get` and `aop replay` are implemented.
+   - `evidence.verify_chain` and `doctor.run` exist only as catalog entries plus stub schemas.
+
+2. **There is currently no kernel or runtime handler wiring for evidence/doctor.**
+   - `apps/control-plane/src/application/kernel-tool-wiring.ts` and `apps/control-plane/src/core/kernel.ts` do not expose `evidence.verify_chain` or `doctor.run`.
+   - `agentic/orchestrator/policy.yaml` and `agentic/orchestrator/defaults/policy.defaults.yaml` do not currently grant RBAC access to either tool.
+
+3. **There is currently no CLI surface for either feature.**
+   - `CliCommand`, `CliArgumentParser`, `COMMAND_CATALOG`, and CLI bootstrap do not include `doctor` or `evidence verify`.
+   - the spec must therefore describe the full command lifecycle against the current command-catalog architecture, not the older help-only command wiring model.
+
+4. **`GateService.evidenceLatest()` still has the exact broad-scan behavior this spec warned about.**
+   - it still scans all `.json` files in the evidence directory when no mode is specified.
+   - this pre-work remains mandatory before chain metadata is introduced into that directory.
+
+5. **The current stub schemas do not match the desired final contracts.**
+   - `evidence.verify_chain` output schema is still a loose placeholder.
+   - `doctor.run` input/output schemas are still placeholders and do not yet encode the report contract defined here.
+   - implementation must replace those stubs, not build around them.
+
 ---
 
 ## 1. Architectural Context
@@ -101,6 +130,8 @@ This fix must land before any chain files are written to the evidence directory.
 - **Evidence write path**: `GateService.gatesRun()` + `core/gates.ts` is the authoritative source for gate evidence artifacts. `EvidenceIntegrityService` hooks into the GateService write path.
 - **Read/report path**: `ReportingService` is the read aggregation surface. Integrity checks must not bypass service boundaries.
 - **Config validation**: `SchemaRegistry` + `loadComposedPolicy` used by doctor for DRIFT_001/DRIFT_002 checks.
+- **Current tool wiring seam**: kernel dispatch now flows through `apps/control-plane/src/application/kernel-tool-wiring.ts`; this spec must add evidence/doctor handlers there instead of assuming a monolithic switch-only kernel path.
+- **Current CLI help/completion seam**: command usage/help metadata is centralized in `apps/control-plane/src/cli/command-catalog.ts`.
 
 ### 1.3 Boundary Rules (Normative)
 
@@ -324,7 +355,16 @@ doctorHistoryPath(ts: string): string      // .aop/runtime/doctor/history/<ts>.j
 - `apps/control-plane/src/application/services/evidence-integrity-service.ts` (new)
 - `apps/control-plane/src/application/services/gate-service.ts` — fix `evidenceLatest`, add `EvidenceIntegrityService` integration
 - `apps/control-plane/src/core/path-layout.ts` — evidence chain + doctor path helpers
-- `apps/control-plane/src/core/kernel.ts` — register `evidence.verify_chain` handler
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/application/tools/tool-metadata.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/application/kernel-tool-wiring.ts`
+- `agentic/orchestrator/policy.yaml`
+- `agentic/orchestrator/defaults/policy.defaults.yaml`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/evidence.verify_chain.input.schema.json` — replace stub
+- `agentic/orchestrator/tools/schemas/output/evidence.verify_chain.output.schema.json` — replace stub
+- `agentic/orchestrator/tools.md` — regenerate after replacing the stub contract
 
 **Test plan**:
 
@@ -389,7 +429,16 @@ Implement deterministic scanner with fixed check IDs, strict severity, and stabl
 - `apps/control-plane/src/application/services/doctor-service.ts` (new)
 - `agentic/orchestrator/schemas/doctor_report.schema.json` (new — validates report output)
 - `apps/control-plane/src/core/path-layout.ts` — doctor path helpers (if not already added in OID2)
-- `apps/control-plane/src/core/kernel.ts` — register `doctor.run` handler
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/application/tools/tool-metadata.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/application/kernel-tool-wiring.ts`
+- `agentic/orchestrator/policy.yaml`
+- `agentic/orchestrator/defaults/policy.defaults.yaml`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/doctor.run.input.schema.json` — replace stub
+- `agentic/orchestrator/tools/schemas/output/doctor.run.output.schema.json` — replace stub
+- `agentic/orchestrator/tools.md` — regenerate after replacing the stub contract
 
 **Test plan**:
 
@@ -438,10 +487,12 @@ aop doctor [--strict] [--json]
 1. `apps/control-plane/src/cli/types.ts` — add `CliCommand.Evidence`, `CliCommand.Doctor`; add `strict` option field
 2. `apps/control-plane/src/cli/cli-argument-parser.ts` — parse `evidence verify` subcommand and `doctor`
 3. `apps/control-plane/src/interfaces/cli/bootstrap.ts` — dispatch both commands to handlers
-4. `apps/control-plane/src/cli/help-command-handler.ts` — add `evidence` and `doctor` entries to `COMMAND_HELP`
+4. `apps/control-plane/src/cli/command-catalog.ts` — add `evidence` and `doctor` command definitions so help/completion stay aligned
 5. `apps/control-plane/src/cli/evidence-command-handler.ts` (new)
 6. `apps/control-plane/src/cli/doctor-command-handler.ts` (new)
 
+If `help-command-handler.ts` requires explicit updates beyond `COMMAND_CATALOG`, those updates must be made in the same change, but `command-catalog.ts` is now the primary help surface to keep aligned.
+
 **Doctor CLI semantics**:
 
 - Normal mode: exits non-zero if any critical finding present.
@@ -528,7 +579,7 @@ If any evidence pruning occurs (manual or policy-driven), chain integrity may fa
 3. `aop doctor` produces deterministic, schema-valid findings with actionable remediations, sorted by check ID.
 4. Doctor strict mode exits non-zero on warnings; normal mode exits non-zero only on criticals.
 5. `evidence.verify_chain` and `doctor.run` tools are fully wired: constants / kernel / tool-metadata / catalog / schemas / RBAC / tools.md.
-6. `aop evidence verify` and `aop doctor` commands are fully wired: types / parser / help / bootstrap / handlers.
+6. `aop evidence verify` and `aop doctor` commands are fully wired: types / parser / command-catalog / bootstrap / handlers.
 7. DRIFT_007 correctly fires when an integrity-tracked artifact is missing.
 8. Quality gates pass: `lint`, `typecheck`, `test`, `validate:mcp-contracts`, `validate:architecture`.