@xulthekl/team-flow 0.22.4

package/skills/ce-ideate/references/ideation-sections.md

@@ -0,0 +1,191 @@
+# Ideation Sections
+
+This is the section contract for the ce-ideate artifact — it describes
+*what* a persisted ideation document contains, independent of output
+format. It is paired with a format-rendering reference
+(`references/markdown-rendering.md` or `references/html-rendering.md`)
+that describes *how* the resolved format presents these sections. The
+same content renders in either format; only presentation differs.
+
+Load this file at save time alongside the rendering reference matching
+`OUTPUT_FORMAT` (see `references/post-ideation-workflow.md` §4.1).
+
+## What the artifact contains
+
+An ideation artifact is a ranked, critiqued candidate set, the grounding
+the candidates were qualified against, and a record of what was cut. It
+is a human-facing discovery document, not a requirements doc or plan —
+keep it about the ideas and their basis, not implementation.
+
+### Metadata
+
+- **date** — composition date (YYYY-MM-DD).
+- **topic** — kebab-case topic slug.
+- **focus** — the focus hint, when one was given. Omit when open-ended.
+- **mode** — `repo-grounded`, `elsewhere-software`, or
+  `elsewhere-non-software`.
+
+Markdown renders metadata as YAML frontmatter at the top of the file.
+HTML renders it as visible header text (per the html-rendering hard
+invariant: one visible source of truth per value, no hidden
+machine-readable copy).
+
+**No status field — not on the doc, not per idea.** An ideation doc is a
+point-in-time discovery artifact, not a tracked work item: it carries no
+`active → completed` lifecycle and no per-idea "explored" marker.
+Tracking mutable workflow progress inside the artifact would create a
+second source of truth that drifts — whether an idea was later pursued is
+knowable from downstream artifacts (a brainstorm or plan that picked it
+up), so it is not duplicated here.
+
+### Grounding Context
+
+The Phase 1 grounding summary the ideas were qualified against — labeled
+"Codebase Context" in repo mode, "Topic Context" in elsewhere mode.
+
+### Topic Axes (conditional)
+
+The 3-5 axes from Phase 1.5, one per line. When Phase 1.5 was skipped, a
+single line records why (`Decomposition skipped — atomic subject` or
+`Decomposition skipped — surprise-me mode`). Omit the section entirely
+when not applicable.
+
+### Ranked Ideas
+
+The surviving candidates, ranked. Each idea carries:
+
+- **title**
+- **description** — concrete explanation.
+- **axis** — the topic axis this idea targets. Omit when decomposition
+  was skipped.
+- **basis** — tagged `direct:` (quoted evidence) / `external:` (named
+  prior art) / `reasoned:` (written-out first-principles argument).
+- **rationale** — how the basis connects to the move's significance.
+- **downsides** — tradeoffs or costs.
+- **confidence** — 0-100%.
+- **complexity** — Low / Medium / High.
+
+**Keep idea cards expanded; add a jump-list when the section is long.**
+Unlike plan Implementation Units, ideation idea cards are meant to be read
+in full to choose a direction — do not hide their substance behind
+default-closed `<details>`. But the Ranked Ideas section is typically 5-7
+cards and runs long in HTML, so add a within-section jump-list of the
+ranked titles (anchor links to each card) at the top of the section, per
+the rendering reference's within-section sub-nav affordance.
+
+**Illustrative visuals — decide on the idea's shape, not on how clear the
+prose reads.** A well-placed visual can make a direction land faster for a
+human scanning a set of candidates. Decide per survivor — none, a few, or
+most may warrant one; there is no quota and no cap.
+
+Watch one trap when you make this call: the prose always conveys the idea
+(that is the hard rule below), and as a text-native reasoner you will tend
+to read your own prose, judge it "clear," and conclude no visual is needed
+— which quietly under-produces the visuals that actually help a reader. So
+"the prose is already clear" is never the reason to skip. The real
+question is what the idea *hinges on*, and whether that has a shape a
+picture carries faster than a sentence.
+
+**Concrete-vs-abstract is the wrong axis.** Don't reach for a visual
+because an idea feels big or conceptual, and don't skip one because it
+feels small or concrete. A new-feature *concept* is often the best
+candidate — the reader has to picture an unfamiliar arrangement — while
+many concrete changes (an error fix, a drop-in dependency swap) have
+nothing structural to draw. Ask what the idea hinges on, not how abstract
+it is.
+
+- **Hinges on a structure → lean toward a visual.** A relationship
+  between parts, a flow or sequence, a before/after contrast, a
+  structural arrangement, an analogy mapping (especially cross-domain
+  ideas), a quantitative comparison. A picture lands these faster than a
+  sentence even when the prose is perfectly clear — and it should show
+  the *basis* or the *why-it-matters*, not restate the title. New-feature
+  concepts frequently live here.
+- **A single point with nothing structural to show → no visual.** A
+  renamed thing, a copy change, "handle the null case," a drop-in library
+  swap — there is no shape a diagram would add; one here is decoration.
+  Size and abstraction don't decide this: a sweeping concept can still be
+  one proposition ("ship dark mode"), and a small concrete fix can still
+  re-route how two parts talk (real shape, worth drawing).
+
+Decoration — a visual with no shape to show, or one that just restates the
+title — is the failure mode, and it is slop whether it appears once or
+five times. A visual that genuinely shows the idea's shape is never slop,
+however many ideas warrant one.
+
+Two constraints on any visual you do add:
+
+- **Stay at the idea's altitude — illustrative, not a spec.** This is the
+  *opposite* of a plan or requirements diagram. The shared rendering
+  reference treats plan diagrams as authoritative content and forbids
+  "directional sketch" framing; ideation visuals are the reverse —
+  deliberately directional overviews of a direction nobody has committed
+  to yet. Keep them conceptual (contrast, analogy, rough flow). Detailed
+  architecture, sequence diagrams, and wireframes belong downstream in
+  ce-brainstorm / ce-plan once a direction is chosen, not here.
+- **Keep the prose standing alone.** A reader who ignores the visual
+  still gets the complete idea and its basis. The visual accelerates
+  understanding; it never carries content found nowhere else.
+
+Rendering mechanics (inline SVG in HTML with the layout-legibility and
+halo rules; a fenced mermaid block in markdown when the shape suits it)
+follow the rendering reference's Diagrams section — but that section's
+plan-centric, authoritative-diagram framing is overridden here by the
+illustrative, decide-per-idea stance above.
+
+### Rejection Summary
+
+A table of considered-and-cut ideas with a one-line reason each. When an
+axis ended with zero survivors despite recovery, record it as its own
+row so the coverage gap is visible rather than silently absent.
+
+## Markdown skeleton
+
+The section shape both formats carry. In markdown it is written
+literally (omit clearly irrelevant fields only when necessary); in HTML
+the same sections render per `html-rendering.md`.
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+focus: <optional focus hint>
+mode: <repo-grounded | elsewhere-software | elsewhere-non-software>
+---
+
+# Ideation: <Title>
+
+## Grounding Context
+[Grounding summary from Phase 1 — "Codebase Context" in repo mode, "Topic Context" in elsewhere mode]
+
+## Topic Axes
+[3-5 axes from Phase 1.5, one per line, OR a single `Decomposition skipped — ...` line. Omit the section if not applicable.]
+
+## Ranked Ideas
+
+### 1. <Idea Title>
+**Description:** [Concrete explanation]
+**Axis:** [Topic axis this idea targets — omit when decomposition was skipped]
+**Basis:** [`direct:` / `external:` / `reasoned:` — quoted, cited, or written-out argument]
+**Rationale:** [How the basis connects to the move's significance]
+**Downsides:** [Tradeoffs or costs]
+**Confidence:** [0-100%]
+**Complexity:** [Low / Medium / High]
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | <Idea> | <Reason rejected> |
+
+[When applicable, append axis-coverage gaps as their own rows so the gap is visible:]
+| - | axis: <name> | recovery skipped (cap reached) — no survivors on this axis |
+```
+
+## No process exhaust
+
+Keep engineering-process metadata out of the artifact — no "captured at
+Phase X" notes, no skill-pointer "next steps", no italic provenance
+lines. The reader wants the ideas and their basis. (HTML carries a
+single visible composition-signal footer per the html-rendering
+invariant; that is the one provenance element that belongs in the doc.)

package/skills/ce-ideate/references/markdown-rendering.md

@@ -0,0 +1,238 @@
+# Markdown Rendering
+
+This is a format-rendering reference — it describes how to render any
+artifact in markdown, independent of which skill is producing it.
+
+It is paired with a section contract (`plan-sections.md`,
+`brainstorm-sections.md`, etc.) that describes *what* the artifact contains.
+This reference describes *how* markdown specifically presents it. The same
+content rendered by different skills shares the same markdown principles.
+
+## Hard invariants
+
+These hold regardless of which skill produced the artifact.
+
+- **YAML frontmatter at the top of the file.** Standard `---` delimited block
+  containing the artifact's stable metadata (title, date, type, etc.
+  — exact fields are per-skill, defined in the section contract).
+- **ASCII identifiers in anchors.** Markdown headings auto-generate anchors
+  from the heading text. Keep headings ASCII so anchors are predictable
+  (`#implementation-units`, not `#implementación-units`).
+- **Repo-relative paths for file references.** Always. Never absolute paths
+  — they break portability across machines, worktrees, teammates.
+- **No HTML mixed in.** Keep the markdown pure. No `<div>`, no `<details>`,
+  no inline `<style>`. If a layout idea only works as HTML, defer it to the
+  HTML rendering. Markdown stays markdown.
+- **No fixed-width line wrapping.** Do not hard-wrap prose to a column (e.g.
+  80 chars). Write one sentence per line, or let each paragraph flow as a
+  single line. The artifact is read rendered and shared, where fixed wraps add
+  nothing and only produce noisy mid-sentence diffs; markdown joins soft line
+  breaks within a paragraph, so wrapping never changes the rendered output.
+- **Unified plan sections use stable headings.** For unified plan artifacts,
+  render the required sections with exact ASCII headings so agents can find
+  them by heading scan: `## Goal Capsule`, `## Product Contract`,
+  `## Planning Contract`, `## Implementation Units`, `## Verification Contract`,
+  `## Definition of Done`, and optional `## Appendix`. Requirements-only
+  artifacts omit the plan-only sections rather than emitting empty placeholders.
+  These stable headings are the wayfinding contract: consumers scan them
+  (markdown headings, or `<h1>`–`<h3>` / anchor ids in HTML) instead of reading
+  the whole document.
+- **Goal Capsule is top-loaded.** It appears before Product Contract and long
+  appendices for fast orientation — not a hidden machine copy.
+
+## Format principles
+
+These shape what "good" markdown looks like; the agent applies them per
+artifact based on content shape.
+
+### ID prefix format
+
+Stable IDs (R, U, A, F, AE, KTD) appear as plain prefixes at the start of
+the bullet or heading — do NOT bold the prefix. The prefix is visually
+distinctive on its own; bolding it inflates visual noise.
+
+```markdown
+- R1. The plan returns paginated sessions.   ← right
+- **R1.** The plan returns paginated sessions.   ← wrong (bolded prefix)
+```
+
+Same applies to unit headings: `### U1. Cloak detection in preflight contract`.
+
+### Content shape: prose vs bullets vs tables
+
+The same content can be rendered three ways; the agent picks per content
+shape, not by template default.
+
+- **Prose** when the content has narrative flow (motivation, decision
+  rationale, problem framing). Bullets fragment narrative into
+  disconnected pieces.
+- **Bullets** when items share a parallel shape but each carries enough
+  prose to not fit a table cell.
+- **Tables** when 5+ items share uniform structure (`ID + body`,
+  `name + value`, `decision + rationale`, `risk + mitigation`). Tables
+  scan faster at that scale and unlock additional columns (status,
+  traceability, severity) that bullets can't accommodate cleanly.
+
+The test: which shape would a reader scan fastest for this content? If
+items have parallel structure and 5+ instances, table. If items are 3-5
+and each has a few lines of prose, bullets. If the content is a single
+narrative thought, prose.
+
+### Bold leader labels within bullets
+
+When a bullet has substructure that benefits from named fields (Key Flows
+with Trigger / Actors / Steps / Outcome, Acceptance Examples with Covers
+/ Given / When / Then), use bold leader labels at the start of nested
+bullets — not deeper heading levels.
+
+```markdown
+- F1. Anonymous capture
+  - **Trigger:** Agent enters Step 2a with no session.
+  - **Actors:** A1, A2
+  - **Steps:** Preflight detects cloak; agent launches; capture proceeds.
+  - **Covered by:** R1, R2, R5
+```
+
+This gives the bullet structure without needing H4/H5 headings that would
+clutter the doc and break TOC generation.
+
+### Section separators
+
+For substantial artifacts, use horizontal rules (`---`) between top-level
+H2 sections. Omit for short docs where separators would dominate.
+
+### Tables for genuinely comparative info only
+
+Use tables for the uniform-shape case in "Content shape" above. Don't use
+tables to render content lists that are really bullets — markdown tables
+are noisier in raw form and worse for diffs.
+
+## Section anatomy
+
+How section types commonly render in markdown. These are patterns, not
+contracts — the agent picks the shape that fits the content.
+
+- **Goal Capsule** — bullets or a small table for objective, authority,
+  execution profile, stop conditions, and tail ownership.
+- **Product Contract** — H2 section containing Summary, Problem Frame,
+  Requirements, and product-scope subsections. Put Requirements under
+  `### Requirements` so review tools can distinguish Product Requirements
+  from implementation detail.
+- **Planning Contract** — H2 section for KTDs, high-level technical design,
+  assumptions, and sequencing.
+- **Summary / Problem Frame** — prose paragraphs.
+- **Requirements** — bullets with `R<N>.` prefix. When requirements span
+  more than one concern, grouping under bold inline headers is the default
+  shape, not optional polish (group by capability, not by discussion order);
+  render a flat list only when every requirement is about the same thing.
+  When requirements have status, traceability, or severity that warrant
+  additional columns, escalate to a table.
+- **Implementation Units** — H3 heading per unit with `U<N>.` prefix.
+  Fields (Goal, Files, Patterns, Test Scenarios, Verification) render as
+  bullets with bold leader labels, or as sub-headings if the field has
+  multi-paragraph content.
+- **Verification Contract / Definition of Done** — use tables when commands,
+  applicability, unit IDs, and done signals share a uniform shape. Name
+  concrete repo commands such as `bun test` rather than generic "run tests"
+  when the repo has known commands.
+- **Key Technical Decisions** — bullets with bold decision name + prose
+  rationale, or numbered KTD-N pattern when traceability matters. A
+  `session-settled:` annotation renders as part of the KTD bullet's
+  visible text, stem preserved verbatim.
+- **Key Flows / Acceptance Examples** — bullets with bold leader labels
+  (Trigger / Actors / Steps / Outcome / Covers / Given-When-Then).
+- **Scope Boundaries** — bullets, optionally split into "Deferred for
+  later" / "Outside this product's identity" sub-headings when the
+  positioning distinction matters.
+
+The agent picks more elaborate or simpler shapes based on what each
+specific artifact's content needs.
+
+## Diagrams
+
+When the section contract calls for a diagram (architecture, sequence,
+flowchart, state machine, swim lane, data-flow), markdown renders it as
+a fenced mermaid block:
+
+```markdown
+` ``mermaid
+flowchart TB
+  A[Start] --> B{Decision}
+  B -->|yes| C[Action]
+  B -->|no| D[Other action]
+` ``
+```
+
+(`TB` direction default — keeps diagrams narrow in source view and in
+narrow rendered viewports.)
+
+Markdown's diagram affordances are limited compared to HTML. For
+quantitative comparisons (bar charts, scatter plots) markdown has no
+native equivalent — use a table with the data and let prose or caption
+carry the interpretation. The richer visualization happens in the HTML
+rendering.
+
+For a **UI/layout shape** that would be a wireframe in HTML, markdown has
+no inline-SVG wireframe affordance. Render the region composition as a
+mermaid layout `flowchart` (or describe it in prose) — never hand-draw a
+box-drawing/ASCII wireframe; it violates the no-box-drawing-characters rule
+and reads poorly. The wireframe proper is an HTML-only affordance.
+
+## Inline code and code blocks
+
+- **Inline code** for identifiers (variable names, function names,
+  flag names, file paths, IDs that aren't section anchors).
+- **Fenced code blocks** with language tag for code, shell commands,
+  API request/response samples. Always specify the language for syntax
+  highlighting and accessibility.
+
+```markdown
+The flag `--cdp-url` accepts a URL.
+
+` ``bash
+browser-use --cdp-url http://localhost:9222
+` ``
+```
+
+## No process exhaust
+
+Engineering process metadata stays out of the artifact:
+
+- No "captured at Phase X" notes
+- No `## Next Steps` pointing to the next skill
+- No italic provenance lines ("*Brainstorm completed 2026-05-13*")
+- No engineering-flow shepherding ("Now read this file:", "Next, run that
+  command:")
+
+This information belongs in commit messages, tool output, and agent
+transcripts — not in the artifact a reader returns to weeks later.
+
+## Frontmatter shape
+
+Per-skill frontmatter fields are defined in each skill's section contract
+(`plan-sections.md` lists plan frontmatter; `brainstorm-sections.md` lists
+brainstorm frontmatter). Common rules:
+
+- YAML at the top of the file, delimited by `---` on its own line above
+  and below.
+- Field names in lowercase snake_case (`created_at`, `topic`, not
+  `CreatedAt`, `Topic`).
+- **No status / lifecycle field.** Artifacts are point-in-time records
+  (decision or discovery), not tracked work items. Do not introduce a
+  mutable `status` field or an `active → completed` lifecycle — whether
+  the work shipped is derived from git, not stored in the doc.
+- Stable across artifact revisions — never rename or repurpose a field.
+
+## Post-write audit
+
+Before declaring the markdown file written, scan it for these common
+slips:
+
+- All stable IDs are plain-prefix format, not bolded.
+- No HTML elements mixed in.
+- All file paths are repo-relative.
+- Horizontal rule separators between H2s (for Standard / Deep artifacts).
+- No process exhaust (Phase X notes, Next Steps pointers, provenance
+  lines).
+- Tables only where 5+ uniform-shape items justify them.
+- Frontmatter has all the per-skill required fields with reasonable values.

package/skills/ce-ideate/references/post-ideation-workflow.md

@@ -0,0 +1,167 @@
+# Post-Ideation Workflow
+
+Read this file after Phase 2 ideation agents return and the orchestrator has merged and deduped their outputs into a master candidate list. Do not load before Phase 2 completes.
+
+## Phase 3: Adversarial Filtering
+
+Review every candidate idea critically. Critique runs in two layers — a fresh-context verifier first, then orchestrator arbitration. Fresh-context verification outperforms self-critique: the orchestrator synthesized some of these candidates itself and carries the full generation history, so it is anchored in ways a verifier that never saw the generation is not.
+
+1. **Basis verification (one generation-tier sub-agent — see SKILL.md Model Tiers).** Dispatch a verifier whose payload is only the consolidated grounding summary (including the evidence gists and dossier file paths — it reads dossier files itself as needed) and the merged candidate list — none of the generation history. Prompt it to refute: for each candidate, check that the stated basis actually supports the claimed move, that `direct:` quotes exist where cited (spot-check by reading the file in repo mode), that `external:` prior art is real and relevantly analogous, that `reasoned:` arguments hold, and that the idea genuinely passes the meeting-test. It returns a per-candidate verdict (sound / weak / refuted) with a one-line reason. The verifier did not write the ideas, so its meeting-test judgment supersedes the generators' self-attestation. Under `go deep` (Phase 0.5), dispatch a second, ceiling-tier critic focused on novelty and feasibility with the same fresh-context payload.
+
+2. **Orchestrator arbitration.** The orchestrator makes the final cut, weighing verifier verdicts without being bound by them — overrule a verdict when evidence in context contradicts it, and say so in the rejection reason.
+
+If verifier dispatch fails (platform limits, errors), fall back to orchestrator-only filtering and note the degradation in the rejection summary.
+
+Do not generate replacement ideas in this phase unless explicitly refining.
+
+For each rejected idea, write a one-line reason.
+
+Rejection criteria:
+- too vague
+- not actionable
+- duplicates a stronger idea
+- not grounded in the stated context
+- too expensive relative to likely value
+- already covered by existing workflows or docs
+- interesting but better handled as a brainstorm variant, not a product improvement
+- **unjustified — no articulated basis** (sub-agent failed to provide `direct:`, `external:`, or `reasoned:` justification, or the stated basis does not actually support the claimed move)
+- **basis refuted by verification** (the verifier found a cited quote absent, prior art mischaracterized, or a reasoned argument unsound — and the orchestrator concurs)
+- **below ambition floor** (fails the meeting-test: would not warrant team discussion — except when Phase 0.5 detected tactical focus signals, in which case this criterion is waived)
+- **subject-replacement** (abandons or replaces the subject of ideation rather than operating on it — e.g., "pivot to an unrelated domain," "become a different organization")
+- **scope overrun** (expands beyond the asked scope rather than ideating within it — e.g., proposes changes to the whole product when the user asked about one flow, stage, or section). Allowed only when the basis explicitly justifies the expansion; default is reject or downgrade.
+
+Score survivors using a consistent rubric weighing: groundedness in stated context, **basis strength** (`direct:` > `external:` > `reasoned:`; none excluded, but direct-evidence ideas score higher all else equal), expected value, novelty, pragmatism, leverage on future work, implementation burden, overlap with stronger ideas, and **axis spread** (when Phase 1.5 produced an axis list) — survivor sets that cover the topic's surface outscore sets that cluster on one axis, all else equal.
+
+**Axis coverage as a list-level concern.** When axes were defined, axis spread is evaluated across the survivor set, not per-idea. After per-idea filtering, check the survivor set: if axis coverage is uneven and stronger candidates exist on under-represented axes, prefer the spread when promoting borderline candidates. Phase 2's recovery dispatch should already have surfaced candidates for empty axes; this is a polish step on the survivor selection. If an axis ends up with zero survivors despite recovery (or because recovery hit the 2-axis cap), note it in the rejection summary as a deliberate gap rather than an oversight.
+
+Target output:
+- keep 5-7 survivors by default
+- if too many survive, run a second stricter pass
+- if fewer than 5 survive, report that honestly rather than lowering the bar
+
+## Phase 4: Write and Present the Deliverable
+
+The ideation artifact is produced **automatically** — persistence is not opt-in. After filtering, write the deliverable, show a concise summary, and open it. The full content lives in the file; the session shows only an orienting summary, so the rich format is what the reader actually engages with.
+
+**Checkpoint B (V17).** Before writing the deliverable, write `<scratch-dir>/survivors.md` (absolute path from Phase 1) containing the survivor list plus key context (focus hint, grounding summary, rejection summary). Best-effort: if the write fails, log a warning and proceed; the checkpoint is not load-bearing. Reuses the same `<run-id>` / `<scratch-dir>` generated in Phase 1.
+
+### 4.1 Write the Deliverable (automatic, both modes)
+
+`OUTPUT_FORMAT` (resolved in SKILL.md Phase 0.0; default `html`) sets the extension. Write the file every run — do not wait for the user to ask.
+
+1. **Resolve the target directory and extension.**
+   - Extension follows `OUTPUT_FORMAT` (`.html` default, `.md` on override).
+   - **Repo mode:** ensure `docs/ideation/` exists (create if absent).
+   - **Elsewhere mode with `docs/ideation/` already present:** use it.
+   - **Otherwise (no repo, or elsewhere with no `docs/ideation/`):** write into the run's CE temp area — the `<scratch-dir>` resolved in Phase 1 (`<scratch-root>/ce-ideate/<run-id>/`). Do **not** write into the user's current working directory, and do **not** create a `docs/ideation/` tree for a subject unrelated to the repo. Announce the absolute path and note it is temporary (`/tmp` is cleared on reboot — move it to keep it).
+2. **Choose the file path:** `<dir>/YYYY-MM-DD-<topic>-ideation.<ext>` (or `<dir>/YYYY-MM-DD-open-ideation.<ext>` when no focus exists).
+3. **Load the section contract and rendering reference** (deferred from Phase 0.0): read `references/ideation-sections.md` and the format-rendering reference matching `OUTPUT_FORMAT` — `references/markdown-rendering.md` for `md`, `references/html-rendering.md` for `html`.
+4. **Write the document** per those references. `ideation-sections.md` defines the section contract (metadata, Grounding Context, Topic Axes, Ranked Ideas with per-idea fields, Rejection Summary); the rendering reference defines how the resolved format presents it. Content is identical across formats; only presentation differs.
+   - **On write failure** (no writable path, permissions): announce the failure and offer a custom path (validate writable; create parent dirs). Never lose the survivors silently.
+
+**Resume:** update the existing file in place, in its existing format (per SKILL.md Phase 0.1 format precedence); carry the prior ideas and rejection summary forward, adding to them rather than overwriting.
+
+### 4.2 Present a Concise Summary (not the full deliverable)
+
+The full cards, rationale, downsides, diagrams, and the rejection table live in the file. Do **not** reproduce them in the session — reprinting the whole deliverable as chat text defeats the rich format and leads the reader through plain text before they ever see it. Show a tight orientation instead:
+
+- One line with counts and the path: e.g. `Wrote 7 ranked ideas (36 raw, 13 cut) across 5 axes → <absolute path>`.
+- A ranked list, **one line per survivor**: `1. <Title> · <axis> · Conf <High/Med/Low> · Cx <S/M/L>`.
+- The top pick called out in a sentence.
+- Any axis with zero survivors noted in one line (the deliberate gap).
+
+This ranked list doubles as the index the user references when choosing an idea in Phase 5. Terminal-only readers still get a usable view; depth is one open away.
+
+### 4.3 Open It
+
+- **HTML:** in an interactive session, best-effort open the file in the browser via the platform's open primitive (`open` on macOS, `xdg-open` on Linux, `start` on Windows); always print the absolute path so it can be reopened or shared. Skip auto-open in headless / pipeline runs (no interactive surface).
+- **Markdown:** print the path. Proof (the markdown share surface) is reached through the Phase 5 menu — it is a network action, not auto-invoked.
+
+## Phase 5: Next Steps
+
+Ask what to do next using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Free-text answers are accepted.
+
+The deliverable already exists (Phase 4), so the menu is purely *what next* — there is no "save" step.
+
+**Stem:** "Your ideation is saved to `<path>`. What next?"
+
+Offer four options (self-contained labels with the distinguishing word front-loaded so they stay distinct when truncated). Option 1 is **format-keyed** — render exactly one of its two labels per run, matching `OUTPUT_FORMAT`:
+
+1. *(when `OUTPUT_FORMAT=html`)* **Open in browser** — open the saved HTML deliverable (re-open if it was already opened).
+   *(when `OUTPUT_FORMAT=md`)* **Publish to Proof** — publish the saved markdown to Proof and get a shareable link; one-way, the local file stays canonical.
+2. **Brainstorm one idea with `ce-brainstorm`** — commit a chosen idea to a requirements-only unified plan under `docs/plans/`; leaves ce-ideate. Asks which idea first.
+3. **Discuss or refine the ideas first** — stay here to think across the set before committing: adjust or interrogate one idea, compare several, or combine/merge them. Asks what you want to work on.
+4. **Done — keep the file and stop.**
+
+**Adjacent nudge (prose, not a slot):** "Don't want it kept? Say 'discard' and the agent deletes the file." Handled via free text (see §5.5); it is create-only and never deletes a resumed or pre-existing doc.
+
+If the user already named what they want to work on inline (e.g. "brainstorm the table tool", "tighten the highlighter idea", "merge the table and highlighter ideas"), skip the follow-up that asks what to work on for §5.2 / §5.3.
+
+### 5.1 Open in Browser (html) / Publish to Proof (md)
+
+- **HTML — Open in browser.** (Re)open the saved file via the platform primitive where available; otherwise print the absolute path. Return to the Phase 5 menu. No Proof — the HTML file is the canonical record.
+- **Markdown — Publish to Proof.** The local markdown file already exists (Phase 4) and stays canonical; Proof is a one-way published copy, not a sync target. Load the `ce-proof` skill to publish, passing:
+  - **source file:** the saved `.md` file from Phase 4.
+  - **doc title:** `Ideation: <topic>` or the doc's H1.
+  - **identity:** `ai:compound-engineering` / `Compound Engineering`.
+
+  ce-proof creates a shared Proof doc (Create and Share workflow) and returns the share URL. Surface it to the user, then return to the Phase 5 menu — nothing syncs back to disk. If the Proof handoff fails after the proof skill's internal retry plus one orchestrator-side retry (~2s pause, narrated as "Retrying Proof... attempt 2/2"), tell the user Proof is unavailable and that the local file is intact at `<path>`, then return to the menu — the deliverable was never at risk (it was written in Phase 4). *(If the user explicitly asked for Proof during an HTML run: Proof is markdown-only and cannot ingest HTML, so render a throwaway markdown copy of the survivors as the Proof source and do not upload the `.html`.)*
+
+### 5.2 Brainstorm One Idea
+
+1. **Identify the idea** by number or name (skip if the user already named it). Match against the ranked list from Phase 4.2.
+2. **Build a focused seed** from the idea's substance already in the orchestrator's context. Do **not** pass the whole file — wasteful and noisy (the other survivors, grounding, and rejection table are irrelevant to defining this one idea, and an HTML file carries CSS/SVG chrome). Do **not** pass only a file pointer — that forces `ce-brainstorm` to re-open and re-extract the idea the orchestrator already holds. The seed is feature-description-shaped:
+
+   > `<title> — <description>. Basis: <basis/evidence>. Why it matters: <rationale>. Known tradeoffs: <downsides>.`
+
+   The basis/evidence directly feeds `ce-brainstorm`'s product-pressure-test, so it won't re-derive what we already know. Append a one-line provenance pointer: `(Seeded from ce-ideate: <path>, idea "<title>")` — it records origin and lets brainstorm pull adjacent detail if it wants, without being forced to read anything.
+3. **Load the `ce-brainstorm` skill** with that seed. The saved file is already the record — no extra write step.
+
+**Repo mode only:** do **not** skip brainstorming and go straight to `ce-plan` — `ce-plan` wants a brainstorm-grounded Product Contract. In elsewhere modes, ideation is a legitimate terminal state; brainstorming is optional deeper development of one idea, not a required next rung on an implementation ladder that does not exist in these modes.
+
+### 5.3 Discuss or Refine the Ideas First
+
+This stays in ce-ideate — no skill handoff. It is the "think across the set before committing" step, and it is a normal, expected outcome of ideation: seeing several strong candidates and wanting to deliberate is more common than instantly committing one. The orchestrator still holds the full grounding and generation context, so it can reason across every survivor — this is where that context pays off. The work here is either **single-idea** (sharpen or interrogate one) or **cross-idea** (compare, combine, or merge several); do not force the user to name a single idea before they can engage.
+
+1. **Establish what the user wants to work on and how.** Infer from their phrasing when given; otherwise ask one open question ("What do you want to work on?") rather than assuming a single idea. The scope may be one idea, a subset, or the whole set.
+2. **Route by intent:**
+   - **Ask / compare** ("why High confidence?", "how does this compare to FigJam?", "which of these overlap?", "which two are closest?") — answer in conversation, grounded in the ideas' bases and the Phase 1 grounding. Spans one idea or many. **No file rewrite** unless the discussion yields a change the user wants captured.
+   - **Adjust** ("smaller scope", "drop the paste-import part", "reframe around X") — revise that idea's framing, scope, or basis as discussed, then **rewrite the saved file** so the deliverable stays current.
+   - **Deepen** ("expand the second-order effects") — extend an idea's analysis; capture into the file only if the user wants it kept.
+   - **Combine / merge** ("merge the table and highlighter ideas", "fold 2 into 5") — synthesize the named ideas into one: write a unified title, description, and basis that draws from each source idea (carry the strongest basis forward; union their evidence). On a file rewrite, **replace the merged source entries with the single combined entry** — do not leave the originals alongside the merge — and renumber the ranked list. Re-evaluate the combined idea's axis and confidence rather than copying one source's. Note the merge in the rejection summary if a source idea effectively drops out.
+3. **Rewrite only on change.** The file is rewritten only when idea content actually changes (adjust, deepen-and-keep, or merge) — Q&A and comparison alone do not churn it.
+4. **Return to the Phase 5 menu.** Typically the user next brainstorms a sharpened or merged idea (§5.2), discusses more, opens it, or finishes.
+
+### 5.4 Done
+
+The file is already written, so there is no save step.
+
+- **Inside a git repo:** offer to commit only the ideation doc (do not create a branch, do not push; if the user declines, leave it uncommitted).
+- **Temp-area or non-repo file:** skip the commit offer.
+
+Then narrate the path and end the session — do not return to the menu.
+
+### 5.5 Discard (free text)
+
+Only when the file was **created fresh this run**: delete it, confirm the deletion, and end. On a **resume** run (a pre-existing file was updated in place), do **not** delete — tell the user the existing doc at `<path>` remains and offer no destructive action. Discard is never a default; it fires only on an explicit request.
+
+Do not delete the run's scratch directory (`<scratch-dir>`) on completion — it holds the V15 web-research cache reused across run-ids by later ideation invocations in the same session (see `references/web-research-cache.md`), the Checkpoint A/B files, the evidence dossiers, and (in the no-repo case) the deliverable itself. OS handles eventual cleanup.
+
+## Quality Bar
+
+Before finishing, check:
+
+- the idea set is grounded in the stated context (codebase in repo mode; user-supplied context in elsewhere mode)
+- **every surviving idea has an articulated basis** (`direct:`, `external:`, or `reasoned:`) that actually supports the claimed move — speculation dressed as ambition was rejected, with reasons
+- load-bearing `direct:` bases were verified against the repo (or the supplied context) — by the generating agent's verification reads or the Phase 3 verifier — not taken on faith
+- **every surviving idea passes the meeting-test** unless Phase 0.5 detected tactical focus signals that waived the floor
+- **no surviving idea replaces the subject** rather than operating on it
+- when Phase 1.5 produced an axis list, the survivor set spreads across axes rather than clustering on one — and any axis with zero survivors is noted as a deliberate gap in the rejection summary, not silently absent
+- the candidate list was generated before filtering
+- the original many-ideas -> critique -> survivors mechanism was preserved
+- if sub-agents were used, they improved diversity without replacing the core workflow
+- every rejected idea has a reason
+- survivors are materially better than a naive "give me ideas" list
+- the deliverable was written automatically in both modes (Phase 4) — to `docs/ideation/` when present, else the CE temp area, never the user's CWD
+- the session showed a concise summary, not a reproduction of the full deliverable
+- acting on an idea routes to `ce-brainstorm` (with a substance seed, not the whole file), not directly to implementation