# 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`.
