agentic-orchestrator 0.1.28 → 0.2.1

package/spec-files/completed/agentic_orchestrator_interactive_planning_intake_and_requirements_verification_spec.md

@@ -0,0 +1,1185 @@
+# Feature Spec: Interactive Planning Intake and Requirements Verification
+
+> **Purpose of this document**: Redesign the planner mental model so raw `spec.md` is first normalized into a verified requirements contract through an explicit intake phase before normal execution planning begins.
+
+**Version:** 1.1  
+**Date:** 2026-03-17  
+**Status:** Draft  
+**Roadmap Mapping:** M59
+
+---
+
+## 0. Standards and Dependencies
+
+### 0.1 Required Standards
+
+All implementation MUST preserve:
+
+- deterministic orchestration state transitions and normalized error envelopes
+- MCP/in-process tool parity
+- atomic artifact mutation under `.aop/**`
+- optimistic concurrency for `plan.json`
+- compatibility with the shared M43 human-input protocol baseline
+- platform-agnostic requirement and traceability semantics
+
+### 0.2 Required Inputs
+
+Implementing agents MUST read:
+
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `apps/control-plane/src/application/services/feature-lifecycle-service.ts`
+- `apps/control-plane/src/application/services/plan-service.ts`
+- `apps/control-plane/src/application/services/question-service.ts`
+- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
+- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
+- `apps/control-plane/src/supervisor/runtime.ts`
+- `agentic/orchestrator/schemas/state.schema.json`
+- `agentic/orchestrator/schemas/policy.schema.json`
+- `agentic/orchestrator/prompts/planner.system.md`
+- `config/agentic/orchestrator/prompts/planner.system.md`
+- `spec-files/outstanding/agentic_orchestrator_human_input_interaction_protocol_spec.md`
+- `spec-files/outstanding/agentic_orchestrator_spec_coverage_and_reconciliation_enforcement_spec.md`
+
+### 0.3 Scope
+
+This spec implements:
+
+- a new explicit `intake` phase before execution planning
+- planner role split into:
+  - requirements normalization during intake
+  - execution planning after verified requirements exist
+- bootstrap manifest proposal generation from arbitrary `spec.md`
+- verified manifest promotion before builder/QA are allowed to run
+- targeted user interaction during intake using existing question protocol
+- artifact and policy changes needed to keep builder, QA, and later planner reconciliation anchored to the same verified contract
+- intake-specific UI and payload extensions on top of the M43 baseline
+
+Out of scope:
+
+- full product-discovery conversations
+- arbitrary free-form chat between operator and agents
+- platform-specific semantic verification
+- replacing or re-specifying the generic question protocol owned by M43
+
+### 0.4 Dependency Boundary
+
+M43 (`agentic_orchestrator_human_input_interaction_protocol_spec.md`) is the prerequisite and authoritative baseline for:
+
+- `awaiting_input`
+- `questions.json`
+- `feature.question_create`
+- `feature.question_list`
+- `feature.question_answer`
+- generic question-ready visibility rules
+- shared dashboard/CLI answer transport
+
+This spec defines only the intake-specific extension layer:
+
+- `intake` lifecycle state
+- manifest artifacts
+- intake review/promotion flow
+- intake-specific metadata and UI context
+- intake-only gating of planning/build/QA/reconciliation
+
+---
+
+## 1. Problem Statement
+
+The current planner mental model assumes that one planning phase can:
+
+1. interpret arbitrary raw `spec.md`
+2. infer the intended requirement set
+3. transform that inference into a trustworthy plan
+4. feed builder/QA/reconciliation with a stable target
+
+That is too much responsibility for one phase.
+
+### 1.1 Current Failure Mode
+
+When the planner reads only raw spec prose:
+
+- ambiguity in the spec leaks directly into the plan
+- missing requirements are not surfaced early enough
+- later builder and QA work may be “correct against plan” but still incomplete against user intent
+- post-QA reconciliation is forced to reinterpret raw spec again, which reintroduces nondeterminism
+
+### 1.2 Root Cause
+
+The system lacks a first-class contract-formation step between:
+
+- **raw user intent**
+
+and:
+
+- **deterministic execution**
+
+That gap cannot be solved by better planning prompts alone.
+
+---
+
+## 2. Target Mental Model
+
+The planner is not a single-stage “plan writer.”
+
+It is a two-stage role:
+
+1. **Intake Planner**
+   - normalize raw spec into explicit requirement artifacts
+   - identify ambiguity
+   - ask targeted questions when needed
+   - produce a verified manifest contract
+2. **Execution Planner**
+   - create `plan.json` against that verified manifest
+   - later reconcile implementation and verification progress against that same manifest
+
+### 2.1 New Deterministic Boundary
+
+The deterministic execution loop must begin only after intake completes.
+
+That means:
+
+- arbitrary prose may drive a bootstrap proposal
+- only a verified manifest may drive enforced planning, building, QA, and later reconciliation
+
+### 2.2 Human Interaction Principle
+
+Human interaction belongs at the intake boundary when the system is still uncertain about requirements, not later when builder or QA are already executing against an unstable contract.
+
+Questions during intake should be:
+
+- narrow
+- requirement-forming
+- blocking only when ambiguity materially affects the verified manifest
+
+---
+
+## 3. Lifecycle Redesign
+
+## 3.1 New Feature Status
+
+Add explicit feature status:
+
+- `intake`
+
+Updated lifecycle:
+
+```text
+intake -> planning -> building -> qa -> ready_to_merge -> merged
+```
+
+Cross-cutting pause states remain:
+
+- `awaiting_input`
+- `blocked`
+- `failed`
+
+### 3.1.1 Meaning of `intake`
+
+`intake` means:
+
+- the feature has a canonical `spec.md`
+- execution planning has not started yet
+- the runtime is forming or verifying the requirement contract
+- builder and QA must not run
+
+### 3.1.2 Transition Rules
+
+- feature creation starts in `intake`
+- `intake -> planning` only when a verified manifest exists
+- `awaiting_input -> intake` resumes if intake questions were answered
+- `planning -> intake` is forbidden unless a future explicit re-intake flow is added
+
+---
+
+## 4. Artifact Model
+
+## 4.1 Bootstrap Proposal Artifact
+
+Location:
+
+- `.aop/features/<feature_id>/spec.manifest.bootstrap.json`
+
+Purpose:
+
+- infer candidate obligations from raw `spec.md`
+- non-authoritative
+- used by intake planner as input
+
+## 4.2 Verified Manifest Artifact
+
+Location:
+
+- `.aop/features/<feature_id>/spec.manifest.verified.json`
+
+Purpose:
+
+- authoritative obligation contract
+- required before `planning`
+- used by:
+  - execution planner
+  - builder
+  - QA
+  - post-QA reconciliation
+
+## 4.3 Intake Review Artifact
+
+Location:
+
+- `.aop/features/<feature_id>/intake.review.json`
+
+Purpose:
+
+- record intake decisions and unresolved ambiguity
+
+Suggested shape:
+
+```json
+{
+  "feature_id": "example_feature",
+  "version": 1,
+  "status": "proposed",
+  "questions_open": 1,
+  "questions_resolved": 2,
+  "ambiguities": [
+    {
+      "id": "AMB-001",
+      "summary": "Unclear whether merge queue view is required for all phases or only non-merged phases",
+      "status": "open"
+    }
+  ],
+  "promotion_basis": null
+}
+```
+
+## 4.4 Plan Artifact Dependency
+
+`plan.json` may not be accepted unless:
+
+- a verified manifest exists
+- `plan_trace` references obligation IDs from that verified manifest
+
+---
+
+## 5. Intake Phase Flow
+
+## 5.1 End-to-End Flow
+
+1. user provides `spec.md`
+2. feature is created in `intake`
+3. system generates `spec.manifest.bootstrap.json`
+4. intake planner reviews:
+   - raw `spec.md`
+   - bootstrap manifest
+   - existing intake review artifact, if any
+5. intake planner decides:
+   - manifest is good enough to verify
+   - manifest needs targeted human clarification
+   - manifest needs revision without human clarification
+6. if questions are needed:
+   - planner emits targeted intake questions
+   - feature enters `awaiting_input` with `resume_status=intake`
+7. once questions are answered:
+   - intake planner updates proposal
+   - system promotes to verified manifest when criteria are met
+8. feature transitions `intake -> planning`
+9. execution planner produces `plan.json`
+
+## 5.2 Intake Planner Responsibilities
+
+During intake, planner must:
+
+- inspect the bootstrap manifest proposal
+- identify missing, conflicting, or ambiguous obligations
+- ask only requirement-forming questions
+- submit a verified-manifest proposal or revised bootstrap guidance
+- avoid execution-level planning until the manifest is verified
+
+## 5.3 What Intake Questions Look Like
+
+Examples:
+
+- “Is `MergeQueueCard` required for all non-merged phases or only `ready_to_merge`?”
+- “Should obligation `OBL-004` be treated as in-scope for this feature or deferred to a follow-on track?”
+- “Is the requirement to expose `/api/merge-queue` mandatory or optional if queue length is 1?”
+
+Bad intake questions:
+
+- “How should I implement this?”
+- “What React hooks should I use?”
+- “Do you want me to write tests?”
+
+Those belong to planning/build/QA, not intake.
+
+---
+
+## 6. System Ownership and Runtime Responsibilities
+
+## 6.1 No New Long-Lived Agent Type Required
+
+This feature does not require a new persistent `PromptIntakeAgent`.
+
+Default architecture:
+
+- reuse planner role
+- add an explicit intake subphase / prompt bundle
+- keep intake runtime system-owned
+
+That means the planner role has two modes:
+
+- `planner:intake`
+- `planner:execution`
+
+## 6.2 Runtime Ownership
+
+The runtime must explicitly own:
+
+- feature creation in `intake`
+- bootstrap manifest generation
+- intake context assembly
+- question creation and answer routing
+- verified-manifest promotion
+- transition to `planning` only after verification
+
+## 6.3 Preferred Invocation Points
+
+1. feature initialization
+2. first planner context load for an `intake` feature
+3. answer-resume flow for intake questions
+
+Builder and QA executors must skip features in:
+
+- `intake`
+- `awaiting_input` where `resume_status=intake`
+
+---
+
+## 7. Contracts and Tools
+
+## 7.1 New Planner Output Type
+
+Add planner output type:
+
+- `INTAKE_SUBMISSION`
+
+Example:
+
+```json
+{
+  "type": "INTAKE_SUBMISSION",
+  "intake_submission": {
+    "verified_manifest": {
+      "feature_id": "example_feature",
+      "manifest_version": 1,
+      "artifact_type": "verified",
+      "verification_basis": "questions_resolved",
+      "obligations": []
+    },
+    "open_ambiguities": [],
+    "resolved_ambiguities": [],
+    "requires_user_input": false
+  }
+}
+```
+
+## 7.2 Alternative Planner Request Path
+
+The intake planner may also emit:
+
+```json
+{
+  "type": "REQUEST",
+  "request": {
+    "action": "ask_user_input",
+    "blocking": true,
+    "prompt": "Clarify whether OBL-004 is required in this feature or deferred.",
+    "details": {
+      "ambiguity_id": "AMB-004",
+      "obligation_id": "OBL-004"
+    }
+  }
+}
+```
+
+This must use the existing question protocol.
+
+No new generic request action is introduced here. M59 reuses the M43 `ask_user_input` contract exactly.
+
+## 7.3 Tool Surface
+
+Add or extend tools:
+
+- `feature.intake_get`
+  - read bootstrap manifest, verified manifest, intake review state, ambiguity summary
+- `feature.intake_submit`
+  - persist verified manifest and intake review result
+- existing:
+  - `feature.question_create`
+  - `feature.question_answer`
+  - `feature.get_context`
+
+If the team prefers not to add new explicit tools, `feature.get_context` and planner output parsing may be extended instead. But the intake artifact persistence boundary must still be explicit.
+
+## 7.4 Intake Question Readiness Contract
+
+M43 owns the generic ready-state contract for persisted questions.
+
+M59 adds one intake-specific predicate:
+
+```text
+intake_question_ready =
+  generic_question_ready_from_M43
+  AND question.resume_status == intake
+```
+
+Only after that predicate holds may the UI and CLI treat the question as actionable intake work.
+
+### 7.4.1 Non-Ready States
+
+The following do **not** count as “ready with a question”:
+
+- planner mentioned uncertainty in a NOTE
+- planner emitted malformed or invalid question output
+- planner emitted a REQUEST but tool execution failed
+- question persistence failed
+- feature did not transition to `awaiting_input`
+
+In those cases:
+
+- the question must not appear in dashboard or CLI question lists
+- the runtime should log a planner/runtime error instead
+
+### 7.4.2 Ready-State Source of Truth
+
+Operator-visible intake readiness is still determined from persisted artifacts and feature state, never from transient model output.
+
+For intake, the distinguishing persisted predicate is:
+
+```text
+question.resume_status == intake
+```
+
+This ensures frontend and CLI remain consistent even if the planner runtime disconnects after asking the question.
+
+## 7.5 API Payload Contracts
+
+This feature must define the exact payload additions the UI consumes for intake interactions.
+
+### 7.5.1 `FeatureQuestion` Intake Extensions
+
+Existing question payloads must be extended, not replaced.
+
+Add optional fields:
+
+```ts
+interface FeatureQuestion {
+  ambiguity_id?: string | null;
+  obligation_ids?: string[];
+  intake_context?: {
+    intake_status: 'in_progress' | 'awaiting_input' | 'verified';
+    bootstrap_manifest_version: number | null;
+    verified_manifest_version: number | null;
+    promotion_basis: string | null;
+  } | null;
+}
+```
+
+Normative behavior:
+
+- these fields are present for intake-originated planner questions
+- they may be absent for builder/QA questions
+
+### 7.5.2 `FeatureSummary` Intake Extensions
+
+M43 already owns the baseline human-input summary fields such as:
+
+- `open_question_count`
+- `awaiting_since`
+- `requested_by_role`
+- `resume_status`
+
+M59 adds only the intake-specific summary surface needed to classify intake blockers without opening the feature.
+
+Add or guarantee:
+
+```ts
+interface FeatureSummary {
+  status: string;
+  phase?:
+    | 'intake'
+    | 'planning'
+    | 'building'
+    | 'qa'
+    | 'ready_to_merge'
+    | 'merged'
+    | 'blocked'
+    | 'awaiting_input'
+    | 'unknown';
+  open_question_count?: number;
+  awaiting_since?: string | null;
+  requested_by_role?: string | null;
+  resume_status?: string | null;
+  intake_status?: 'not_started' | 'in_progress' | 'awaiting_input' | 'verified' | null;
+  bootstrap_manifest_version?: number | null;
+  verified_manifest_version?: number | null;
+}
+```
+
+### 7.5.3 `FeatureTriageDetail` Intake Extensions
+
+The triage drawer must receive explicit intake detail, not infer it from generic questions alone.
+
+Extend payload:
+
+```ts
+interface FeatureTriageDetail {
+  open_questions?: FeatureQuestion[];
+  intake?: {
+    status: 'not_started' | 'in_progress' | 'awaiting_input' | 'verified';
+    bootstrap_manifest_version: number | null;
+    verified_manifest_version: number | null;
+    open_ambiguity_count: number;
+    promotion_basis: string | null;
+  } | null;
+}
+```
+
+### 7.5.4 Dashboard Root Status Payload
+
+`DashboardStatusPayload.pending_questions.items` must include intake questions with the same extended `FeatureQuestion` shape, including:
+
+- `phase = intake`
+- `resume_status = intake`
+- `ambiguity_id` when present
+- `obligation_ids` when present
+
+### 7.5.5 Feature-Level Questions Route
+
+M43 owns the existence and baseline behavior of `GET /api/features/[id]/questions`.
+
+For intake questions specifically, the route must include:
+
+- role = `planner`
+- phase = `intake`
+- intake context metadata
+- ambiguity/obligation references if present
+
+### 7.5.6 Question Answer Route
+
+M43 owns the baseline answer route and its use of `feature.question_answer`.
+
+M59 requires the same route to support intake answers and return enough resume data for intake-aware UI.
+
+`POST /api/features/[id]/questions/[questionId]/answer` must accept:
+
+```ts
+interface IntakeAnswerRequest {
+  answer: string | Record<string, unknown>;
+  answered_by?: string;
+}
+```
+
+And return enough information for the UI to update deterministically:
+
+```ts
+interface IntakeAnswerResponse {
+  ok: boolean;
+  data?: {
+    feature_id: string;
+    question_id: string;
+    question_status: 'answered';
+    feature_status: string;
+    resume_status: string | null;
+    resumed: boolean;
+  };
+  error?: {
+    message: string;
+  };
+}
+```
+
+The frontend should treat `resumed=true` as the signal that the feature has been queued back into intake execution.
+
+If the M43 baseline answer response does not yet expose `resume_status`, M59 extends that payload; it does not create a parallel answer route.
+
+### 7.5.7 Focus View Detail Payload
+
+Feature-focus data loaders should include:
+
+- `questions: FeatureQuestion[]`
+- `intake_review` summary:
+
+```ts
+interface IntakeReviewSummary {
+  status: 'proposed' | 'awaiting_input' | 'verified';
+  open_ambiguity_count: number;
+  resolved_ambiguity_count: number;
+  bootstrap_manifest_version: number | null;
+  verified_manifest_version: number | null;
+  promotion_basis: string | null;
+}
+```
+
+This prevents the focus view from having to reconstruct intake state from multiple low-level artifacts.
+
+---
+
+## 8. Verified Manifest Promotion
+
+## 8.1 Promotion Rule
+
+A bootstrap proposal may become a verified manifest only when:
+
+- no blocking ambiguities remain
+- any required user clarifications are answered
+- manifest shape is schema-valid
+- policy allows verification under the current confidence / review basis
+
+## 8.2 Promotion Bases
+
+Allowed `verification_basis` values:
+
+- `structured_spec`
+- `questions_resolved`
+- `policy_approved_auto_promotion`
+- `human_review_confirmed`
+
+## 8.3 Enforcement Rule
+
+Only `spec.manifest.verified.json` may be used for:
+
+- blocking plan admission
+- enforced `plan_trace` validation
+- enforced builder/QA/reconciliation audit
+
+Bootstrap manifests remain advisory only.
+
+---
+
+## 9. Execution Planning After Intake
+
+## 9.1 Transition to Planning
+
+Once verified manifest exists:
+
+- feature transitions `intake -> planning`
+- planner switches from intake mode to execution mode
+- planner creates `plan.json` with `plan_trace`
+
+## 9.2 Planning Inputs
+
+Execution planner must receive:
+
+- `spec.md`
+- verified manifest
+- intake review summary
+- resolved user answers from intake
+
+The execution planner should not need to reinterpret raw spec ambiguity that was already resolved during intake.
+
+## 9.3 Later Reconciliation
+
+Future planner reconciliation phases must compare against:
+
+- verified manifest
+- accepted `plan_trace`
+- implementation/verification evidence
+
+They must not reopen intake-level ambiguity unless a future explicit re-intake workflow exists.
+
+---
+
+## 10. Operator UX: Dashboard, Focus View, and CLI
+
+This feature must explicitly define how intake questions and verified-manifest state appear to operators.
+
+The operator should not need to infer intake state from logs.
+
+## 10.1 Board / Dashboard Expectations
+
+### 10.1.1 Status and Queueing
+
+When intake planner opens a blocking clarification question:
+
+- feature status becomes `awaiting_input`
+- `resume_status` is `intake`
+- the feature must appear in the existing **Needs Me** queue
+
+This aligns with the current dashboard behavior that already derives `Needs Me` from waiting-input signals and open question count.
+
+Normative behavior:
+
+- `intake` with no blocking question:
+  - feature appears as an active in-progress item, not `Needs Me`
+- `awaiting_input` during intake:
+  - feature appears in `Needs Me`
+  - client status label should render `Awaiting Input`
+- root dashboard pending-questions panel must include intake questions
+
+### 10.1.2 Needs Me Card
+
+The **Needs Me** queue should remain the top-level operator signal for features awaiting intake clarification.
+
+Clicking a feature in **Needs Me** must:
+
+- select the feature
+- open the triage drawer on the board
+- offer a direct link into the feature focus view
+
+### 10.1.3 Root Pending Questions Section
+
+The existing root “Pending Questions” section should include intake questions with enough context to route the operator:
+
+- feature ID
+- role = `planner`
+- phase = `intake`
+- prompt text
+
+Selecting an item should focus the feature and open its triage/focus surfaces.
+
+## 10.2 Triage Drawer Expectations
+
+The triage drawer must become a first-class intake response surface, not only a passive open-question list.
+
+### 10.2.1 Intake Question Presentation
+
+When a selected feature has an open intake question:
+
+- the triage drawer must show:
+  - question prompt
+  - planner role / intake phase
+  - expected answer choices or schema hints
+  - resume target = `intake`
+
+### 10.2.2 Response Entry
+
+The operator should be able to answer the question directly in the triage drawer.
+
+This means the current open-question display must be extended with:
+
+- choice buttons when `expected_answer.choices` exist
+- a text area or structured-response field
+- a submit action that posts the answer
+
+The generic “Send Message” box is not sufficient for closing blocking intake questions. The intake answer path must call `feature.question_answer`, not `feature.send_message`.
+
+### 10.2.3 Post-Answer Behavior
+
+After successful answer submission from the triage drawer:
+
+- show toast: “Answer sent. Feature queued to resume intake.”
+- refresh the selected feature
+- remove the blocking question from the open-question section
+- if no other blockers remain, feature should leave `Needs Me` on next refresh
+
+## 10.3 Focus View Expectations
+
+The feature focus view must be the deep-detail surface for intake interactions.
+
+### 10.3.1 Human Input Panel
+
+The existing `HumanInputPanel` should be reused and extended for intake questions.
+
+When the feature is in `awaiting_input` with `resume_status=intake`, the focus view should display:
+
+- banner: `Awaiting your input`
+- planner role and `intake` phase
+- prompt text
+- details / ambiguity metadata
+- expected answer choices or schema hints
+- resume target: `intake`
+
+### 10.3.2 Intake Context
+
+For intake-specific questions, the focus view should additionally surface:
+
+- ambiguity ID
+- affected obligation IDs, if known
+- bootstrap manifest summary
+- verification basis status:
+  - `bootstrap only`
+  - `questions resolved`
+  - `verified`
+
+This gives the operator enough context to answer without reading raw artifacts.
+
+### 10.3.3 Recommended Tab Placement
+
+Intake-response UI should appear in the focus view’s review-oriented area, with the current `HumanInputPanel` as the base surface.
+
+If a dedicated intake tab is not added in M59, then:
+
+- the panel must be visible on the feature overview/review surface when open intake questions exist
+
+## 10.4 Frontend Request / Response Wiring
+
+M43 owns the generic agent-to-runtime-to-frontend question transport.
+
+This section defines only the intake-specific mapping onto those existing seams.
+
+### 10.4.1 From Agent to Frontend
+
+Flow:
+
+1. intake planner emits `REQUEST.action=ask_user_input`
+2. runtime routes to `feature.question_create`
+3. `QuestionService` persists the question and sets status to `awaiting_input`
+4. dashboard data loaders read question artifacts and human-input state
+5. board, triage drawer, and focus view render the open question
+
+Current frontend seams that should be reused:
+
+- root pending-questions data
+- triage drawer `open_questions`
+- feature-level questions route
+- focus-view `questions` payload
+
+Readiness rule for all frontend surfaces:
+
+- render an intake question as actionable only if it satisfies the persisted ready-state contract from §7.4
+- otherwise render nothing and wait for refreshed persisted state
+
+### 10.4.2 From Frontend to Runtime
+
+Flow:
+
+1. operator enters answer in triage drawer or focus view
+2. frontend posts to question-answer API route
+3. route calls control-plane question-answer tool path
+4. runtime closes the question and resumes the feature into `intake`
+
+Normative rule:
+
+- blocking intake answers must go through `feature.question_answer`
+- they must not be implemented as free-form `feature.send_message`
+
+### 10.4.3 Required Frontend Routes
+
+The UI integration should reuse or extend existing routes such as:
+
+- `GET /api/features/[id]/triage`
+- `GET /api/features/[id]/questions`
+- `POST /api/features/[id]/questions/[questionId]/answer`
+- root dashboard pending-questions summary route/data path
+
+If additional intake metadata is needed, extend these payloads instead of inventing parallel one-off transport.
+
+### 10.4.4 Message vs Answer Path
+
+This feature must distinguish two operator actions clearly:
+
+- **answer question**
+  - closes a blocking intake question
+  - uses `feature.question_answer`
+- **send message**
+  - non-blocking contextual message to a worker
+  - uses `feature.send_message`
+
+The UI must not multiplex these into one ambiguous control.
+
+If an open blocking intake question exists:
+
+- the primary action in triage/focus surfaces must be **Answer Question**
+- `Send Message` may remain available, but it must not imply closure of the blocker
+
+## 10.5 CLI Relationship
+
+The CLI remains a first-class operator path alongside the dashboard, but M59 assumes the shared M43 CLI question workflow rather than redefining it.
+
+### 10.5.1 Status Visibility
+
+`aop status` must surface:
+
+- feature status = `awaiting_input`
+- resume target = `intake`
+- open intake question count
+- short prompt summary
+
+### 10.5.2 Explicit Question Commands
+
+The shared question workflow should remain valid:
+
+- `aop questions`
+- `aop answer`
+
+For intake questions, CLI output must clearly show:
+
+- role = `planner`
+- phase = `intake`
+- ambiguity or obligation reference if present
+
+### 10.5.3 CLI / Dashboard Parity
+
+Dashboard answer flow and CLI answer flow must both terminate in the same backend call:
+
+- `feature.question_answer`
+
+The dashboard is not a special side channel. It is a UI wrapper over the same question protocol as the CLI.
+
+## 10.6 How the Operator Knows a Response Is Required
+
+M43 owns the generic visible-question rule. M59 defines the intake-specific classification of those visible questions.
+
+An intake question requiring response is considered visible when all of the following are true:
+
+- feature status = `awaiting_input`
+- `human_input.open_question_count > 0`
+- an open question exists with `resume_status=intake`
+- the open question satisfies the ready-state contract in §7.4
+
+The operator should see at least one of:
+
+- **Needs Me** queue entry
+- root pending-questions panel
+- triage drawer open-question section
+- focus-view `HumanInputPanel`
+- CLI `aop status` / `aop questions`
+
+This redundancy is intentional.
+
+---
+
+## 11. Policy Additions
+
+Add policy section:
+
+```yaml
+planning:
+  intake:
+    enabled: true
+    require_verified_manifest_before_planning: true
+    allow_auto_promotion: false
+    auto_promotion_min_confidence: high
+    max_intake_question_rounds: 2
+    on_unresolved_ambiguity: awaiting_input # awaiting_input | blocked | fail_feature
+```
+
+Normative behavior:
+
+- default should favor safety over silent assumption
+- if intake cannot verify the manifest, execution planning should not start
+
+---
+
+## 12. State Schema Changes
+
+Add new state enum:
+
+- `intake`
+
+Add frontmatter section:
+
+```yaml
+intake:
+  status: not_started | in_progress | awaiting_input | verified
+  bootstrap_manifest_version: integer | null
+  verified_manifest_version: integer | null
+  open_ambiguity_count: integer
+  last_verified_at: date-time | null
+```
+
+Rules:
+
+- `status=planning` requires `intake.status=verified`
+- `verified_manifest_version` must be non-null before `planning`
+
+---
+
+## 13. Implementation Plan
+
+M59 must not re-implement the generic M43 protocol. It layers intake-specific behavior on top of it.
+
+### M59.0 — Align to M43 baseline
+
+- treat M43 as the shared protocol authority
+- require `resume_status=intake` support in the M43 resumable-state contract
+- reuse existing question tools and answer routes rather than inventing parallel transport
+
+### M59.1 — Add `intake` lifecycle status
+
+Update:
+
+- `apps/control-plane/src/core/constants.ts`
+- `agentic/orchestrator/schemas/state.schema.json`
+- lifecycle/status consumers
+
+### M59.2 — Add intake artifacts and schemas
+
+Add:
+
+- schema for bootstrap manifest
+- schema for verified manifest
+- schema for `intake.review.json`
+
+### M59.3 — Add bootstrap manifest generation
+
+Create:
+
+- system-owned bootstrap generation service
+
+This service produces `spec.manifest.bootstrap.json` only.
+
+### M59.4 — Add intake planner mode
+
+Update:
+
+- planner prompt bundle(s)
+- worker decision loop output parsing for `INTAKE_SUBMISSION`
+
+### M59.5 — Add intake persistence and promotion
+
+Create/update:
+
+- intake service
+- verified manifest promotion logic
+- transition from `intake -> planning`
+
+### M59.6 — Integrate question protocol
+
+Update:
+
+- question creation/answer routing so intake questions resume back into `intake`
+- reuse M43 ready-state and answer transport, adding intake-only predicates and payload extensions where needed
+
+### M59.7 — Dashboard and focus-view intake UX
+
+Update:
+
+- board/root pending-questions rendering
+- triage drawer open-question response controls
+- focus-view `HumanInputPanel` intake context and resume target handling
+- any frontend types/routes needed to expose intake metadata
+
+### M59.8 — Execution planner gating
+
+Update:
+
+- `PlanService`
+- planning wave executor
+
+So execution planning is blocked until verified manifest exists.
+
+### M59.9 — CLI and reconciliation alignment
+
+Update:
+
+- shared CLI status/question displays for intake context
+- post-QA reconciliation to use verified manifest only
+
+---
+
+## 14. Testing Plan
+
+## 13.1 Intake Flow Tests
+
+Add tests proving:
+
+- new features begin in `intake`
+- bootstrap manifest is generated before execution planning
+- planner cannot submit execution plan without verified manifest
+
+## 13.2 Question Loop Tests
+
+Add tests proving:
+
+- intake planner can open blocking questions
+- answering intake questions resumes into `intake`
+- verified manifest promotion occurs only after required answers are present
+- generic ready-state behavior remains covered by M43 tests; M59 adds only the `resume_status=intake` predicate and intake metadata checks
+
+## 13.2.1 Dashboard / Focus View Tests
+
+Add tests proving:
+
+- `awaiting_input` intake features appear in **Needs Me**
+- triage drawer renders intake question context and answer controls
+- focus-view `HumanInputPanel` renders planner/intake context and resume target
+- dashboard answer submission calls the question-answer route and refreshes state
+- transient planner REQUEST output without persisted question record does not render as operator-visible work
+- answer route returns resumed state payload that the UI can use deterministically
+
+## 13.3 Planning Transition Tests
+
+Add tests proving:
+
+- `intake -> planning` occurs only after verified manifest exists
+- builder/QA do not run while feature is in `intake`
+- execution planner receives verified manifest context
+
+## 13.4 Reconciliation Tests
+
+Add tests proving:
+
+- post-QA reconciliation audits against verified manifest
+- raw `spec.md` is not reinterpreted as the primary contract once intake is complete
+
+## 13.5 Cross-Platform Fixtures
+
+Add intake fixtures for:
+
+- TypeScript/UI spec
+- Python service spec
+- Java/backend spec
+- CLI/config spec
+
+Each should exercise:
+
+- bootstrap proposal
+- ambiguity detection
+- manifest verification
+- transition into planning
+
+---
+
+## 15. Risks and Mitigations
+
+| Risk                                                       | Impact | Mitigation                                                                                     |
+| ---------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
+| Intake adds latency before planning starts                 | Medium | Keep questions narrow and only ask when ambiguity blocks contract formation.                   |
+| Teams perceive intake as “extra bureaucracy”               | Medium | Allow auto-promotion when confidence and policy permit; otherwise ask only blocking questions. |
+| Planner prompt overload between intake and execution modes | Medium | Separate planner prompt bundles or explicit mode-specific instructions.                        |
+| Legacy specs still have low-quality bootstrap manifests    | High   | Keep bootstrap advisory until verified; never treat raw extraction as enforceable truth.       |
+| Re-intake may be needed after major scope change           | Medium | Explicitly defer re-intake flow to future spec rather than allowing silent reopen.             |
+| Dashboard and CLI drift in question handling               | Medium | Force both surfaces through `feature.question_answer` and shared question payloads.            |
+
+---
+
+## 16. Acceptance Criteria
+
+This feature is complete when all of the following are true:
+
+1. New features begin in `intake`, not `planning`.
+2. The system generates a bootstrap manifest proposal from `spec.md` before execution planning starts.
+3. The planner has an intake mode that can:
+   - review the bootstrap proposal
+   - ask targeted requirement-forming questions
+   - submit a verified manifest
+4. Builder and QA never run before a verified manifest exists.
+5. Execution planning cannot begin until the feature transitions `intake -> planning`.
+6. Intake questions use the existing M43 question protocol and resume into `intake`.
+7. Dashboard UX explicitly supports intake questions through:
+   - **Needs Me**
+   - root pending-questions panel
+   - triage drawer answer controls
+   - focus-view `HumanInputPanel`
+8. CLI and dashboard answer flows both terminate in the shared `feature.question_answer` path; M59 does not introduce a parallel intake-only answer channel.
+9. `plan.json` and later reconciliation evaluate against the verified manifest, not raw ambiguous spec prose.
+10. Cross-platform fixtures prove the intake-to-planning model works for at least TypeScript, Python, and Java style specs.
+11. The spec does not duplicate or redefine generic question lifecycle rules already owned by M43.
+12. `npm run typecheck`, `npm run lint`, and relevant Vitest suites pass.
+
+---
+
+## 17. Explicit Non-Requirements
+
+This spec does not require:
+
+- a general-purpose conversational PM agent
+- indefinite back-and-forth with the user
+- platform-specific semantic analysis
+- replacing the existing human-input protocol
+
+The purpose is narrower:
+
+- form a verified requirements contract first
+- then execute deterministically against that contract