@xulthekl/team-flow 0.22.4

package/skills/ce-plan/references/reasoning-elevation.md

@@ -0,0 +1,63 @@
+# Fable Elevation (Claude Code only)
+
+This reference is loaded ONLY after a positive Claude Code host check (the gate below). It carries the entire elevation engine; the calling `SKILL.md` holds only a model-name-free pointer. Never inline any part of this file into an always-loaded `SKILL.md` — the silent no-op on other harnesses depends on this text never shipping in a non-Claude context.
+
+Elevation dispatches the reasoning-heavy authoring/interpretation step to a higher-reasoning model (in Claude Code, **Fable**) via a subagent, so a user on a cheaper session model still gets a high-reasoning result without switching their whole session.
+
+## Mechanical host gate — the first ordered step
+
+Before reading any Fable config key, parsing Fable intent, or emitting any Fable string, self-identify the host with the same env-var union `ce-code-review` uses:
+
+```bash
+if [ -n "${CURSOR_AGENT:-}${CURSOR_CONVERSATION_ID:-}" ]; then HOST=cursor;
+elif [ "${CLAUDECODE:-}" = "1" ]; then HOST=claude;
+elif [ -n "${CODEX_SANDBOX:-}${CODEX_SESSION_ID:-}${CODEX_THREAD_ID:-}${CODEX_CI:-}" ]; then HOST=codex;
+else HOST=unknown; fi;
+echo "HOST: $HOST"
+```
+
+These are **host-provided environment variables** — the Claude Code runtime sets `CLAUDECODE=1`, Cursor sets `CURSOR_AGENT` / `CURSOR_CONVERSATION_ID`, Codex sets the `CODEX_*` markers. This skill only reads them; it never sets them. You must actually **run this check with the shell tool** and **branch on the emitted `HOST:` line** — the `echo` is load-bearing: the variable is set inside the shell process and is gone once the command exits, so without reading the printed value you have no observable host to gate on. The value is not knowable from context.
+
+Proceed with elevation ONLY when `HOST=claude`. On `cursor`, `codex`, or `unknown`: elevation is off and inert — do not read Fable config, do not parse intent, do not dispatch, do not mention Fable. (A stray "use fable" prompt on those hosts is handled by the SKILL.md pointer without naming a model.)
+
+## Activation resolution (only after `HOST=claude`)
+
+Resolve a per-skill boolean by precedence:
+
+1. **In-prompt intent** — reason over THIS run's prompt. Affirmative intent ("use fable", "get fable help", "have fable plan this") → elevate. Negative intent ("don't use fable", "no fable") → do not elevate. Intent is *reasoned, not keyword-matched*: a passing mention of "fable" as subject matter (e.g. "design a fable-generator feature") is NOT activation.
+2. **Config** — otherwise the per-skill key: `plan_use_fable` for ce-plan, `brainstorm_use_fable` for ce-brainstorm. Read it from the config file the **same way this skill's Phase 0.0 already resolves `plan_output` / `brainstorm_output`**: reuse the repo root the skill already resolved if you have it, else run `git rev-parse --show-toplevel`, then read `<repo-root>/.compound-engineering/config.local.yaml` with the native file-read tool. This skill already read that file once at Phase 0.0 — reuse that result if you still have it rather than re-reading. Ignore commented (`#`-prefixed) lines. `true` → elevate; missing / commented / invalid / `false` / no file → off.
+3. **Pipeline runs** — in pipeline / `disable-model-invocation` runs there is no prompt, so resolution is config-only; if the key is on, elevate. Still subordinate to the host gate — a config copied to a non-Claude harness never fires it.
+
+If the session model is already Fable, elevation is moot: skip dispatch and the nudge.
+
+## Elevated dispatch
+
+When elevation is active, dispatch the reasoning-heavy step to a Fable subagent:
+
+- Use the platform subagent primitive with a per-agent model override of **fable** (`model: "fable"` on the Claude Code `Agent`/`Task` tool).
+- Pass the main agent's full working context as **file paths the subagent reads itself**, never a re-narrated prose brief. If a needed piece lives only in context, **write it to a fresh scratch file you create** (e.g. `mktemp` under the OS temp dir) rather than skipping it or summarizing it:
+  - **Research / grounding evidence.** ce-brainstorm already wrote a Phase 1.1 grounding dossier to a scratch path — pass it. ce-plan consolidates its Phase 1 research findings *in context only* (Phase 1.4 summarizes; it does not write a file), so **serialize those consolidated findings to a scratch file now and pass it** — the elevated author must interpret the same research evidence the inline path had, not just the resulting decisions.
+  - **Dialogue / decisions.** Write the accumulated dialogue/decisions this skill holds in context to a fresh scratch file and pass that path too.
+
+  Re-narration is forbidden: the main model's default tendency is to compress, and a lossy summary is the failure the quality bet cannot absorb — so hand over files, not a summary.
+- Tell the subagent that, for this run, elevation **supersedes this skill's default ceiling-tier convention** — that the reasoning-heavy step runs inline in the main conversation with nothing dispatched — for this step only.
+- Relay the Fable output through the main agent, which stays the orchestrator.
+
+The elevated steps: **ce-plan** — interpret research findings and author the plan, folded into one interpret-then-author call. **ce-brainstorm** — generate approaches. The ce-brainstorm integration-check consult is deferred and is NOT wired in this version.
+
+## Transparency
+
+- `HOST=claude`, elevation fired → surface a brief confirmation that Fable is handling the step.
+- `HOST=claude`, Fable requested but unavailable (no Fable access / failed dispatch) → run the step inline on the main model and surface a brief fallback notice. Elevation is never a correctness dependency and never blocks the workflow.
+- `HOST≠claude` → silent (the gate already stopped before this file loaded).
+
+## Discoverability nudge
+
+When ALL hold — `HOST=claude`, the run completed with elevation NOT active (no intent, config off), the session is not already on Fable, `fable_nudge` is not `false` in config, this is not a pipeline run, and the tip has not already been shown once — surface the one-line tip, then record that it was shown.
+
+"Shown once" is enforced by a **per-user marker file at a stable path outside the repo** (per-user, not per-checkout — e.g. `~/.config/compound-engineering/fable-nudge-seen`). Before showing: if the marker exists, skip the nudge. After showing: create the marker (with its parent dir). A missing marker means "not yet shown."
+
+- **ce-plan:** `💡 Tip: add "use fable" to your prompt and Fable will author your plan with deeper reasoning — your session model stays as-is. Set plan_use_fable: true to make it the default.`
+- **ce-brainstorm:** `💡 Tip: say "use fable" and Fable will generate sharper approaches — no session switch needed. Set brainstorm_use_fable: true to default it on.`
+
+Never show the nudge when elevation was active (redundant), in pipeline runs (no reader), or off-Claude (the gate stopped earlier).

package/skills/ce-plan/references/research-workflow.md

@@ -0,0 +1,165 @@
+# Phase 1: Research Workflow
+
+Detailed research logic for Phase 1 (Gather Context).
+
+All specialist research and deepening prompts used in this phase are skill-local prompt assets under `references/agents/`. When dispatching one, read the matching file and seed a generic subagent with that prompt content plus the task-specific context below. Do not dispatch standalone agents by type/name.
+
+Model tiering lives in this caller, not in prompt assets. Local prompt files have no frontmatter. Use the platform's mid-tier model for external/organizational research prompts such as `slack-researcher` and `web-researcher` when the current harness exposes a known override; otherwise omit the override and inherit. Use inherited model for high-judgment architecture, migration, and planning-deepening prompts unless the harness has an established cheaper capable tier.
+
+## 1.1 Local Research (Always Runs)
+
+Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents:
+- If an origin document exists, summarize the problem frame, requirements, and key decisions from that document
+- Otherwise use the feature description directly
+- If `STRATEGY.md` exists, read it and include the relevant pieces (target problem, approach, active tracks) in the summary so downstream research and planning decisions are anchored to product strategy
+- If `CONCEPTS.md` exists at repo root, read it — its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.
+- Include session-settled decisions with their rejected alternatives, plus the standing line "If you find evidence a settled decision cannot work, report it — do not suppress it." Do not pass the decision's advocacy or rationale, and keep any adversarial or validation lens blind to settlement markers.
+
+Pass the project's active instructions and the planning context summary to `repo-research-analyst`, and send it directly to the requested current scopes. If the feature cannot be scoped from that context, allow one targeted root or workspace probe. Read an exact dependency or runtime version when the plan or an external-doc query materially depends on it.
+
+Run these agents in parallel:
+
+- `references/agents/repo-research-analyst.md` — scope: **patterns**. Pass the planning context summary so it can go directly to current feature patterns and owning code.
+- `references/agents/learnings-researcher.md` — pass the planning context summary.
+
+**Agent-native planning triage** (conditional) — consider broadly, dispatch selectively. Dispatch a generic subagent with `references/agents/agent-native-planning-strategist.md` in parallel with the local research agents when the request, origin document, or repo research indicates any of:
+
+- agent, assistant, chat, workflow automation, MCP, plugin, skill, tool registry, prompt, or autonomous-loop work
+- a codebase with an existing agent surface where this feature changes user-visible capabilities
+- a primary domain action that is repetitive, high-volume, complex, naturally language-shaped, or likely to need automation access
+- a risk that the plan will widen the gap between UI/API actions and agent-accessible tools or context
+
+Do **not** dispatch for cosmetic, layout-only, animation-only, brand, low-value preference, or narrow work in a product with no agent surface. If the signal is borderline, do not dispatch; carry only a short future parity consideration when it affects a high-value domain action. Include any resulting findings in consolidation as planning inputs, not as a standalone advice appendix.
+
+Collect:
+- Exact dependency or runtime versions only when they materially affect the plan or an external research decision
+- Relevant architecture and implementation patterns, files, modules, and tests for the requested scope
+- Applicable constraints from the project's active instructions and context
+- Institutional learnings from `docs/solutions/`
+- Product strategy context when `STRATEGY.md` is present — flag any plan decisions that pull away from the active tracks or the stated approach
+- Agent-native planning findings when the conditional triage dispatched: action/context parity decisions, tool/workspace/execution-lifecycle choices, scope boundaries, and verification scenarios
+
+**Slack context** (opt-in) — never auto-dispatch. Route by condition:
+
+- **Tools available + user asked**: Dispatch a generic subagent with `references/agents/slack-researcher.md` and the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation.
+- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
+- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
+
+**Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = plan OR phase = cross-phase` and `domain` matches the current topic. Inject top-5 summaries as planning constraints. If INDEX.md does not exist or is empty, skip silently.
+
+## 1.1b Detect Execution Direction Signals
+
+Decide whether the plan should carry a lightweight execution direction signal.
+
+Look for signals such as:
+- The user explicitly asks for TDD, test-first, or characterization-first work
+- The origin document calls for test-first implementation or exploratory hardening of legacy code
+- Local research shows the target area is legacy, weakly tested, or historically fragile, suggesting characterization coverage before changing behavior
+- The work is mostly configuration, packaging, UI styling, or environment setup where the right first proof is a smoke/runtime check rather than unit coverage
+
+When the signal is clear, carry it forward silently in the relevant implementation units.
+
+Ask the user only if the direction would materially change sequencing or risk and cannot be responsibly inferred.
+
+## 1.2 External Research Decision
+
+Based on the origin document, user signals, and local findings, decide **whether** external research adds value and, if so, **what kind**. Resolve this in three stages:
+
+### Stage 1 — Explicit Request Takes Precedence
+
+If the user prompt **or** the origin requirements document explicitly asks for external input — a signal that the answer lives outside the repo, such as competitor/prior-art comparison, "what should we borrow", "from the web", "best practices", "official docs", "alternatives to", a market scan, or naming a specific external technology to consult — external research is **required**, regardless of how strong local patterns look. The list is illustrative; key on the signal, not the exact phrase. The skip conditions below do **not** apply to an explicit request. The only thing that overrides it is an explicit opt-out ("no web research", "skip external research"): honor that, skip, and note it. Improvement or quality verbs ("improve", "make better") carry no external signal on their own and never trigger research by themselves.
+
+### Stage 2 — Classify the Research Intent
+
+Whenever external research will run (from Stage 1 or the implicit signals below), classify so Phase 1.3 routes correctly:
+
+- **Implementation-guidance** — the approach or technology is already settled; the question is *how to build it well* (best practices, version-specific docs, API constraints, known pitfalls, deprecations).
+- **Landscape / option-discovery** — the question is *what options or prior art exist* (competitor scans, build-vs-buy, library/provider selection, prior art, market signals, cross-domain analogies).
+- **Mixed** — both: discover an unsettled external option set first, then research the shortlisted choice for implementation guidance.
+
+### Stage 3 — Implicit Signals
+
+**Read between the lines:**
+- **User familiarity** — Are they pointing to specific files or patterns? They likely know the codebase well.
+- **User intent** — Do they want speed or thoroughness? Exploration or execution?
+- **Topic risk** — Security, payments, external APIs warrant more caution regardless of user signals.
+- **Uncertainty level** — Is the approach clear or still open-ended?
+
+**Leverage the repo research prompt's technology context:**
+
+Use technology facts already present in the project's active instructions, planning context, or task-specific repo research. Read any exact version fresh from the owning manifest when it materially affects an external-research decision:
+
+- If specific frameworks and versions were detected (e.g., Rails 7.2, Next.js 14, Go 1.22), pass those exact identifiers to the `framework-docs-researcher` local prompt so it fetches version-specific documentation
+- If the feature touches a technology layer the scan found well-established in the repo, lean toward skipping external research
+- If the feature touches a technology layer the scan found absent or thin, lean toward external research
+- If the scan detected deployment infrastructure (Docker, K8s, serverless), note it in the planning context
+- If the scan detected a monorepo and scoped to a specific service, pass that service's tech context — not the aggregate
+
+**Always lean toward external research when:**
+- The topic is high-risk: security, payments, privacy, external APIs, migrations, compliance
+- The codebase lacks relevant local patterns — fewer than 3 direct examples
+- Local patterns exist for an adjacent domain but not the exact one
+- The user is exploring unfamiliar territory
+- The technology scan found the relevant layer absent or thin
+- The plan's recommendations depend on a genuinely external, **unsettled** option set — bounded by three gates: (a) the option set genuinely lives outside the repo, (b) the decision materially shapes the plan, and (c) no settled local or team choice already exists
+
+**Skip external research when** (only when Stage 1 found no explicit request):
+- The codebase already shows a strong local pattern — multiple direct examples, recently touched, following current conventions
+- The user already knows the intended shape
+- Additional external context would add little practical value
+- The technology scan found the relevant layer well-established
+
+When an explicit request *did* fire but a settled local or team choice already exists, **narrow the research rather than skipping it**.
+
+Announce the decision and the intent briefly before continuing.
+
+## 1.3 External Research Dispatch (Conditional)
+
+If Step 1.2 indicates external research is useful, dispatch by the **intent** classified in Stage 2, using the platform's subagent primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex) where available; otherwise run the work inline or serially. Read the selected prompt asset from `references/agents/` and seed a generic subagent with it. For `web-researcher.md`, pass a focus hint plus the planning context summary and do **not** pass codebase content.
+
+- **Implementation-guidance** — run in parallel:
+  - `references/agents/best-practices-researcher.md` with the planning context summary.
+  - `references/agents/framework-docs-researcher.md` with the planning context summary and exact frameworks/versions from Phase 1.1 where available.
+- **Landscape / option-discovery** — `references/agents/web-researcher.md` with the focus hint and planning context summary. When the request targets projects on a code host, name the discovery dimensions in the focus hint: project names and URLs, release recency and activity, CLI/UX shape, install path, docs and examples, plugin/extension surfaces, recurring issue themes, and license.
+- **Mixed** — **sequential, not parallel**: run the `web-researcher` local prompt first to map the landscape and produce a shortlist; then run the `framework-docs-researcher` and/or `best-practices-researcher` local prompts against the shortlisted technologies only when their details materially shape the plan.
+
+**Tool-unavailable handling.** `web-researcher` self-checks for web tools and stops if they are missing. Never block on this: if it reports research unavailable, or any researcher fails, warn and proceed, and carry the gap into Phase 1.4 so the plan records it honestly.
+
+## 1.4 Consolidate Research
+
+Summarize:
+- Relevant codebase patterns and file paths
+- Relevant institutional learnings
+- Organizational context from Slack conversations, if gathered
+- External references, prior art, competitor/landscape findings, and best practices, if gathered
+- Related issues, PRs, or prior art
+- Any constraints that should materially shape the plan
+
+**Land external findings in decisions, not an appendix.** Any external research that ran must surface where it changes a choice — Key Technical Decisions rationale, Alternatives, Risks, or Sources & Research — not as a detached list with no bearing on the plan.
+
+**Mark whether external research was load-bearing.** Record a single internal flag: did external findings materially shape a KTD, Alternative, Scope boundary, or Risk? Phase 5.3.2 reads it to decide whether to enter a confidence-scoring pass.
+
+**Record requested-but-unavailable.** If the user explicitly requested external research but it could not run, state that in the plan as an assumption or open question rather than presenting the plan as externally grounded.
+
+## 1.4b Reclassify Depth When Research Reveals External Contract Surfaces
+
+If the current classification is **Lightweight** and Phase 1 research found that the work touches any of these external contract surfaces, reclassify to **Standard**:
+
+- Environment variables consumed by external systems, CI, or other repositories
+- Exported public APIs, CLI flags, or command-line interface contracts
+- CI/CD configuration files (`.github/workflows/`, `Dockerfile`, deployment scripts)
+- Shared types or interfaces imported by downstream consumers
+- Documentation referenced by external URLs or linked from other systems
+
+Announce the reclassification briefly: "Reclassifying to Standard — this change touches [environment variables / exported APIs / CI config] with external consumers."
+
+## 1.5 Flow and Edge-Case Analysis (Conditional)
+
+For **Standard** or **Deep** plans, or when user flow completeness is still unclear, run:
+
+- `references/agents/spec-flow-analyzer.md` with the planning context summary and research findings.
+
+Use the output to:
+- Identify missing edge cases, state transitions, or handoff gaps
+- Tighten requirements trace or verification strategy
+- Add only the flow details that materially improve the plan

package/skills/ce-plan/references/review-and-write.md

@@ -0,0 +1,127 @@
+# Phase 5: Review, Write, and Confidence Check
+
+Detailed review, writing, and confidence-check logic for Phase 5.
+
+## Review Checklist
+
+Before finalizing, check:
+- The plan does not invent product behavior that should have been defined in `ce-brainstorm`
+- If there was no origin document, the bounded planning bootstrap established enough product clarity to plan responsibly
+- Every major decision is grounded in the origin document or research
+- Each implementation unit is concrete, dependency-ordered, and implementation-ready
+- If test-first proof, characterization coverage, smoke-first verification, or another execution direction was explicit or strongly implied, the relevant units carry it forward with a lightweight natural-language `Execution note`
+- Each feature-bearing unit has test scenarios from every applicable category (happy path, edge cases, error paths, integration) — right-sized to the unit's complexity, not padded or skimped
+- Test scenarios name specific inputs, actions, and expected outcomes without becoming test code
+- Feature-bearing units with blank or missing test scenarios are flagged as incomplete — the `Test expectation: none -- [reason]` annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)
+- Deferred items are explicit and not hidden as fake certainty
+- Every implementation unit that implements a session-settled decision cites the labeled KTD in its Requirements or Approach
+- **High-Level Technical Design presence audit (load-bearing).** For each architecture trigger in Phase 3.4 that the plan content satisfies (3+ components with directed relationships, 3+ protocol steps, 3+ state machine states, lifecycle, 3+ decision points, 3+ data-flow stages, mode/flag combinations, DSL/API surface design, non-obvious single-component shape), verify a corresponding sketch/diagram is present in the High-Level Technical Design section. Count the firing triggers; count the sketches; the sketch count must be at least the count of distinct trigger categories that fired. Missing the section when a trigger fired, OR including the section but skipping a triggered sketch within it, is incomplete — return to Phase 3.4 and add the missing sketch. Token cost is not a valid reason to fail this check.
+- If a High-Level Technical Design section is included, it uses the right medium for the work, carries the non-prescriptive framing, and does not contain implementation code
+- Per-unit technical design fields, if present, are concise and directional rather than copy-paste-ready
+- If the plan creates a new directory structure, would an Output Structure tree help reviewers see the overall shape?
+- If Scope Boundaries lists items that are planned work for a separate PR, issue, or repo, are they under `### Deferred to Follow-Up Work` rather than mixed with true non-goals?
+- U-IDs are unique within the plan and follow the stability rule — no two units share an ID; reordering or splitting did not renumber existing units; gaps from deletions are preserved
+- Would a visual aid (dependency graph, interaction diagram, comparison table) help a reader grasp the plan structure faster than scanning prose alone?
+
+If the plan originated from a requirements document, re-read that document and verify:
+- The chosen approach still matches the product intent
+- Scope boundaries and success criteria are preserved
+- Blocking questions were either resolved, explicitly assumed, or sent back to `ce-brainstorm`
+- Every section of the origin document is addressed in the plan — scan each section to confirm nothing was silently dropped
+- If origin supplies A/F/AE IDs: every origin R/F/AE that *affects implementation* is referenced in Requirements, a U-ID unit, test scenarios, verification, scope boundaries, or explicitly deferred. Actors are carried forward when they affect behavior, permissions, UX, orchestration, handoff, or verification. The standard is preservation of product intent, not mandatory ID spam — irrelevant origin IDs may be omitted
+- If origin was Deep-product (origin contains an `Outside this product's identity` subsection): the plan's Scope Boundaries preserves the three-way split — `Deferred for later` and `Outside this product's identity` carried verbatim from origin, `Deferred to Follow-Up Work` reserved for plan-local implementation sequencing
+
+## Brainstorm-Sourced Scoping Synthesis (5.1.5)
+
+Surface plan-time call-outs to the user before Phase 5.2 commits the plan to disk — the latest cheap moment to catch plan-time scope errors. The brainstorm already validated WHAT to build; this phase surfaces HOW the plan will execute on the forks that matter.
+
+Fires **whenever Phase 0.2 resolved an upstream PRD source** — a PRD document (`prd/vN/prd.md`) **or** a legacy `*-requirements.{md,html}` brainstorm doc — AND not on Phase 0.1 fast paths. Skip Phase 5.1.5 only in solo invocation (no upstream source found) — solo plans handled their synthesis in Phase 0.7.
+
+**Read `references/synthesis-summary.md` before composing the scoping synthesis.**
+
+**Required gate output — do not skip; silent proceeding is not allowed.** Compose an internal three-bucket scope draft (Stated / Inferred / Out of scope). Derive call-outs, run the pre-emit scans, then emit the **brainstorm-sourced** synthesis and **wait for user confirmation before continuing to Phase 5.2.** Its summary is two parts — a 1-2 sentence restatement of the brainstorm's scope in the brainstorm's own vocabulary, then the plan-specific scoping decisions the brainstorm did not make — each affirmable without reading code, and never an enumeration of Implementation Units, file paths, or PR/sequencing shape.
+
+**Blocking decision:** auto-proceed only when plan depth is **Lightweight AND zero call-outs survive**. Standard and Deep always fire the confirmation gate.
+
+**Headless / opt-in skip:** in headless mode, or when `SKIP_SCOPING_CONFIRM` resolved to skip, do not block — compose the internal draft, skip the chat-time confirmation, and route Inferred bets to a `## Assumptions` section at plan-write.
+
+## Write Plan File (5.2)
+
+**Reasoning elevation (Claude Code only).** Before authoring the plan, if positively Claude Code (`CLAUDECODE=1`, not Cursor/Codex), load `references/reasoning-elevation.md` and follow it. On any non-Claude host, skip it entirely.
+
+**REQUIRED: Write the plan file to disk before presenting any options.**
+
+HTML note: `ce-doc-review` is markdown-only today. HTML plans still render the unified artifact, but the Phase 5.3.8 document-review autofix pass is skipped for HTML by the format gate in `references/plan-handoff.md`.
+
+Use the Write tool to save the complete plan:
+
+```text
+prd/{ITERATION_VERSION}/plan.md
+```
+
+The plan is always written to the same `prd/vN/` directory as the PRD, using the iteration version resolved at Phase 0.2. The plan is always markdown (`.md`).
+
+Compose the plan using the content from `templates/plan.md` (the plan template) and the format-specific principles from the rendering reference loaded at Phase 0.0.
+
+**Session-settled KTDs.** Author each settled decision as a labeled Key Technical Decision carrying the annotation `(session-settled: user-directed — chosen over <alternative>: <one-line reason>)` (class per `references/settled-decisions.md`: `user-directed` or `user-approved`). A KTD that instantiates a labeled Key Decision from a brainstorm-sourced Product Contract inherits the label and cites the source decision.
+
+**HTML composition timing.** When `OUTPUT_FORMAT=html`, Phase 5.3 deepening runs before this write completes its final form, but `ce-doc-review` is skipped in HTML mode.
+
+Confirm (use absolute path so the reference is clickable in modern terminals):
+
+```text
+Plan written to <absolute path to plan>
+```
+
+**Pipeline mode:** If invoked from an automated workflow such as LFG or any `disable-model-invocation` context, skip interactive questions. Make the needed choices automatically and proceed to writing the plan. Pipeline mode forces `OUTPUT_FORMAT=md` at Phase 0.0. Exception: when research produced invalidating evidence against any session-settled decision — do not write the plan and do not resolve silently — return a blocked report to the caller containing the token `settled-decision-invalidated`, the decision, and the reason.
+
+**CONCEPTS.md gap-fill (only if the file already exists):** If the plan body uses a domain term whose definition is missing from `CONCEPTS.md`, add the entry. **Domain entities, named processes, and status concepts with project-specific meaning only** — not file paths, class names, function signatures, or implementation decisions. Follow the format set by existing entries. Apply silently. Skip entirely if `CONCEPTS.md` does not exist.
+
+## Confidence Check (5.3)
+
+After writing the plan file, automatically evaluate whether the plan needs strengthening.
+
+**Two deepening modes:**
+
+- **Auto mode** (default during plan generation): Runs without asking the user for approval. Sub-agent findings are synthesized directly into the plan.
+- **Interactive mode** (activated by the re-deepen fast path in Phase 0.1): The user explicitly asked to deepen an existing plan. Sub-agent findings are presented individually for review before integration. The user can accept, reject, or discuss each agent's findings.
+
+`ce-doc-review` and this confidence check are different:
+- Use `ce-doc-review` when the document needs clarity, simplification, completeness, or scope control
+- This confidence check strengthens rationale, sequencing, risk treatment, and system-wide thinking
+
+**Pipeline mode:** This phase always runs in auto mode in pipeline/disable-model-invocation contexts.
+
+### 5.3.1 Classify Plan Depth and Topic Risk
+
+Determine the plan depth from the document:
+- **Lightweight** - small, bounded, low ambiguity, usually 2-4 implementation units
+- **Standard** - moderate complexity, some technical decisions, usually 3-6 units
+- **Deep** - cross-cutting, high-risk, or strategically important work, usually 4-8 units or phased delivery
+
+Build a risk profile. Treat these as high-risk signals:
+- Authentication, authorization, or security-sensitive behavior
+- Payments, billing, or financial flows
+- Data migrations, backfills, or persistent data changes
+- External APIs or third-party integrations
+- Privacy, compliance, or user data handling
+- Cross-interface parity or multi-surface behavior
+- Significant rollout, monitoring, or operational concerns
+
+### 5.3.2 Gate: Decide Whether to Deepen
+
+- **Lightweight** plans usually do not need deepening unless they are high-risk
+- **Standard** plans often benefit when one or more important sections still look thin
+- **Deep** or high-risk plans often benefit from a targeted second pass
+- **Thin local grounding override:** If Phase 1.2 triggered external research because local patterns were thin (fewer than 3 direct examples or adjacent-domain match), always proceed to scoring regardless of how grounded the plan appears.
+- **Load-bearing external research override:** If Phase 1.4 marked external research as load-bearing, always proceed to scoring — **even when local implementation patterns are strong**.
+
+If the plan already appears sufficiently grounded and neither override applies, report "Confidence check passed — no sections need strengthening", then **load `references/plan-handoff.md` now and execute 5.3.8 → 5.3.9 → 5.4 in sequence**. Document review is mandatory for markdown plans — do not skip it because the confidence check passed.
+
+### 5.3.3–5.3.7 Deepening Execution
+
+When deepening is warranted, read `references/deepening-workflow.md` for confidence scoring checklists, section-to-agent dispatch mapping, execution mode selection, research execution, interactive finding review, and plan synthesis instructions. Execute steps 5.3.3 through 5.3.7 from that file, then return for 5.3.8.
+
+### 5.3.8–5.4 Document Review, Final Checks, and Post-Generation Options
+
+**Load `references/plan-handoff.md` now before continuing.** It carries the full instructions for 5.3.8 (document review), 5.3.9 (final checks and cleanup), and 5.4 (post-generation handoff, including the Publish to Proof flow and Issue Creation branching). **This load is non-optional.**

package/skills/ce-plan/references/settled-decisions.md

@@ -0,0 +1,45 @@
+# Session-Settled Decisions
+
+Protocol and schema for carrying decisions the user already made in the invoking conversation, so this skill augments them instead of re-litigating them. This file is byte-duplicated between `ce-plan` and `ce-brainstorm` (skills cannot share files); any edit must land in both copies and is guarded by `tests/settled-decisions-parity.test.ts`.
+
+## The settlement test
+
+Classify each conversation-carried decision by whether it survived examination — not by how confident the user sounded.
+
+- **Settled** — a tradeoff, alternative, or risk was surfaced in the conversation and the user chose with it in view. Record with a provenance class (below).
+- **Directive** — the user asserted a choice no one examined (e.g., a cold "build it with X"). Not settled. It receives exactly one in-pipeline challenge, spent during this skill's research/pressure-test phase; the outcome lands in the artifact as a (labeled or unlabeled) decision entry. The artifact is the only challenge ledger — later stages do not get a second challenge, and an unanswered pipeline-surfaced challenge may resurface only through the divergent/residual channel of the calling pipeline.
+- **Unlabeled** — anything only the agent inferred or proposed without user engagement. Ordinary planning input; never annotated.
+
+Contrast pair: the user rejected option A after seeing the tradeoff -> settled (`user-directed`); the user said "sounds good" to a passing mention -> at most `user-approved`; the agent proposed X and the user never engaged -> no label.
+
+**No self-settling.** An agent never labels its own unexamined proposal, and never upgrades bare assent to `user-directed`. Only the user's conversation acts mint provenance.
+
+## Provenance classes
+
+Exactly two classes; both render as visible English in the artifact:
+
+- `user-directed` — the user chose against or between surfaced options ("no, do X").
+- `user-approved` — the agent proposed with the tradeoff surfaced; the user assented.
+
+The class records decision strength for human readers (plan annotation, PR provenance line) and is the relabel target when a later interactive acceptance changes a settled decision (the change was proposed and accepted -> `user-approved`). Consumers do not route differently by class today.
+
+## The annotation
+
+A settled decision is recorded on its Key Technical Decision entry (plan) or Key Decision entry (brainstorm Product Contract) as an inline English parenthetical:
+
+`(session-settled: user-directed — chosen over <alternative>: <one-line reason>)`
+
+- The stem `session-settled:` and the class tokens `user-directed` / `user-approved` are stable protocol — greppable and test-pinned. The rest of the sentence is free-form prose.
+- Self-contained: decision, rejected alternative, and reason must be readable by a consumer with no access to the conversation.
+- No sidecar files, no frontmatter registry, no numeric weights, no lifecycle field. An unrecognized consumer sees a normal decision entry; the worst-case degradation is today's re-litigation, never corruption.
+
+## Capture rules
+
+- Never re-ask a settled decision. In the scoping synthesis it renders as a "Carrying forward:" line, not a call-out, and question phases skip it.
+- Research augments settled decisions and may contradict them only on evidence, routed by the severity ladder: nothing found -> proceed silently; suboptimal-but-workable -> proceed as settled and attach a conflict call-out to the decision entry (artifact-write time only — post-write consumers never mutate the artifact); invalidating (infeasible, wrong-thing, destructive) -> stop as blocked per this skill's pipeline contract.
+- A settled label never suppresses defect evidence: a real bug or infeasibility finding inside a settled approach keeps full severity everywhere.
+- When passing research context to subagents, include settled decisions as scope — with their rejected alternatives, so researchers do not re-survey them — plus the standing line: "If you find evidence a settled decision cannot work, report it — do not suppress it." Do not pass the advocacy or rationale for the decision (the decision as fact scopes the work; advocacy anchors), and keep any adversarial/validation lens blind to settlement markers.
+
+## Brief entries (pipeline input)
+
+A calling skill (e.g. `lfg`) may pass a distilled brief as invocation input — from the user or a calling skill. Each settled-decision entry requires: the decision, its class, the rejected alternative, and a one-line reason. An entry that cannot state its rejected alternative fails the settlement test — demote it to a directive (one challenge) or an open area. The required fields are a compliance aid; the settlement classification itself remains this skill's judgment. The brief is transient: once the artifact is written with labeled entries, the artifact is canonical and the brief carries no further authority.