Epic: consolidate the planning chain #12646

Refs #6917

Consolidates the planning chain: one stage order, one decision level per stage, one vocabulary, one view configuration on ADR 0075, one fallback chain, one chrome, live review pages, and presence-gated plugin offers. Sub-issues are the slices; this epic is never agent-ready.

Brief

TLDR

• One stage order in /session-flow:workflow: interview first, then design, plan, decompose, then the autonomous lanes; the quick-change on-ramp stays.
• Each stage decides one level: behaviour in the Brief, interfaces and contracts in design, files and symbols in the plan.
• One vocabulary: rung, tier, ladder, overlay, surface and contract each name one thing.
• One view configuration on ADR 0075's layers, one fallback chain, one shared chrome, live review pages with approval in the conversation.
• Presence-gated guidance: a one-line offer of the installed surfaces and planners, and fresh, consented optional-plugin installs.

Problem

• Gap: planning surfaces disagree. The workflow's stage list contradicts its own prose (plugins/session-flow/skills/workflow/SKILL.md:77-90); the interview, plan and brainstorm render views through different settings (surface vs the medium cascade); the medium setting still reads a file ADR 0075 retired (docs/contracts/rendered-views/README.md:802-804; ADR 0075:50, :128); one word names two things in the contract (rung :328 vs :806; tier :37 vs :822; surface :802); the interview pages do not use the shared chrome (prior explore EXPLORE-summary.md).
• Who / how many: the owner (human-in-the-loop stages) and every marketplace consumer of the planning plugins; count unknown.
• Frequency: every planning session.
• Trend: unknown.
• Cost: confusion at the human gate (round 1: owner could not tell view from medium); duplicated look and settings to maintain.
• Evidence: strong (file:line reads above, verified explore EXPLORE.md).

Intent

"The interview skill and the planning skill are very, very important. They're very important to the human-in-the-loop steps ... that stuff needs to be very, very, very, very good. Because everything else after that should be, for the most part, automated through our agent-ready or software factory kind of deal." (owner, 2026-11-02)

Goal

A person starting work meets one consistent planning chain: the interview runs first and calls research, exploration, prototypes or a PRD only when a question needs them; each later stage decides its own level and hands a markdown record to the next; every page those stages show looks and behaves the same, falls back visibly when a medium is unavailable, and keeps approval in the conversation; the user is told which surfaces, planners and optional plugins are available without being stopped to choose.

• Intent (why, in the user's words): "all of our plugins, planning, and all that stuff need to be consolidated ... I just want to make sure that we support all those things and then we gracefully degrade."
• Vision (where this heads): "interview first, then planning, and all of those different sequential steps"; plugins ship Artifacts as the default view; the owner's machines use local HTML, later Cloudflare-tunnel shareable pages.
• When goals conflict, prefer: none stated.

Work size

• Appetite: not assessed.
• Size: large: workflow, interview, design, plan, rendered-views contract, shared chrome, config resolver, publish gate, and a repository-wide vocabulary pass.
• Uncertainty: low on what (every decision answered); moderate on how (mechanisms deferred to design and plan).
• Split signals: separable slices per decision area (order, levels, vocabulary, config, fallback chain, chrome, live review, offers); one epic, Refs Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917.

Constraints

• Skills reference each other only by public contract (plugin namespace, skill name, public arguments), never internals (owner, 2026-11-02).
• Markdown is the record; HTML, Artifacts and tunnel pages are views (ADR 0025; Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917 C2).
• Plugins ship the Artifact view as the default where the Artifact tool exists; in this epic that covers brainstorm, design and plan views only; the owner's machines use local HTML via enableArtifact false (owner, 2026-11-02; scope Q32).
• No team rendered-views.yaml in org repos for now (Q31).
• html-plan may be copied, integrated or referenced as an optional dependency that degrades gracefully, never required; comments built into our chrome (owner, 2026-11-02, replacing Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917 Q2; prior Q13).
• The shipped Artifact default is verified in CI with posted evidence, not on the owner's machines (owner, prior Q14); out of scope (owner, 2026-11-02).
• Team standards: design-for-change (add a variant by addition, docs/standards/design-for-change.md:26), reference-dont-duplicate, simpler-code.
• Quality requirement: Performance: rendering or watching a page never blocks the conversation; no numeric target.
• Quality requirement: Reliability: every view lane falls back to the next reachable medium and says why, never a dead file path (docs/contracts/rendered-views/README.md:361-362).
• Quality requirement: Security: no new path off the machine; existing paths keep their controls: an Artifact view publishes only when the publish gate passes and otherwise falls back to a local file (docs/contracts/rendered-views/README.md:383-386); a hosted page also goes to the private host for a non-public repository or a page with a machine path or hostname, and is refused on a credential-shaped line (docs/contracts/rendered-views/README.md:452-460); the shared session keeps its own controls; page input is untrusted data.
• Quality requirement: Maintainability: each shared file has one canonical copy, drift-checked in CI (ADR 0019).
• Quality requirement: Usability: the accessibility floor holds: contrast pairings, focus visibility, color-scheme and reduced-motion behavior, keyboard reach (docs/contracts/rendered-views/README.md:727-729); the theme follows the system setting by default.
• Quality requirement: Scalability: does not apply (one user, one session per page).
• Quality requirement: Observability: each view lane states the medium used and the deciding fact.

Acceptance criteria

• AC1: /session-flow:workflow lists one stage order, interview first, and its list and prose agree (Q3).
• AC2: The interview, design and plan skills each state the level they decide: behaviour, interfaces and contracts, files and symbols (Q4).
• AC3: A search of the whole repository, excluding dated records (docs/adr/, docs/upstream/, CHANGELOG files) and the synced docs/standards/, finds none of these words used in their retired senses (each match is read in context): "rung", "default ladder", "overlay" in their old senses, "tier" for precedence, "surface" for a config file, "contract" for the Brief; the workflow stage reads "Interview" (Q5-Q12).
• AC4: medium resolves through ADR 0075 precedence (plugin default, userConfig, docs/conventions/rendered-views.yaml, docs/conventions/rendered-views.local.yaml); neither ~/.claude/rendered-views.md nor .claude/rendered-views*.md is read as a settings layer (Q14; ADR 0075:167-169). Amended 2026-11-03 (owner, see AC14): a retired file is not a settings layer, but its terminal or file value still keeps the view local.
• AC5: Setting medium never changes the interview's surface (Q15).
• AC6: The contract records brainstorm, design and plan views as a named Artifact exception (Q16). CI evidence of the Artifact default is out of scope (owner, 2026-11-02: "CI verification evidence should be out").
• AC7: The contract holds one fallback chain, ordered published Artifact, local file, terminal, with "hosted" read as Artifact except for PR digests (docs/contracts/rendered-views/README.md:366-368, :448-451); every view lane names the medium it used and the fact that decided it (Q17).
• AC8: Our interview pages and planning views (not a third-party plugin's own pages) use the one canonical chrome, with a system/light/dark toggle and the comment UI, and no team or user theme overrides (Q18, Q36).
• AC9: On a review page (a Claude-interactive view of a brainstorm, design or plan record), on the file and Artifact mediums, a choice redraws its example; a lock reaches the session and is written to the markdown record; approval is taken only from the conversation; a missed page event is picked up at the next message (Q19, Q33). If design finds no Artifact channel, an Artifact review page says so and review happens in the conversation; the terminal reviews in the conversation.
• AC10: A plugin is offered only if listed, not renamed, and last committed within 6 months, with its date shown when older than 3 months; it installs at user scope only after a yes and points to /reload-plugins; no offer appears in an unattended run (Q20, Q21, Q34).
• AC11: One epic exists, Refs Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917, slices as its sub-issues; the epic carries no agent-ready label (Q2, Q22).
• AC12: Between human-in-the-loop stages the workflow suggests a handoff only when context-guard warns (Q23).
• AC13: With the surface not set by the user and more than one surface, the shared session or an optional planner (a presence-gated planning plugin offered under AC10; html-plan today) available, the interview names the default and the alternatives in one line and proceeds; an installed html-plan is named as an alternative and is never required (Q25, Q35).
• AC14: A view lane that finds a retired rendered-views file (~/.claude/rendered-views.md, .claude/rendered-views.md or .claude/rendered-views.local.md) reads it only to name its value and where to move it (plugin userConfig for the user file, the matching docs/conventions file for a repo file), once per view-lane plugin per project (Q29, Q50 reconfirmed at planning, owner 2026-11-02), never applies the value, and names a team value that selects a publishing medium as ignored (Q29, Q50). Amended 2026-11-03 (owner, in session, verbatim: "Go with recommended, but those docs cloud locations, all that, should be targeting or the normative state should be going to docs/convention/whatever."): a retired file's terminal or file value keeps the view local; a publishing value there stays ignored; the move notice names docs/conventions as the destination (docs/conventions/rendered-views.local.yaml first for the user file, the plugin userConfig as the per-user alternative). Reason: a security finding on refactor(adhd): resolve the clarify view medium through the shared resolver #12966 showed that ignoring a local value could publish an Artifact for a user who had set output to stay local.
• AC15: Adding a medium, a surface or a shared-session variant touches its own registration and renderer, with no edit to the skills that use it (Q24).

Captured assumptions

• Quality bar: production
• Variation intent: second variant = known; existing structure: four mediums (terminal, file, artifact, hosted) through the cascade and default ladder, two surfaces (terminal, page) plus the shared session; upstream: Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917 workstreams W3-W7
• Acceptance-criteria coverage: unwanted-behaviour and state-driven cases covered by AC7 (unreachable medium) and AC9 (missed page event); owner accepted with no addition.
• Mechanisms (sync script, redraw attribute, page lock event) are inputs to design and plan from RESEARCH.md items 6-7: revisit if design finds a simpler mechanism.
• Owner's machines: the review plugin's userConfig sets medium hosted; every other view lane local (Q30): revisit if the owner wants PR digests local.
• No team rendered-views.yaml in org repos (Q31): revisit if other people work in org repos with Artifacts on.

Out-of-scope

• A tunnel medium for rendered views (owner: "later", Q26).
• feat(planning): make plans reviewable in a minute with behaviour-first summaries and code-shape views #6927 implementation (its own item, blocked by feat(planning): fail plans with missing citations and trace acceptance criteria #6924).
• CI evidence of a planning view under the Artifact page rules (Q38 answer b): out of scope (owner, 2026-11-02: "CI verification evidence should be out").

Deferred questions

• Q38: answered at planning (owner, 2026-11-02): option (b), CI renders the view under the Artifact page rules; then taken out of scope by the owner.
• Q39: Which plugin setting the carry-over notice names, and where the shown-once state lives; defer until planning; arbiter: /planning:plan
• Q40: Where the offerable-plugin list lives, how a rename is detected, and whose last commit counts; defer until planning; arbiter: /planning:plan
• Q41: Canonical chrome home (plugins/visualization/reference/html-chrome.html or lib/); defer until planning; arbiter: /planning:plan
• Q43: answered at design (owner, 2026-11-02): an Artifact review page offers a "Copy choices as prompt" control; the owner pastes it into the conversation; no new path off the machine (design/design-threads.md T4).
• Q42: Which context-guard zone counts as the warning that suggests a handoff; defer until planning; arbiter: /planning:plan

Load-bearing assumptions

Execution shape: per-item PRs