agentic-orchestrator 0.1.13 → 0.1.15

package/spec-files/outstanding/agentic_orchestrator_human_input_interaction_protocol_spec.md

@@ -0,0 +1,590 @@
+# Feature Spec: Human Input Interaction Protocol for Agent Cluster (AOP)
+
+> **Purpose of this document**: Define a first-class, deterministic protocol for cases where planner/builder/qa must pause and request human input (clarifications, approvals, permission overrides) before safe continuation.
+
+**Version:** 1.1  
+**Date:** 2026-03-04  
+**Status:** Draft  
+**Roadmap Mapping:** M43
+
+---
+
+## 0. Standards and Dependencies
+
+### 0.1 Required Standards
+
+All implementation MUST preserve:
+
+- deterministic orchestration behavior and state transitions
+- MCP/in-process tool contract parity
+- strict schema validation (`validate:mcp-contracts`, `validate:architecture`)
+- canonical runtime artifacts under `.aop/**`
+- global topology invariants (`1 + 3N` active sessions)
+- idempotent behavior for mutating tool calls (`operation_id` required)
+
+### 0.2 Required Inputs
+
+Implementing agents MUST read:
+
+- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
+- `apps/control-plane/src/supervisor/run-coordinator.ts`
+- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
+- `apps/control-plane/src/supervisor/build-wave-executor.ts`
+- `apps/control-plane/src/supervisor/qa-wave-executor.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/cli/status-command-handler.ts`
+- `apps/control-plane/src/cli/send-command-handler.ts`
+- `apps/control-plane/src/application/services/activity-monitor-service.ts`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/schemas/state.schema.json`
+- `agentic/orchestrator/schemas/index.schema.json`
+- `agentic/orchestrator/policy.yaml`
+- `agentic/orchestrator/schemas/policy.schema.json`
+
+### 0.3 Scope
+
+This spec implements:
+
+- explicit question/answer protocol between agents and humans
+- deterministic pause-and-resume behavior for features awaiting input
+- new MCP tools and schema artifacts for question lifecycle
+- CLI and dashboard-facing retrieval/answer workflows
+- regression coverage for question-blocked execution and resume
+
+Out of scope:
+
+- external ticketing approval workflows (Jira/ServiceNow sync)
+- cryptographic signature workflows for approvals
+- model-vendor-specific conversational UX
+
+### 0.4 OOP and Architecture Guardrails (Mandatory)
+
+Implementation for this spec MUST follow explicit object-oriented and architectural best practices:
+
+- **KISS**: implement the smallest deterministic question/answer protocol that satisfies the contract.
+- **SRP (Single Responsibility Principle)**: question persistence, state transitions, CLI handling, and status projection MUST remain in separate modules/services.
+- **SOLID-oriented design** (applied pragmatically):
+  - open/closed for new question types or answer validators without changing unrelated orchestration flow
+  - interface segregation for question store/service/query ports
+  - dependency inversion so supervisor/CLI depend on contracts, not storage details
+- **Hexagonal architecture alignment**: domain/application logic must not depend directly on transport adapters (CLI/MCP/dashboard).
+- **Composition over inheritance**: compose question validators/parsers/services rather than building inheritance-heavy hierarchies.
+- **High cohesion / low coupling**: keep WorkerDecisionLoop routing, Kernel state mutation, and artifact I/O separated.
+
+Code organization requirements for this spec:
+
+- question lifecycle domain logic lives in dedicated services (`create`, `answer`, `list`, `expire`)
+- feature status transitions (`awaiting_input` <-> resumed phase) are owned by kernel/application services, not CLI handlers
+- CLI and dashboard adapters are thin and invoke tool/service contracts only
+- provider-specific worker payload formats are normalized before domain question handling
+
+---
+
+## 1. Current Gap and Defect Class
+
+Current system behavior is missing a first-class handshake when agents need input:
+
+1. worker `REQUEST` handling has no `ask_user` action contract.
+2. `waiting_input` exists only as heuristic activity derivation from `status_reason` text.
+3. there is no durable question queue artifact.
+4. no structured answer tool exists (`feature.send_message` is unstructured best-effort delivery).
+5. run loop has no deterministic pause/resume contract for unresolved questions.
+
+Result: operators must use ad hoc `send`/`attach` workflows, and orchestrator semantics are ambiguous when a role cannot proceed safely without human response.
+
+---
+
+## 2. Objectives
+
+### 2.1 Must-Have Outcomes
+
+1. Agents can raise a structured blocking question via tool contract.
+2. Feature enters deterministic `awaiting_input` state until answered (or expired/escalated).
+3. Human answers are persisted as first-class artifacts and fed back into role context.
+4. Orchestrator does not run planner/build/qa waves for features with open blocking questions.
+5. Answering a question deterministically resumes the correct phase.
+6. `aop status` can show pending-question state without heuristic parsing.
+
+### 2.2 Non-Goals
+
+- replacing existing `aop send` and `aop attach` commands
+- introducing a free-form chat broker between human and agents
+- adding real-time websocket transport requirements to core runtime
+
+---
+
+## 3. Terminology and Invariants
+
+### 3.1 New Terms
+
+- **Blocking Question**: a question that must be answered before wave execution can continue.
+- **Question Record**: durable structured artifact for one question lifecycle.
+- **Awaiting Input State**: explicit feature status indicating orchestrator pause pending answer.
+
+### 3.2 Invariants
+
+1. Exactly zero or one **active blocking question** per feature at a time.
+2. A feature in `awaiting_input` cannot execute planning/build/qa wave logic.
+3. Answers are append-only in question history (no destructive rewrites).
+4. Answer operations are idempotent by `operation_id`.
+5. Resume phase is deterministic from recorded pre-question status.
+
+---
+
+## 4. End-to-End Lifecycle (Normative)
+
+### 4.1 Ask Flow
+
+1. Worker emits:
+
+```json
+{
+  "type": "REQUEST",
+  "request": {
+    "action": "ask_user_input",
+    "question_type": "permission_override",
+    "prompt": "Allow editing file outside planned file set: config/security/policy.yaml?",
+    "details": {
+      "requested_paths": ["config/security/policy.yaml"],
+      "reason": "Fix required by failing gate"
+    },
+    "expected_answer": {
+      "kind": "single_choice",
+      "choices": ["approve", "deny", "needs_more_context"]
+    },
+    "blocking": true
+  }
+}
+```
+
+2. `WorkerDecisionLoop` routes this to `feature.question_create`.
+3. Kernel persists question record and transitions feature state to `awaiting_input`.
+4. Feature retains active session assignment but is skipped by phase executors.
+5. Operator sees pending question in `aop status` and `aop questions`.
+
+### 4.2 Answer Flow
+
+1. Human answers via `aop answer --feature-id <id> --question-id <qid> --answer <json-or-text>`.
+2. `feature.question_answer` persists answer and closes question.
+3. Kernel restores feature status to recorded `resume_status`.
+4. Next orchestration iteration resumes normal phase execution.
+5. Answer is included in `feature.get_context` under `human_input.latest_answer`.
+
+### 4.3 Timeout / Expiry Flow
+
+1. If no answer before timeout (`policy.execution.human_input_timeout_ms`), question becomes `expired`.
+2. Configured action applies (`block_feature` or `fail_feature`).
+3. Expiry is logged in decisions and question history.
+
+---
+
+## 5. Contract and Schema Deltas
+
+### 5.1 Feature Status Contract
+
+Add new status constant and schema enum:
+
+- `awaiting_input`
+
+State semantics:
+
+- terminal: no
+- wave-executable: no
+- eligible for resume: yes (after question resolution)
+
+### 5.2 State Frontmatter Additions (`state.schema.json`)
+
+Add:
+
+```yaml
+human_input:
+  open_question_id: string | null
+  open_question_count: integer
+  awaiting_since: date-time | null
+  requested_by_role: string | null
+  resume_status: string | null
+```
+
+Rules:
+
+- `open_question_id` must be null when status is not `awaiting_input`.
+- `resume_status` must be one of `planning|building|qa|blocked|ready_to_merge` when awaiting input.
+
+### 5.3 Question Artifact Contract
+
+Add per-feature artifact:
+
+```text
+.aop/features/<feature_id>/questions.json
+```
+
+Shape:
+
+```json
+{
+  "version": 1,
+  "feature_id": "feature_x",
+  "items": [
+    {
+      "question_id": "q_01J...",
+      "status": "open",
+      "blocking": true,
+      "question_type": "permission_override",
+      "role": "builder",
+      "session_id": "builder-feature_x-...",
+      "prompt": "Allow editing ... ?",
+      "details": { "requested_paths": ["..."] },
+      "expected_answer": { "kind": "single_choice", "choices": ["approve", "deny"] },
+      "created_at": "2026-03-04T22:00:00.000Z",
+      "expires_at": "2026-03-04T22:15:00.000Z",
+      "answer": null,
+      "answered_at": null,
+      "answered_by": null,
+      "resume_status": "building"
+    }
+  ]
+}
+```
+
+### 5.4 Tool Catalog Additions
+
+Add new MCP tools:
+
+1. `feature.question_create` (mutating)
+2. `feature.question_list` (read)
+3. `feature.question_answer` (mutating)
+
+#### `feature.question_create` input
+
+- `feature_id` (string)
+- `role` (`planner|builder|qa|orchestrator`)
+- `session_id` (string)
+- `question_type` (`clarification|permission_override|external_decision|risk_ack`)
+- `prompt` (string, min length 1)
+- `details` (object, optional)
+- `expected_answer` (object with `kind`, optional choices/schema)
+- `blocking` (boolean, default true)
+- `operation_id` (string, required)
+
+Output:
+
+- `question_id`
+- `status`
+- `feature_status`
+- `resume_status`
+
+#### `feature.question_list` input
+
+- `feature_id` (string)
+- `status` (`open|answered|expired|withdrawn|all`, default `open`)
+
+Output:
+
+- array of matching question records (stable sorted by `created_at` ascending)
+
+#### `feature.question_answer` input
+
+- `feature_id` (string)
+- `question_id` (string)
+- `answer` (string or object)
+- `answered_by` (string; `human` or operator identity)
+- `operation_id` (string, required)
+
+Output:
+
+- `question_id`
+- `question_status` (`answered`)
+- `feature_status` (resumed phase)
+- `resumed` (boolean)
+
+### 5.5 Error Taxonomy Additions
+
+Add:
+
+- `question_not_found`
+- `question_already_answered`
+- `question_invalid_answer`
+- `question_conflict_open`
+- `question_answer_not_allowed_in_terminal_state`
+
+---
+
+## 6. Runtime Behavior Changes
+
+### 6.1 WorkerDecisionLoop
+
+Add handling for `REQUEST.action=ask_user_input`:
+
+- call `feature.question_create`
+- mark request handled
+- append note to feature log with question id
+
+Unknown `REQUEST.action` remains no-op but MUST log a warning note for observability.
+
+### 6.2 RunCoordinator and Wave Executors
+
+When feature status is `awaiting_input`:
+
+- planning/build/qa executors must skip worker execution and gates
+- no automatic transition to `blocked` or `failed` unless timeout policy triggers
+- feature remains in the current runtime scope (session cluster intact)
+
+### 6.3 Context Enrichment
+
+`feature.get_context` adds:
+
+```yaml
+human_input:
+  open_questions: [...]
+  latest_answer: {...} | null
+```
+
+Rules:
+
+- planner/builder/qa receive at most last `N` answered questions (`N` configurable, default 3)
+- open questions included only for same feature
+
+### 6.4 Activity State Determinism
+
+Stop relying on heuristic `status_reason` parsing for waiting-input detection:
+
+- if state status is `awaiting_input`, `activity_state` reports `waiting_input`
+- heuristic fallback remains only for backward compatibility during migration window
+
+---
+
+## 7. CLI and Dashboard Surface
+
+### 7.1 New CLI Commands
+
+Add:
+
+1. `aop questions --feature-id <id> [--status open|answered|expired|withdrawn|all]`
+2. `aop answer --feature-id <id> --question-id <qid> --answer <value> [--answered-by <id>]`
+
+Behavior:
+
+- both commands return structured JSON envelopes
+- answer command validates feature/question state and idempotency
+
+### 7.2 Status Output Enhancements
+
+`aop status` and dashboard payload include:
+
+- `open_question_count`
+- `open_question_id`
+- `awaiting_since`
+- `resume_status`
+
+---
+
+## 8. Planner / Builder / QA Role Semantics
+
+### 8.1 Planner
+
+Planner may ask blocking clarification questions when spec ambiguities prevent safe plan updates.
+
+### 8.2 Builder
+
+Builder may ask blocking permission questions for out-of-plan or protected path changes.
+
+### 8.3 QA
+
+QA may ask blocking risk-acknowledgement questions when gate failures imply high-risk tradeoffs.
+
+### 8.4 Orchestrator
+
+Orchestrator does not synthesize answers. It only records question lifecycle and enforces state transitions.
+
+---
+
+## 9. Policy Contract
+
+Add under `policy.execution`:
+
+```yaml
+human_input:
+  enabled: true
+  timeout_ms: 900000
+  on_timeout: block_feature # block_feature | fail_feature
+  max_open_questions_per_feature: 1
+  context_answer_history_limit: 3
+```
+
+Rules:
+
+- if `enabled=false`, `feature.question_create` returns `unsupported_operation`
+- `max_open_questions_per_feature=1` is enforced strictly in v1
+
+---
+
+## 10. Edge-Case Matrix (Normative)
+
+1. Duplicate create requests with same `operation_id`:
+
+- replay exact prior success envelope.
+
+2. New question when an open blocking question already exists:
+
+- reject with `question_conflict_open`.
+
+3. Answer submitted for unknown question id:
+
+- reject with `question_not_found`.
+
+4. Answer submitted for already answered question:
+
+- return idempotent success if same operation replay, else `question_already_answered`.
+
+5. Feature reaches terminal status while question open:
+
+- auto-close question as `withdrawn` and retain history.
+
+6. Resume status no longer valid at answer time:
+
+- fallback resume to `planning` and log deterministic reason.
+
+7. Multi-project mode:
+
+- question artifacts must resolve under selected project root only.
+
+8. Stale runtime takeover:
+
+- open questions persist and remain answerable post-takeover.
+
+9. Manual `aop send` while awaiting input:
+
+- allowed; does not auto-answer question.
+
+10. Missing session cluster while answering:
+
+- answer still persists and feature resumes by state transition; session recreation handled by normal runtime recovery.
+
+---
+
+## 11. Implementation Plan
+
+### M43.1 Core Question Service
+
+- add `QuestionService` for create/list/answer lifecycle
+- persist `.aop/features/<id>/questions.json`
+- enforce open-question invariant and idempotency behavior
+
+### M43.2 Tooling and Schema Integration
+
+- add tool constants and kernel routing
+- add catalog entries and input/output schemas
+- add policy/state schema fields
+
+### M43.3 Runtime Integration
+
+- wire `ask_user_input` request handling in `WorkerDecisionLoop`
+- skip awaiting-input features in wave executors
+- enrich `feature.get_context` with human input data
+
+### M43.4 CLI and Reporting
+
+- add `questions` and `answer` commands to parser/bootstrap/help
+- extend status/dashboard payload with question summary fields
+
+### M43.5 Verify Path Coverage
+
+- add unit/integration tests and include in `npm run verify` path
+
+---
+
+## 12. File-Level Change Targets
+
+- `apps/control-plane/src/application/services/question-service.ts` (new)
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
+- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
+- `apps/control-plane/src/supervisor/build-wave-executor.ts`
+- `apps/control-plane/src/supervisor/qa-wave-executor.ts`
+- `apps/control-plane/src/cli/types.ts`
+- `apps/control-plane/src/cli/cli-argument-parser.ts`
+- `apps/control-plane/src/cli/help-command-handler.ts`
+- `apps/control-plane/src/cli/questions-command-handler.ts` (new)
+- `apps/control-plane/src/cli/answer-command-handler.ts` (new)
+- `apps/control-plane/src/interfaces/cli/bootstrap.ts`
+- `apps/control-plane/src/cli/status-command-handler.ts`
+- `apps/control-plane/src/application/services/activity-monitor-service.ts`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/feature.question_create.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/feature.question_create.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/feature.question_list.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/feature.question_list.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/feature.question_answer.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/feature.question_answer.output.schema.json` (new)
+- `agentic/orchestrator/schemas/state.schema.json`
+- `agentic/orchestrator/schemas/policy.schema.json`
+- `agentic/orchestrator/policy.yaml`
+- `README.md`
+- `apps/control-plane/test/question-service.spec.ts` (new)
+- `apps/control-plane/test/worker-decision-loop.spec.ts`
+- `apps/control-plane/test/run-coordinator.spec.ts`
+- `apps/control-plane/test/cli.unit.spec.ts`
+- `apps/control-plane/test/status-command.spec.ts`
+- `apps/control-plane/test/mcp.spec.ts`
+
+---
+
+## 13. Test Plan (Must Be in `npm run verify` Path)
+
+### 13.1 Unit
+
+- question create transitions state to `awaiting_input`
+- answer transitions to recorded `resume_status`
+- duplicate open question is rejected
+- answer idempotency and replay behavior
+
+### 13.2 Supervisor Integration
+
+- feature in `awaiting_input` is skipped by all wave executors
+- answering question resumes the next iteration in deterministic phase
+
+### 13.3 CLI Integration
+
+- `aop questions` returns open questions sorted deterministically
+- `aop answer` closes question and reports resumed status
+
+### 13.4 MCP Contract
+
+- all new tools validate schema and role authorization
+- mutating tools enforce `operation_id`
+
+### 13.5 Regression
+
+- GIVEN builder asks permission override WHEN unanswered THEN no further patch/gate actions execute for that feature
+- GIVEN answer is provided WHEN next iteration runs THEN builder resumes and can continue gate repair
+
+---
+
+## 14. Acceptance Criteria
+
+1. Agent-generated blocking questions become first-class persisted artifacts.
+2. Feature status transitions to `awaiting_input` deterministically.
+3. No planning/building/qa waves execute for features with open blocking question.
+4. Human answer flow is deterministic, idempotent, and auditable.
+5. Feature resumes from recorded phase after answer.
+6. `aop status`, `aop questions`, and `aop answer` provide complete operator workflow.
+7. `npm run verify` fails if awaiting-input pause/resume invariants regress.
+8. Implementation boundaries follow KISS/SRP/SOLID/Hexagonal requirements from Section 0.4.
+
+---
+
+## 15. Risks and Mitigations
+
+- Risk: status-model expansion (`awaiting_input`) causes unintended branch regressions.
+  - Mitigation: add explicit status transition tests in all wave executors and coordinator.
+
+- Risk: unanswered questions stall active slots indefinitely.
+  - Mitigation: policy timeout with deterministic expiry action and status reporting.
+
+- Risk: users bypass structured answers with ad hoc `send`.
+  - Mitigation: keep `send` but require `question_answer` to clear blocking state.
+
+- Risk: tool-surface growth increases contract maintenance load.
+  - Mitigation: strict MCP schema/metadata validation and parity tests.