agentic-orchestrator 0.1.27 → 0.2.0

package/spec-files/outstanding/agentic_orchestrator_focus_plan_tab_execution_contract_workspace_spec.md

@@ -0,0 +1,616 @@
+# Feature Spec: Focus Plan Tab Execution-Contract Workspace
+
+> Purpose: Redesign the Focus-page `Plan` tab so it complements `Intake` instead of repeating it. The `Plan` tab must become the operator workspace for execution strategy, plan quality, verification intent, blast radius, and plan-change decisions.
+
+**Version:** 0.1
+**Date:** 2026-03-18
+**Status:** Proposed
+**Roadmap Mapping:** M46-D (Focus Plan Workspace Refinement)
+**Depends On:**
+
+- `spec-files/completed/agentic_orchestrator_focus_plan_tab_intake_planning_workspace_spec.md`
+- `spec-files/outstanding/agentic_orchestrator_interactive_planning_intake_and_requirements_verification_spec.md`
+
+---
+
+## 0. Executive Summary
+
+The Focus page now correctly separates `Intake` and `Plan` into two tabs, but the current `Plan` tab still behaves too much like a second planner-status screen.
+
+Today it over-emphasizes:
+
+- intake provenance
+- manifest freshness metadata
+- trace counters
+- raw task lists
+- artifact browsing
+
+Those are not useless, but they are not the main operator job once `Plan` is distinct from `Intake`.
+
+The `Intake` tab should answer:
+
+1. What does the feature need to do?
+2. What is still ambiguous?
+3. Why is the verified requirements contract trustworthy?
+
+The `Plan` tab should answer different questions:
+
+1. Can execution proceed safely against the current plan?
+2. What is the intended delivery strategy?
+3. What is the critical path?
+4. How will completion be proven?
+5. What plan defects or risks still require intervention?
+
+This spec redefines the `Plan` tab as an **execution-contract workspace** rather than a planner artifact browser.
+
+---
+
+## 1. Context
+
+The completed Intake/Planning split solved the first information-architecture problem:
+
+- `Intake` owns requirement formation
+- `Plan` owns accepted-plan detail
+
+However, the current `Plan` tab still carries over too much of the planner-centric mental model from the first implementation pass.
+
+Current implementation symptoms:
+
+- `Intake Handoff` is still a top-level card, even though promotion basis and ambiguity counts are intake-owned concerns
+- `Plan Contract Health` and `Plan Trace Coverage` rely on internal counters instead of decision-ready summaries
+- `Current Planning Focus` exposes planner-state phrasing rather than operator actions
+- `Accepted Execution Plan` still reads like a rendered `plan.json` summary rather than an operational contract
+- raw artifacts still compete visually with the actual execution plan story
+
+The tab therefore feels like “planner telemetry after intake” instead of “how this feature will actually be delivered.”
+
+---
+
+## 2. Problem Statement
+
+The current `Plan` tab overlaps with `Intake` and under-serves execution decisions.
+
+### 2.1 Current UX failures
+
+- The top of the `Plan` tab still spends too much space re-explaining intake provenance.
+- The tab does not surface the execution strategy clearly enough for a human to evaluate it.
+- The tab shows counts and versions where it should show blockers, decisions, and consequences.
+- `Plan Trace Coverage` is too implementation-centric; operators care about missing commitments, not only totals.
+- The accepted-plan presentation is too artifact-led and not organized around workstreams, critical path, or delivery slices.
+- The tab does not clearly separate “plan exists” from “plan is trustworthy and actionable.”
+- Verification intent is buried; the operator cannot easily tell how the plan expects success to be proven.
+- Scope is too abstract; a file count is not a usable blast-radius assessment.
+- The tab does not explain how the plan changed over time in meaningful human language.
+
+### 2.2 Consequence
+
+Operators still cannot answer quickly:
+
+- Is the plan executable right now?
+- What exactly is the current delivery strategy?
+- Which obligations or tasks are still weak, unowned, stale, or under-verified?
+- Which part of the plan is most likely to cause execution or merge trouble?
+- What changed in the plan, and why did it change?
+
+---
+
+## 3. Scope and Supersession
+
+This spec refines the meaning of the `Plan` tab after the Intake/Plan split.
+
+It supersedes the `Plan`-tab section of:
+
+- `spec-files/completed/agentic_orchestrator_focus_plan_tab_intake_planning_workspace_spec.md` section `6.4`
+
+Normative rule:
+
+- `Intake` remains the workspace for requirement validation and question resolution.
+- `Plan` remains a distinct tab and must not be removed or hidden during intake.
+- `Plan` must no longer behave like a second intake summary.
+- `Plan` must become complementary to `Intake`, not parallel to it.
+
+This spec does not redesign:
+
+- `Overview`
+- `Runtime`
+- `History`
+- `Gates & QA`
+- kernel lifecycle semantics
+
+---
+
+## 4. Product Definition
+
+The `Plan` tab is the **execution-contract workspace**.
+
+Its job is to help an operator or reviewer decide whether the accepted plan is:
+
+- actionable
+- coherent
+- sufficiently verified in intent
+- properly scoped
+- safe to drive execution
+
+### 4.1 `Intake` versus `Plan`
+
+`Intake` owns:
+
+- source spec meaning
+- ambiguities
+- open questions
+- bootstrap-to-verified contract formation
+- promotion readiness
+
+`Plan` owns:
+
+- execution structure
+- critical path
+- workstream ownership
+- planned verification strategy
+- blast radius
+- unresolved plan defects
+- evolution of the accepted execution contract
+
+### 4.2 User questions the `Plan` tab must answer
+
+Within 10 seconds, the top half of the tab must answer:
+
+1. Is the current plan executable right now?
+2. What is the highest-priority plan defect or blocker?
+3. What is the current critical path?
+4. What proof is expected before the feature can be considered done?
+5. What changed most recently in the plan?
+
+---
+
+## 5. Information Architecture
+
+The `Plan` tab should keep the shared `PlannerLifecycleHeader`, but the rest of the tab must be reorganized around decision-making.
+
+### 5.1 Required sections
+
+The `Plan` tab must contain these sections, in this order:
+
+1. `Plan Readiness`
+2. `Delivery Strategy`
+3. `Critical Path`
+4. `Verification Strategy`
+5. `Scope & Blast Radius`
+6. `Plan Gaps Requiring Decision`
+7. `Plan Evolution`
+8. `Plan Artifacts`
+
+### 5.2 Sections that must be reduced or demoted
+
+These may exist only as compact provenance metadata, not as dominant cards:
+
+- promotion basis
+- last verified timestamp
+- open ambiguities at handoff
+- verified-manifest version counts
+- raw mapped / unmapped / deferred obligation counters without consequences
+- raw task list as the primary plan display
+
+---
+
+## 6. Detailed Section Requirements
+
+## 6.1 Plan Readiness
+
+This section replaces the current generic planning-summary emphasis.
+
+It must answer:
+
+- `Executable`
+- `Blocked`
+- `Stale`
+- `Draft`
+
+The section must show:
+
+- accepted-plan version
+- readiness state
+- last accepted / last revised time
+- current owner
+- top blocker
+- one-sentence recommended next action
+
+The section must not merely say `accepted`, `stale`, or `blocked`; it must explain the consequence in operator language.
+
+Examples:
+
+- `Executable — execution can proceed against Plan v4`
+- `Blocked — planner is waiting on a missing verification commitment for 2 obligations`
+- `Stale — intake changed, and the accepted plan no longer matches the verified contract`
+
+## 6.2 Delivery Strategy
+
+This section is the core of the tab.
+
+It must present the plan as workstreams or delivery slices rather than a flat task dump.
+
+Each workstream should show:
+
+- title
+- status
+- owner
+- objective
+- key files or modules
+- upstream dependency
+- downstream impact
+
+Normative rule:
+
+- if the plan has explicit workstream grouping, use it
+- if the plan does not, derive grouped slices from tasks + file scope + owner boundaries and mark the grouping as derived
+
+This section should communicate:
+
+- how the feature will be delivered
+- how work is sequenced
+- where the risky concentration points are
+
+## 6.3 Critical Path
+
+This section must show only the work that materially gates progress.
+
+Required items:
+
+- current critical task
+- next unblocker
+- blocked tasks on the critical path
+- tasks with unresolved ownership or dependency problems
+
+This section must not show all tasks equally.
+
+If the plan has 20 tasks but only 3 matter for forward motion, only those 3 should dominate this section.
+
+## 6.4 Verification Strategy
+
+This is the most important complementary section to `Intake`.
+
+`Intake` explains what must be true.
+`Plan` must explain how the team intends to prove it.
+
+The section must map:
+
+- acceptance criterion or verified obligation
+- planned verification method
+- expected gate, test, or review proof
+- verification owner if known
+- missing verification intent
+
+Normative rule:
+
+- `Gates & QA` shows actual evidence
+- `Plan` shows intended proof strategy
+
+This section must make “missing verification intent” concrete, not just counted.
+
+## 6.5 Scope & Blast Radius
+
+This section replaces low-signal file counts with meaningful scope interpretation.
+
+It must show:
+
+- major modules affected
+- hotspot files or directories
+- config / schema / migration impact
+- collision-sensitive areas
+- dependency-sensitive areas
+
+It should answer:
+
+- how broad is this plan?
+- where is it dangerous?
+- what adjacent systems are likely to be touched?
+
+Normative rule:
+
+- a total file count alone is insufficient
+
+## 6.6 Plan Gaps Requiring Decision
+
+This section turns planner-internal weaknesses into operator-facing decisions.
+
+It must include:
+
+- stale manifest bindings
+- unmapped obligations
+- deferred obligations
+- out-of-scope obligations that may need review
+- missing verification intent
+- blocked tasks without a clear owner
+- risks without mitigation
+
+Each item must include:
+
+- what is wrong
+- why it matters
+- what the recommended action is
+
+This section should be a prioritized queue, not a wall of diagnostics.
+
+## 6.7 Plan Evolution
+
+This section must answer:
+
+- what changed in the plan?
+- why did it change?
+- what was the impact on scope, risk, or verification?
+
+It must not simply list:
+
+- version numbers
+- timestamps
+- `revision_of`
+- raw `revision_reason`
+
+Each revision entry should summarize:
+
+- the material delta
+- trigger source
+- affected workstreams or files
+- whether risk increased, decreased, or stayed flat
+
+## 6.8 Plan Artifacts
+
+Raw artifacts remain required for auditability:
+
+- `plan.md`
+- `plan.json`
+- verified manifest
+- optionally the latest prior accepted plan when useful for diffing
+
+But these must be secondary and collapsible.
+
+Artifacts are supporting evidence, not the main narrative.
+
+---
+
+## 7. Data Contract Changes
+
+The current `FeaturePlanningWorkspace` is not expressive enough for the required UI.
+
+### 7.1 Required additions
+
+```ts
+interface FeaturePlanningWorkspace {
+  readiness: {
+    state: 'executable' | 'blocked' | 'stale' | 'draft';
+    headline: string;
+    consequence: string;
+    next_action: string;
+    current_owner: 'planner' | 'builder' | 'qa' | 'operator' | 'system' | null;
+    last_plan_update_at: string | null;
+    top_blocker: {
+      id: string;
+      label: string;
+      reason: string;
+      severity: 'high' | 'medium' | 'low';
+    } | null;
+  };
+
+  workstreams: Array<{
+    id: string;
+    title: string;
+    objective: string;
+    status: 'pending' | 'in_progress' | 'blocked' | 'completed';
+    owner_role?: 'planner' | 'builder' | 'qa' | 'orchestrator' | null;
+    dependency?: string | null;
+    file_scope: string[];
+    derived: boolean;
+  }>;
+
+  critical_path: {
+    current: PlanProgressTaskSummary | null;
+    next_blocker: PlanProgressTaskSummary | null;
+    blocking_tasks: PlanProgressTaskSummary[];
+  };
+
+  verification_strategy: Array<{
+    obligation_id: string;
+    label: string;
+    disposition: 'in_scope' | 'deferred' | 'out_of_scope' | 'unmapped';
+    planned_verification: string[];
+    owner_role?: 'planner' | 'builder' | 'qa' | null;
+    gap_reason: string | null;
+  }>;
+
+  scope_hotspots: Array<{
+    path: string;
+    kind: 'module' | 'directory' | 'file' | 'config' | 'schema';
+    risk: 'high' | 'medium' | 'low';
+    reason: string;
+  }>;
+
+  decision_queue: Array<{
+    id: string;
+    kind:
+      | 'stale_binding'
+      | 'unmapped_obligation'
+      | 'missing_verification_intent'
+      | 'deferred_obligation'
+      | 'out_of_scope_obligation'
+      | 'blocked_task'
+      | 'unmitigated_risk';
+    headline: string;
+    reason: string;
+    recommended_action: string;
+    severity: 'high' | 'medium' | 'low';
+  }>;
+
+  revisions: Array<{
+    id: string;
+    timestamp: string | null;
+    summary: string;
+    trigger: 'intake_change' | 'qa_feedback' | 'review_feedback' | 'runtime_discovery' | 'manual';
+    impact: 'scope_up' | 'scope_down' | 'risk_up' | 'risk_down' | 'neutral';
+  }>;
+}
+```
+
+### 7.2 Fields that should remain but become secondary
+
+- `intake_handoff`
+- `freshness`
+- `trace_coverage`
+- `accepted_plan_summary`
+- `artifacts`
+
+These fields still matter, but they should support the new decision-first sections instead of driving the layout directly.
+
+---
+
+## 8. Derivation Rules
+
+## 8.1 Workstreams
+
+Preferred source:
+
+- explicit workstream or slice metadata in `plan.json`
+
+Fallback source:
+
+- group tasks by owner role + shared file area + dependency chain
+
+Fallback-derived workstreams must be labeled as derived.
+
+## 8.2 Verification strategy
+
+Derive from:
+
+- verified obligations
+- `plan_trace`
+- acceptance criteria
+- gate profile
+
+A missing `planned_verification` entry for an in-scope obligation is a first-class plan defect.
+
+## 8.3 Decision queue
+
+The queue must be prioritized by severity and operator consequence.
+
+At minimum, create queue items for:
+
+- stale accepted-plan binding
+- unmapped in-scope obligations
+- required obligations with no verification intent
+- blocked critical-path tasks
+- risks with no mitigation text
+
+## 8.4 Revision summaries
+
+If a semantic revision summary is not explicitly present, derive one from:
+
+- plan version diff
+- revision reason
+- changed task set
+- changed file scope
+- changed risk count
+
+The UI must never degrade to raw version metadata without at least a coarse human summary.
+
+---
+
+## 9. Component Changes
+
+### 9.1 `PlanningTab.tsx`
+
+This component must be restructured around the section order from section 5.
+
+### 9.2 `plan-viewer.tsx`
+
+This component should stop behaving like the main plan surface.
+
+It should either:
+
+- become the `Plan Artifacts` / raw-plan drawer
+- or be split into smaller components used by the new `Plan` tab sections
+
+### 9.3 New recommended components
+
+- `PlanReadinessCard`
+- `PlanWorkstreamsPanel`
+- `PlanCriticalPathPanel`
+- `VerificationStrategyPanel`
+- `PlanBlastRadiusCard`
+- `PlanDecisionQueue`
+- `PlanEvolutionTimeline`
+
+The exact filenames are not normative, but the responsibilities are.
+
+---
+
+## 10. Rollout Plan
+
+### Slice P1 — Reframe the tab around decisions
+
+- demote `Intake Handoff`
+- add `Plan Readiness`
+- rename or repurpose the current planning summary section
+
+### Slice P2 — Replace raw task emphasis with workstreams + critical path
+
+- introduce workstream grouping
+- introduce critical-path display
+- reduce flat task-list prominence
+
+### Slice P3 — Add verification strategy and decision queue
+
+- map obligations to intended proof
+- surface missing verification intent as operator decisions
+
+### Slice P4 — Add semantic plan evolution
+
+- replace raw revision metadata with a meaningful evolution timeline
+
+### Slice P5 — Move artifacts to a secondary audit layer
+
+- preserve raw `plan.md` / `plan.json`
+- keep artifacts collapsible and secondary
+
+---
+
+## 11. Testing Requirements
+
+Required coverage:
+
+- `Plan` tab shows a visible complementary structure during intake and post-intake states
+- `Plan Readiness` derives correct operator-facing states from stale, blocked, draft, and executable plans
+- workstream derivation works with both explicit and fallback grouping
+- `Verification Strategy` surfaces missing verification intent by obligation, not only by count
+- decision queue prioritizes high-severity plan defects first
+- evolution timeline renders semantic summaries instead of raw version metadata
+- artifact viewer remains available but does not dominate the initial render
+
+Tests should be added or updated in:
+
+- `packages/web-dashboard/test/components/planning-tab.spec.tsx`
+- `packages/web-dashboard/test/lib/planner-workspace.spec.ts`
+- any new component-level specs introduced by the redesign
+
+---
+
+## 12. Acceptance Criteria
+
+This spec is complete when all of the following are true:
+
+1. The `Plan` tab no longer reads like a second intake summary.
+2. An operator can determine in under 10 seconds whether the plan is executable, blocked, stale, or draft.
+3. The delivery strategy is presented as workstreams or slices, not just flat tasks.
+4. The critical path is explicit.
+5. Planned verification strategy is visible and distinct from actual QA evidence.
+6. Scope/blast radius is meaningful and not reduced to file counts.
+7. Unmapped obligations, missing verification intent, stale bindings, and blocked tasks appear as a decision queue with recommended actions.
+8. Plan changes over time are summarized semantically, not only as raw metadata.
+9. Raw artifacts remain available but are clearly secondary to the decision-first sections.
+
+---
+
+## 13. Explicit Non-Goals
+
+- This spec does not merge `Intake` and `Plan` back together.
+- This spec does not move open intake questions back into the `Plan` tab as a primary concern.
+- This spec does not replace `Gates & QA` with plan-level verification intent.
+- This spec does not require in-browser editing of `plan.md` or `plan.json`.