@xulthekl/team-flow 0.22.4

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

@@ -0,0 +1,241 @@
+# 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`, `prd-mapping.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.
+- **PRD sections use stable headings.** For PRD artifacts, render the 11
+  chapters with exact headings matching the PRD template: `## 一、版本修订记录`,
+  `## 二、业务流程一览`, `## 三、D7.1_业务流程`, `## 四、D7.2_画面原型及设计`,
+  `## 五、D7.3_报表清单`, `## 六、D7.4_业务术语字典`, `## 七、D7.5_系统功能清单`,
+  `## 八、D7.6_系统功能处理说明书`, `## 九、D7.7_要件定义自查报告`,
+  `## 十、D7.8_要件定义完成报告`, `## 十一、D7.9_评审会议纪`.
+  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.
+- **版本修订记录 is top-loaded.** It appears first in the PRD for fast
+  orientation — document metadata, iteration version, and revision history.
+
+## 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.
+
+- **版本修订记录 (§一)** — small table for document metadata (status,
+  version, author, date) and a revision-history table below.
+- **业务流程一览 (§二)** — table with L1–L4 process taxonomy columns,
+  stakeholders, value description, change type, and related systems.
+- **D7.1_业务流程 (§三)** — per-flow subsections with a mermaid flowchart
+  table, summary prose, and step-by-step explanation. Appendix table for
+  the full process ledger.
+- **D7.2_画面原型及设计 (§四)** — per-module subsections with prototype
+  tables (ID, screenshot, summary columns), screen migration tables, and
+  information-structure diagrams.
+- **D7.3_报表清单 (§五)** — table with report ID, linked flow/activity/task,
+  report type, and description. Appendix table for the full report ledger.
+- **D7.4_业务术语字典 (§六)** — table with term name, definition, part of
+  speech, synonyms, and source. Appendix table for the full term ledger.
+- **D7.5_系统功能清单 (§七)** — table with function ID, linked
+  flow/activity, function name, description, parent function, and change
+  type. Appendix table for the full function ledger.
+- **D7.6_系统功能处理说明书 (§八)** — the largest chapter: function
+  overview table, global notes (permissions, interactions, exceptions,
+  sorting, search, loading), hardware/network specs, per-module function
+  detail tables, non-functional requirements (performance, availability,
+  security), analytics tracking, and encoding rules.
+- **D7.7_要件定义自查报告 (§九)** — structured self-check tables across
+  nine categories (accounts/roles, data, state/interaction, hardware,
+  other, UX, product framework, flow design, reading experience) with
+  pass/fail/not-applicable checkboxes.
+- **D7.8_要件定义完成报告 (§十)** — project overview prose, requirements
+  achievement matrix, deliverable completeness table, self-check summary
+  table, project team table, deliverable handover table, next-steps table,
+  and section prose summary.
+- **D7.9_评审会议纪 (§十一)** — review record table with project info,
+  review content summary, attendee matrix with opinions, review findings
+  with countermeasures, and conclusion prose.
+
+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; `prd-mapping.md` maps brainstorm output to PRD
+chapters). 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-brainstorm/references/model-tiers.md

@@ -0,0 +1,9 @@
+# Model Tiers
+
+Read this when dispatching a sub-agent (the Phase 1.1 grounding scout, the Phase 2.6 claim verifier, or the opt-in Slack researcher). Sub-agent dispatch is tiered by task shape, never hardcoded to a model name:
+
+- **Extraction tier** — the grounding scout: retrieval and quoting work. Use the platform's cheapest capable model when the current harness exposes a known override. "Capable" is part of the spec — escalate to the generation tier when the repo is large or the stack obscure.
+- **Generation tier** — the claim verifier: evidence-driven mechanical verification. Use the platform's mid-tier model when the current harness exposes a known override. If model names are unknown, omit the override and inherit rather than guessing.
+- **Ceiling tier** — the dialogue itself. Questions, approaches, synthesis, and the requirements-only unified plan run in the main conversation on the orchestrator's model; nothing is dispatched for them.
+
+**Degradation rule.** When the platform's subagent primitive does not support per-agent model selection, dispatch the scout and verifier on the inherited model and keep their read budgets and output caps — cost control then comes from structure, not tiering. When the platform has no subagent primitive at all, do the topic scan inline at Phase 1.1 — still writing the grounding dossier to the scratch path, because downstream consumers (the Phase 2.6 verifier, the ce-plan handoff) receive that path — and verify claims inline before the Phase 3 write, with the same budgets.

package/skills/ce-brainstorm/references/prd-mapping.md

@@ -0,0 +1,71 @@
+# Brainstorm → PRD 章节映射
+
+ce-brainstorm 的对话流程收集的信息需要映射到 PRD 模板的 11 个章节。
+
+## 映射关系
+
+| PRD 章节 | 信息来源 | 填充策略 |
+|---|---|---|
+| 一、版本修订记录 | 元数据（日期、作者、版本、状态） | **自动填充**：从对话上下文提取日期、用户信息；版本/状态按下方「版本格式规范」填充，**文档状态必须与 frontmatter `frozen` 一致** |
+| 二、业务流程一览 | Phase 1.3 对话：用户/流程/系统交互 | **对话填充**：brainstorm 对话中收集的业务流程信息 |
+| 三、D7.1_业务流程 | Phase 1.3 对话：Key Flows | **对话填充**：从 brainstorm 的 Key Flows 映射 |
+| 四、D7.2_画面原型及设计 | Phase 1.3 对话：UI/交互需求 | **对话填充**：如涉及 UI，从对话中收集原型信息 |
+| 五、D7.3_报表清单 | Phase 1.3 对话 | **占位保留**：brainstorm 不涉及报表细节，保留模板占位符 |
+| 六、D7.4_业务术语字典 | Phase 1.3 对话 + CONCEPTS.md | **部分填充**：从对话中提取的领域术语，其余保留占位符 |
+| 七、D7.5_系统功能清单 | Phase 1.3 对话：Requirements | **对话填充**：从 brainstorm 的 Requirements 映射 |
+| 八、D7.6_系统功能处理说明书 | Phase 1.3 对话：Key Decisions + Constraints | **部分填充**：权限/交互/异常等从对话收集，硬件/网络保留占位符 |
+| 九、D7.7_要件定义自查报告 | 自动 | **占位保留**：这是 BA 自查工具，brainstorm 阶段不填充 |
+| 十、D7.8_要件定义完成报告 | 自动 | **占位保留**：这是完成态产物，brainstorm 阶段不填充 |
+| 十一、D7.9_评审会议纪 | 自动 | **占位保留**：这是评审产物，brainstorm 阶段不填充 |
+
+## 关键映射规则
+
+1. **brainstorm 对话中没有信息的章节保留模板占位符**，不硬填
+2. **版本修订记录（§1）** 从元数据自动填充：日期、撰写人（如可获取）
+3. **业务流程（§2-§3）** 从 brainstorm 的 Key Flows 和 Actors 映射
+4. **画面原型（§4）** 仅在 brainstorm 涉及 UI 时填充
+5. **业务术语（§6）** 从对话中提取已定义的领域术语
+6. **系统功能（§7-§8）** 从 Requirements 和 Key Decisions 映射
+7. **自查/完成/评审（§9-§11）** 全部保留占位符，由后续流程填充
+
+## 迭代版本（vN）
+
+- `prd/vN/` 中的 N 是产品迭代版本（v1=MVP, v2=扩展），不是文档版本
+- ce-brainstorm 启动时扫描 `prd/` 目录检测已有迭代
+- 自动建议最新迭代或创建新迭代，用户确认后继续
+- 每个迭代目录下只有一个 `prd.md` 文件
+
+## 版本格式规范（v0.8 新增，修复格式不统一 BUG）
+
+> **背景**：曾出现 frontmatter `iteration_version: v1`/`frozen: true`，正文却写「产品版本 v1.0」「文档状态 编辑中」——格式两套且状态自相矛盾。本节钉死格式，写入时自检。
+
+**两层版本号，分工明确**：
+
+| 字段 | 位置 | 格式 | 含义 | 递增时机 |
+|------|------|------|------|---------|
+| `iteration_version` | frontmatter | `vN`（v1/v2/…） | **产品迭代版本** | 仅新迭代/新用户故事（vN+1）|
+| 产品版本 | 正文 §1.1 版本信息 | `vN.M`（v1.0/v1.1/…） | **文档修订次版本** | vN 内每次修订递增 M（呼应反馈环路「vN 内修订不升版」）|
+
+- vN 内修订（S3→S2 回退修订）→ 只递增正文 `vN.M` 的 M，**frontmatter `iteration_version` 不变**，并在 §1.2 修订记录追加一行 + 「决策与变更履历」章节记录。
+- 新迭代 → frontmatter `iteration_version` 升 vN+1，正文产品版本重置为 `v(N+1).0`，新建 `prd/v(N+1)/` 目录。
+
+**文档状态枚举（§1.1）——必须与 frontmatter `frozen` 一致**：
+
+| 文档状态 | frontmatter | 含义 |
+|---------|-------------|------|
+| `编辑中` | 无 `frozen` 或 `frozen: false` | 仍在编写/对话中 |
+| `已冻结-下游` | `frozen: true`（默认）| `frozen_downstream`：下游不可直接改，可经 S3→S2 回退在 vN 内修订 |
+| `已冻结-绝对` | `frozen: absolute` | `frozen_absolute`：任何修改必须升版 vN+1 |
+
+> **一致性硬约束**：frontmatter `frozen: true` 时，正文文档状态**不得**为「编辑中」。PRD 写入/冻结时自检，不一致即修正。
+
+## 冻结声明（v0.8 新增，修复冻结措辞 BUG）
+
+PRD 冻结时（`frozen_downstream`），在正文标题下方插入冻结声明 blockquote。**措辞必须区分双层冻结，不得写"升版 v2"**（那是 `frozen_absolute` 语义，违反反馈环路设计）：
+
+```markdown
+> **本文档已于 {YYYY-MM-DD} 冻结**（`frozen_downstream`，经原型循环验证 + 人工评审通过）。
+> 下游阶段（plan/spec/build）**不可直接修改**；如 plan 或实施暴露 scope 问题，经 **S3→S2 回退在 vN 内修订**并记录「决策与变更履历」（不升版）。
+> 仅当**启动新迭代 vN+1** 或**用户显式绝对冻结**（`frozen_absolute`）时，才需升版。
+```
+

package/skills/ce-brainstorm/references/product-pressure-test.md

@@ -0,0 +1,42 @@
+# Product Pressure Test — rigor-gap lenses
+
+Read this at Phase 1.2, before generating approaches. This is agent-internal analysis, not a user-facing checklist. Read the opening, note which gaps actually exist, and raise only those as questions during Phase 1.3 — folded into the normal flow of dialogue, not fired as a pre-flight gauntlet. A fuzzy opening may earn three or four probes; a concrete, well-framed one may earn zero because no scope-appropriate gaps were found.
+
+Match depth to the Phase 0.3 scope.
+
+## Lightweight
+
+- Is this solving the real user problem?
+- Are we duplicating something that already covers this?
+- Is there a clearly better framing with near-zero extra cost?
+
+## Standard — scan for these gaps
+
+- **Evidence gap.** The opening asserts want or need, but doesn't point to anything the would-be user has already done — time spent, money paid, workarounds built — that would make the want observable. When present, ask for the most concrete thing someone has already done about this.
+
+- **Specificity gap.** The opening describes the beneficiary at a level of abstraction where the agent couldn't design without silently inventing who they are and what changes for them. When present, ask the user to name a specific person or narrow segment, and what changes for that person when this ships.
+
+- **Counterfactual gap.** The opening doesn't make visible what users do today when this problem arises, nor what changes if nothing ships. When present, ask what the current workaround is, even if it's messy — and what it costs them.
+
+- **Attachment gap.** The opening treats a particular solution shape as the thing being built, rather than the value that shape is supposed to deliver, and hasn't been examined against smaller forms that might deliver the same value. When present, ask what the smallest version that still delivers real value would look like.
+
+Plus these synthesis questions — not gap lenses, product-judgment the agent weighs in its own reasoning:
+- Is there a nearby framing that creates more user value without more carrying cost? If so, what complexity does it add?
+- Given the current project state, user goal, and constraints, what is the single highest-leverage move right now: the request as framed, a reframing, one adjacent addition, a simplification, or doing nothing?
+
+Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling. Use the result to sharpen the conversation, not to bulldoze the user's intent.
+
+## Deep — Standard lenses and synthesis questions plus
+
+- Is this a local patch, or does it move the broader system toward where it wants to be?
+
+## Deep — product — Deep plus
+
+- **Durability gap.** The opening's value proposition rests on a current state of the world that may shift in predictable ways within the horizon the user cares about. When present, ask how the idea fares under the most plausible near-term shifts — and push past rising-tide answers every competitor could make.
+
+- What adjacent product could we accidentally build instead, and why is that the wrong one?
+- What would have to be true in the world for this to fail?
+
+These questions force an explicit product thesis and feed the Scope Boundaries subsections ("Deferred for later" and "Outside this product's identity") and Dependencies / Assumptions in the Product Contract.
+
+Phase 1.3 owns how these gaps fire as probes: each scope-appropriate gap found here becomes a separate open-ended probe (the "when present, ask..." line is the probe), surfaced progressively but all probed before Phase 2.

package/skills/ce-brainstorm/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-brainstorm/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.