dsh-compound-engineering 0.0.0-stage → 0.1.1

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/issue-intelligence.md

@@ -0,0 +1,44 @@
+# Issue Intelligence (Phase 1, conditional)
+
+Read this when Phase 1 step 4 applies, that is, when issue-tracker intent was detected in Phase 0.2. `references/grounding.md` defines the four-step sequence (scan → fall back or scope → cluster → await). This file defines the payload of each call and how the scoping question is built.
+
+The lens works against whichever tracker is reachable — GitHub, Linear, or Jira. Probe by capability (a connector/MCP, a documented API, or a documented CLI), never by assuming a specific binary exists. A missing binary or env var is not proof the tracker is unreachable.
+
+## a. Scan call
+
+Read `references/agents/issue-intelligence-analyst.md` and dispatch a generic subagent seeded with that prompt, the focus hint, the `<scratch-dir>` resolved earlier in Phase 1, and the instruction that it is in **SCAN mode**.
+
+It probes tracker access, does one bounded fetch, persists that fetched set to `<scratch-dir>/issue-scan.json`, and returns the distribution, a signal count, and an ambiguity assessment. It does **not** cluster.
+
+The scan call may run alongside the other Phase 1 grounding agents.
+
+## b. Fallback markers
+
+Two outcomes end the lens before the cluster call. Both are warn-and-proceed — never block the run on them:
+
+- **First line is the `Issue analysis unavailable:` marker** (no reachable tracker) — log `"{that message}. Proceeding with standard ideation."` and continue with the remaining grounding.
+- **Fewer than 5 eligible issues** — note `"Insufficient issue signal for theme analysis"` and continue.
+
+In both cases Phase 2 falls back to the six-frame default fleet rather than the 4-agent issue-tracker fleet — and **a fallback re-derives only what the abandoned frame set determined, and never re-resolves anything else.** Carry forward Phase 0.5's **already-resolved** scaling state — which overrides ended up active *after* its collisions, plus the raw total or explicit survivor count. Do not re-read the prompt's raw signals: a `go deep` run that also said `quick wins` has already had tactical suppressed, and re-deriving from the raw signal would resurrect the waived floor and lowered volume on a maximum-depth run. Re-derive **only** the two values the frame count determined — the agent count and the per-frame split — because the frame set changes from at most 4 themes to the 6 defaults. Carrying the old agent count would leave 4 agents holding 6 frames, the packing this skill rejects; carrying the old per-frame volume would multiply a requested total by the new frame count. See the fleet variants in `references/divergent-ideation.md`. No scoping question is asked.
+
+## b. Scoping question (the orchestrator decides; at most one question)
+
+Read the scan's ambiguity assessment.
+
+**Auto-scope silently by default.** Compose the scope from focus hint → priority (when populated) → workflow-state → recency.
+
+Ask **one** blocking scoping question (per the asking rules in `references/grounding.md`) **only** on irreducible ambiguity: two or more coherent, materially-different scopes that no single deliberately-varied sample could fairly represent. Skip it entirely when the scan is unambiguous.
+
+Its options are the scan's distribution-derived slices plus an always-present **"analyze a representative sample of everything,"** so the user can decline to narrow. When the slices plus that option would exceed the platform's blocking-tool option cap (Codex `request_user_input` takes 2-3 explicit options; `AskUserQuestion` takes 4; DeepSeek Harness `ask_user_question` is uncapped), show the highest-mass slices that fit and fold the rest into the representative-sample option, or fall back to a numbered chat list. **Never drop the representative-sample option.**
+
+This is a grounding / subject-scoping question — the same kind as the Phase 0.2 subject gate ("what should the agent work on"), not a Phase 0.4 solution-constraint question. It counts toward the ≤3-question grain, and "Surprise me" stays available.
+
+## c. Cluster call
+
+Dispatch the analyst again in **CLUSTER mode**, passing the resolved scope **and the same `<scratch-dir>`** so it reuses the persisted `issue-scan.json` rather than re-fetching. It returns the leverage-ranked themes plus coverage accounting.
+
+## d. What consolidation must carry
+
+The consolidated grounding summary's `Issue intelligence` section carries the theme summaries (titles, descriptions, issue counts, leverage, trend directions) **and the cluster call's coverage accounting** — fetched / eligible / analyzed / excluded / unknown-remainder, with any `>N` lower bound. That accounting is the non-exhaustive-coverage disclosure; it has to reach Phase 2 ideation and the Phase 4 artifact rather than being dropped at consolidation.
+
+Themes become Phase 2 frames per the issue-tracker override in `references/divergent-ideation.md`.

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

@@ -0,0 +1,242 @@
+# 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>`. The only exception is a contract-defined invisible
+  semantic marker such as `<!-- ce-section: work-relationships -->`; it carries
+  section meaning for downstream agents and does not create layout. 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, means (only
+  when an approach is fixed), authority, execution profile, stop conditions, and who finishes the remaining work.
+- **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 `KTD<N>.` plain prefix (same
+  format as `R1.`/`U1.`) + bold decision name + prose rationale. Legacy
+  plans with unnumbered KTDs stay readable by label; do not renumber
+  existing numbered ones. 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/output-mode.md

@@ -0,0 +1,34 @@
+# Resolving the output mode
+
+Required read at Phase 0.0, before anything writes or resumes an ideation artifact. The ordinary-key cascade block lives in `SKILL.md` and is not repeated here.
+
+#### 0.0 Resolve Output Mode
+
+Determine `OUTPUT_FORMAT` for the ideation artifact this run might persist. Output mode is **exclusive** — the ideation doc is written as either HTML (`.html`) OR markdown (`.md`), never both. Precedence: in-prompt request > user-stated preference > config > default (`html`). There is no pipeline override: a headless or non-interactive run resolves the format by the same steps.
+
+Unlike `ce-plan` and `ce-brainstorm` (which default to `md`), ce-ideate defaults to **`html`** — ideation artifacts are read mainly by humans weighing candidate directions, and a rich self-contained HTML file makes the ideas easier to approach.
+
+**Read config.** Resolve `<repo-root>` with `git rev-parse --show-toplevel`, then apply the ordinary-key cascade block in `SKILL.md`. Read both files when they exist. If the root cannot be resolved, fall through to the defaults below.
+
+Resolution steps:
+
+1. **In-prompt request.** Reason over the user's prompt for this run for a request about *this document's* output format, expressed either as the `output:` shorthand or in plain language ("give me this as markdown", "I want a webpage"). On an explicit format, match it case-insensitively to `md`/`html`, and ignore the `output:` shorthand token when reading the rest of the prompt as the focus hint. Distinguish a request about the document's format from a format named as subject matter: "ideate on an HTML export feature" is the work, not a doc-format request — do not switch on it.
+   - `output:` alone (no value) → no-op, fall through to step 2.
+   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-ideation menu after final resolution: `Ignored unknown output: value '<value>' — using <resolved_format> instead.` where `<resolved_format>` is the value `OUTPUT_FORMAT` actually resolved to after the remaining precedence steps. Do not hardcode a format in the note — that misleads users when config or the default differs from what you assume.
+2. **User-stated preference.** If this prompt holds no format request, honor an output-format preference (markdown vs HTML) the user established earlier — earlier in this session, in your memory, or written into their active instructions — that is already in your context (match `md`/`html` case-insensitively). A remembered preference is more current than the rarely-edited config, so it **overrides** the config in step 3. Do not open or search instruction files to find it — act only on a preference already present in your context; if none is, fall through to the config.
+3. **Config.** If steps 1-2 did not resolve, apply the ordinary-key rule: first **active (non-commented)** `ideate_output:` in `config.local.yaml` then `config.yaml` matching `md` or `html` (case-insensitive) wins. Missing, invalid, or commented values continue to the next layer, then step 4. Critical: lines starting with `#` are YAML comments and must be ignored — the shipped config template includes a commented example like `# ideate_output: md` to document the option, and matching that as an active setting would silently override the default on every run without the user having opted in.
+4. **Default.** Otherwise `OUTPUT_FORMAT=html`.
+
+**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:` where applicable) are consumed and stripped. Other `<word>:<word>` tokens — including conventional commit prefixes like `feat:`, `fix:`, `chore:` that may appear inside a focus hint — pass through verbatim.
+
+**Defer loading the format-rendering reference.** The deliverable is written at Phase 4 (after generation), so `references/ideation-sections.md` and the format-rendering references (`markdown-rendering.md` / `html-rendering.md`) are only needed then — loading them at Phase 0.0 would carry them through the entire grounding and ideation dispatch for no benefit. Resolve `OUTPUT_FORMAT` now, but load the section contract and the matching rendering reference at write time (see `references/post-ideation-workflow.md` §4.1). The `output:` preference does NOT auto-propagate to `ce-brainstorm` on handoff — see §5.2 there.
+
+#### 0.1 Check for Recent Ideation Work
+
+Look in `<root>/ideation/` for ideation documents (`*.md` or `*.html`) created within the last 30 days. This is a repo-mode convenience: when there is no git repository or `<root>` fails to resolve, skip the scan and continue — do not fail the run before 0.3 classifies mode, since elsewhere and no-repo runs write to a temp area and never touch `<root>/ideation/`.
+
+A prior doc is relevant when its topic, path, or subsystem overlaps the requested focus, or the request is open-ended and one obvious recent open doc exists. Issue-grounded and non-issue ideations are distinct topics — never offer to resume across that line.
+
+If a relevant doc exists, ask whether to continue from it or start fresh. If continuing: read it, summarize what has already been explored, preserve the previous ideas and rejection summary, and update that file rather than creating a duplicate.
+
+**Write the update back in the existing file's format**, overriding the Phase 0.0 baseline. Resume precedence: explicit `output:` arg this run > resumed file's extension > config > default (`html`). An explicit `output:` that differs from the existing file switches format — write the new-format file and leave the original in place.